Skip to content

Orchestrator refinement#20

Merged
devzeebo merged 12 commits into
mainfrom
orchestrator-refinement
May 18, 2026
Merged

Orchestrator refinement#20
devzeebo merged 12 commits into
mainfrom
orchestrator-refinement

Conversation

@devzeebo

Copy link
Copy Markdown
Owner

No description provided.

@coderabbitai

coderabbitai Bot commented May 18, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Rate limit exceeded

@devzeebo has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 45 minutes and 58 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 04c62bc1-ef66-4859-9f74-feebcfaddb2c

📥 Commits

Reviewing files that changed from the base of the PR and between 7f9e145 and 05929e3.

📒 Files selected for processing (8)
  • Makefile
  • orchestrator/packages/engine/src/test-engine.ts
  • orchestrator/packages/orchestrator/src/agent-helper.ts
  • orchestrator/packages/orchestrator/src/core/orchestrator.ts
  • orchestrator/packages/orchestrator/src/orchestrator-class.ts
  • orchestrator/packages/task-source-bifrost/src/bifrost-task-source.ts
  • orchestrator/packages/task-source-memory/package.json
  • orchestrator/publish.js
📝 Walkthrough

Walkthrough

This PR refactors the orchestrator architecture by introducing session-based engine execution, replacing shell-based hooks with in-memory function-based hooks, removing the @bifrost-ai/core package, restructuring the orchestrator as a wired class, and standardizing all packages to version 0.0.0 with controlled publishing. The core flow shifts from CLI-driven orchestration to a class-based model where tasks are watched, routed to agents via hooks, and executed with session continuity.

Changes

Session-Based Engine Execution

Layer / File(s) Summary
Engine interface and type contracts
orchestrator/packages/engine/src/interface.ts, orchestrator/packages/engine/src/types.ts
Engine.execute() accepts an optional sessionId parameter for session continuations; EngineContext and EngineResult types gain instructions and sessionId fields.
TestEngine session management
orchestrator/packages/engine/src/test-engine.ts, orchestrator/packages/engine/src/test-engine.spec.ts
TestEngine tracks sessions via #currentSessionId, determines follow-up calls when sessionId is provided, and returns sessionId in results; sendFollowUp() method is removed.
ClaudeCodeEngine session refactor
orchestrator/packages/engine-claude-code/src/claude-code-engine.ts, orchestrator/packages/engine-claude-code/src/claude-code-engine.spec.ts
buildPrompt now accepts options objects; execute() takes optional sessionId to resume Claude sessions; class-persisted sessions are replaced with local returnedSessionId.

In-Memory Hook Architecture

Layer / File(s) Summary
Hook type system and contracts
orchestrator/packages/orchestrator/src/core/types.ts
New types define HookResult with outcome/message, HookExecutionContext with state accessors, HookFn and HookSpec for hook functions, and agent-level AgentDefinition, Template, Hooks.
Hook executor implementation
orchestrator/packages/orchestrator/src/core/hook-executor.ts, orchestrator/packages/orchestrator/src/core/hook-executor.spec.ts
New executeHooks() runs hooks sequentially, collects outcomes, stops on fatal or thrown errors, with tests covering execution order, outcomes, errors, and state propagation.
Agent parser and hook removal
orchestrator/packages/orchestrator/src/core/agent-parser.ts, orchestrator/packages/orchestrator/src/core/agent-parser.spec.ts
Agent parser now returns empty hook arrays regardless of AGENT.md content; hook parsing and related tests are removed.

Orchestrator Class and API Restructure

Layer / File(s) Summary
Orchestrator class and helpers
orchestrator/packages/orchestrator/src/orchestrator-class.ts, orchestrator/packages/orchestrator/src/agent-helper.ts
New Orchestrator class wires task source and engine, registers agents, and watches tasks; agent-helper.ts provides loadAgent() with deep-merge utility.
orchestrate() function with state and sessions
orchestrator/packages/orchestrator/src/core/orchestrator.ts
orchestrate() tracks task state via currentTaskState, passes state through hook context and engine context, manages sessionId across follow-ups, and branches on hook outcomes.
Main index.ts as barrel module
orchestrator/packages/orchestrator/src/index.ts
Converted from CLI entrypoint to pure re-export barrel that delegates to core/*, orchestrator-class, and agent-helper.
Orchestrator tests
orchestrator/packages/orchestrator/src/core/orchestrator.spec.ts
Tests rewritten to use inline function-based hooks, validate task state propagation, session continuation, follow-up loops, and hook short-circuiting.

Core Package Removal

Layer / File(s) Summary
@bifrost-ai/core deletion
orchestrator/packages/core/*
Entire @bifrost-ai/core package including shell-based hook executor, repo-installer, types, config, and tests is removed; functionality migrates to orchestrator.

Package Structure and Publishing

Layer / File(s) Summary
Version and file list updates
orchestrator/package.json, orchestrator/packages/*/package.json
All packages updated to version 0.0.0 and include files: ["dist"] to restrict published contents.
Publish automation script
orchestrator/publish.js
New script automates building and publishing multiple @bifrost-ai packages in dependency order with version bumping, temporary prerelease versioning, and rollback on failure.
Project configuration
orchestrator/tsconfig.json, orchestrator/packages/orchestrator/tsconfig.json
Top-level and package tsconfig files updated to reference orchestrator, engine-claude-code, task-source-bifrost instead of cli and core.

Logging and Diagnostics

Layer / File(s) Summary
BifrostTaskSource logging
orchestrator/packages/task-source-bifrost/src/bifrost-task-source.ts
Console logging added for startup configuration, poll loop activity, iteration progress, and error handling.
Configuration cleanup
oxlint.config.ts, .vscode/settings.json
Global no-await-in-loop rule disabled; VS Code dist exclusion commented out.

Possibly related PRs

  • devzeebo/bifrost#19: Introduces the hook-executor.ts implementation with executeHooks and hook types that this PR's previous code removal deleted, so these PRs form a pair of architectural changes.
🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'Orchestrator refinement' is vague and generic, using a non-descriptive term that doesn't convey specific details about the changeset. Use a more specific title that describes the main architectural change, such as 'Remove hook execution from core and relocate to orchestrator package' or 'Refactor engine session handling and hook execution flow'.
Description check ❓ Inconclusive No pull request description was provided by the author, making it impossible to assess whether any description relates to the changeset. Add a pull request description explaining the key architectural changes, such as moving hook execution responsibility, refactoring session management, and removing deprecated functionality.
✅ Passed checks (3 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
orchestrator/packages/task-source-memory/package.json (1)

3-7: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add a publish whitelist for this package.

Line 3 updates version, but this manifest still has no files restriction. That can unintentionally publish non-build artifacts.

📦 Proposed fix
 {
   "name": "`@bifrost-ai/task-source-memory`",
   "version": "0.0.0",
   "description": "In-memory task source implementation for Orchestrator Framework",
   "type": "module",
+  "files": [
+    "dist"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@orchestrator/packages/task-source-memory/package.json` around lines 3 - 7,
The package manifest lacks a publish whitelist which can publish
source/artifacts unintentionally; update the package.json for the
task-source-memory package to add a "files" array that explicitly whitelists the
build output (e.g., "dist/") and other necessary artifacts (like "package.json",
"README.md", "LICENSE") and remove or avoid publishing dev-only files; modify
the package.json (referencing the existing "main" and "types" fields) to include
this "files" field so only intended files are published.
orchestrator/packages/orchestrator/src/core/orchestrator.ts (1)

107-145: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Check engineResult.success before completing the task.

The engine result status is never checked. When execute() returns success: false, the code still calls taskSource.completeTask() and returns {outcome: "completed"}. Additionally, the skipFulfill flag is ignored. The task should fail or be handled differently if the engine execution was unsuccessful.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@orchestrator/packages/orchestrator/src/core/orchestrator.ts` around lines 107
- 145, After calling engine.execute and before executing post-task hooks, check
engineResult.success; if it's false then do not proceed to complete the task or
run fulfillment logic: call taskSource.failTask(task.id, `Engine execution
failed: ${engineResult.error ?? "unknown"}`) and return { outcome: "failed",
error: engineResult.error } unless skipFulfill is true, in which case skip both
fail/complete calls and return { outcome: "skipped", error: engineResult.error }
so the skipFulfill flag is respected; update references in this flow to
engineResult, engine.execute, skipFulfill, and taskSource.failTask /
taskSource.completeTask accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@orchestrator/packages/engine/src/test-engine.ts`:
- Around line 58-62: The current logic reuses a previous this.#currentSessionId
when sessionId is omitted; change it so any call without an explicit sessionId
always mints a new session id (e.g., this.#currentSessionId =
`test-session-${Date.now()}`) instead of conditional on the existing value;
update the three occurrences that reference this.#currentSessionId/sessionId
(the block shown and the other occurrences noted at lines 64 and 73) so omission
means "fresh session" rather than "reuse previous."

In `@orchestrator/packages/orchestrator/src/agent-helper.ts`:
- Around line 37-45: The loadAgent function merges in the wrong direction:
deepMerge(agent ?? {}, definition) makes the parsed definition override
caller-provided fields; change the merge to have definition as the base and
agent applied second (e.g., call deepMerge(definition, agent ?? {})) so caller
overrides like name, promptBody, and hooks take precedence; update code around
loadAgent and ensure parseAgentDefinition and AgentDefinition types are
unchanged.

In `@orchestrator/packages/orchestrator/src/core/orchestrator.ts`:
- Around line 100-104: The loop currently pre-decrements maxFollowUps (let
maxFollowUps = 10; while ((maxFollowUps -= 1) > 0) { ... }) so when all Stop
hooks keep returning "follow-up" the code falls through and calls
completeTask(), incorrectly reporting success; change the loop to use a proper
attempt counter (e.g., while (maxFollowUps-- > 0) or loop with attemptsUsed++
and compare) and after the loop detect exhaustion and return a halted/failure
outcome instead of calling completeTask(); update the same pattern wherever
maxFollowUps is pre-decremented (the duplicate blocks handling Stop hook
"follow-up") to reference maxFollowUps and completeTask() and ensure exhausted
branches call the halted/fail path.

In `@orchestrator/packages/orchestrator/src/orchestrator-class.ts`:
- Around line 39-53: The loop in run() over this.taskSource.watchTasks()
currently lets any rejection from orchestrate(...) escape and terminate the
for-await loop; wrap the per-task processing in a try/catch so each task is
handled independently: inside the try call orchestrate({ task, agent,
taskSource: this.taskSource, engine: this.engine, projectDir: process.cwd() })
and log the success path, and in the catch call
this.taskSource.failTask(task.id, <error message or stack>) (or similar) to mark
the task failed, then continue the loop; ensure you still handle the
unknown-agent branch as before (this.agents.get(task.agentId) and failTask for
unknown agent).

In `@orchestrator/packages/task-source-bifrost/src/bifrost-task-source.ts`:
- Around line 64-70: The poll loop in bifrost-task-source.ts currently emits
console.log every iteration using pollCount and pollInterval which creates noisy
logs; change the logging so it only logs on meaningful state changes or at a
sampled interval (e.g., every Nth poll or when debug mode flag is enabled) and
suppress per-iteration messages otherwise. Locate the while (true) poll loop
that increments pollCount and remove or guard the two per-iteration console.log
calls (the poll header and rune-count log) to only run when (a) pollCount %
SAMPLE_RATE === 0, (b) a detected state change occurs, or (c) a DEBUG/verbose
flag is true; keep pollCount and pollInterval logic but add a configurable
SAMPLE_RATE or debug check to control emission. Ensure you update any
tests/logging docs and use consistent logging API (replace console.log with the
existing logger if one exists) so that only sampled or state-change logs are
emitted.
- Around line 41-45: The unconditional console.log of bifrostConfig.url and
bifrostConfig.realm can leak sensitive endpoint metadata; update the logging in
bifrost-task-source.ts (the lines referencing bifrostConfig.url,
bifrostConfig.realm and this.#config.*) to either (a) only emit full URL/realm
when a debug flag is enabled (e.g., this.#config.debug or a
logger.isDebugEnabled check) or (b) redact/mask sensitive parts (host, path,
token query) before logging and always keep pollInterval/maxPollInterval as
non-sensitive. Implement the chosen approach where the current console.log calls
occur so sensitive values are not printed in normal runs.

In `@orchestrator/publish.js`:
- Around line 46-47: Replace all uses of shell-interpolated execSync with
child_process.execFileSync and pass command and arguments as an array to avoid
shell parsing; specifically, swap execSync calls (referenced as execSync in
publish.js) for execFileSync from the child_process module, invoke npm with
arguments like ["version","patch","--no-git-tag-version"] instead of a single
concatenated string, and for the case that uses currentVersion (the execSync
that previously interpolates currentVersion) pass currentVersion as an argument
element rather than injecting it into a shell string; also remove any
unnecessary shell: "/usr/bin/bash" options and ensure stdio is forwarded (e.g.,
stdio: "inherit") so the behavior remains the same.

---

Outside diff comments:
In `@orchestrator/packages/orchestrator/src/core/orchestrator.ts`:
- Around line 107-145: After calling engine.execute and before executing
post-task hooks, check engineResult.success; if it's false then do not proceed
to complete the task or run fulfillment logic: call taskSource.failTask(task.id,
`Engine execution failed: ${engineResult.error ?? "unknown"}`) and return {
outcome: "failed", error: engineResult.error } unless skipFulfill is true, in
which case skip both fail/complete calls and return { outcome: "skipped", error:
engineResult.error } so the skipFulfill flag is respected; update references in
this flow to engineResult, engine.execute, skipFulfill, and taskSource.failTask
/ taskSource.completeTask accordingly.

In `@orchestrator/packages/task-source-memory/package.json`:
- Around line 3-7: The package manifest lacks a publish whitelist which can
publish source/artifacts unintentionally; update the package.json for the
task-source-memory package to add a "files" array that explicitly whitelists the
build output (e.g., "dist/") and other necessary artifacts (like "package.json",
"README.md", "LICENSE") and remove or avoid publishing dev-only files; modify
the package.json (referencing the existing "main" and "types" fields) to include
this "files" field so only intended files are published.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 89adf1be-720c-47c9-8f5e-f69c1d382beb

📥 Commits

Reviewing files that changed from the base of the PR and between 7f9ce47 and 7f9e145.

⛔ Files ignored due to path filters (1)
  • orchestrator/package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (49)
  • .vscode/settings.json
  • orchestrator/package.json
  • orchestrator/packages/core/package.json
  • orchestrator/packages/core/src/hook-executor.spec.ts
  • orchestrator/packages/core/src/hook-executor.ts
  • orchestrator/packages/core/src/repo-installer.spec.ts
  • orchestrator/packages/core/src/repo-installer.ts
  • orchestrator/packages/core/src/types.ts
  • orchestrator/packages/core/tsconfig.json
  • orchestrator/packages/core/vite.config.ts
  • orchestrator/packages/engine-claude-code/package.json
  • orchestrator/packages/engine-claude-code/src/claude-code-engine.spec.ts
  • orchestrator/packages/engine-claude-code/src/claude-code-engine.ts
  • orchestrator/packages/engine/package.json
  • orchestrator/packages/engine/src/interface.spec.ts
  • orchestrator/packages/engine/src/interface.ts
  • orchestrator/packages/engine/src/test-engine.spec.ts
  • orchestrator/packages/engine/src/test-engine.ts
  • orchestrator/packages/engine/src/types.ts
  • orchestrator/packages/orchestrator/package.json
  • orchestrator/packages/orchestrator/src/agent-helper.ts
  • orchestrator/packages/orchestrator/src/config.spec.ts
  • orchestrator/packages/orchestrator/src/config.ts
  • orchestrator/packages/orchestrator/src/core/agent-parser.spec.ts
  • orchestrator/packages/orchestrator/src/core/agent-parser.ts
  • orchestrator/packages/orchestrator/src/core/handlebars-renderer.spec.ts
  • orchestrator/packages/orchestrator/src/core/handlebars-renderer.ts
  • orchestrator/packages/orchestrator/src/core/hook-executor.spec.ts
  • orchestrator/packages/orchestrator/src/core/hook-executor.ts
  • orchestrator/packages/orchestrator/src/core/index.ts
  • orchestrator/packages/orchestrator/src/core/orchestrator.spec.ts
  • orchestrator/packages/orchestrator/src/core/orchestrator.ts
  • orchestrator/packages/orchestrator/src/core/types.ts
  • orchestrator/packages/orchestrator/src/core/validator.spec.ts
  • orchestrator/packages/orchestrator/src/core/validator.ts
  • orchestrator/packages/orchestrator/src/git-root.spec.ts
  • orchestrator/packages/orchestrator/src/git-root.ts
  • orchestrator/packages/orchestrator/src/index.spec.ts
  • orchestrator/packages/orchestrator/src/index.ts
  • orchestrator/packages/orchestrator/src/orchestrator-class.ts
  • orchestrator/packages/orchestrator/tsconfig.json
  • orchestrator/packages/task-source-bifrost/package.json
  • orchestrator/packages/task-source-bifrost/src/bifrost-task-source.ts
  • orchestrator/packages/task-source-memory/package.json
  • orchestrator/packages/task-source-memory/src/memory-task-source.ts
  • orchestrator/packages/task-source/package.json
  • orchestrator/publish.js
  • orchestrator/tsconfig.json
  • oxlint.config.ts
💤 Files with no reviewable changes (15)
  • orchestrator/packages/core/package.json
  • orchestrator/packages/core/src/repo-installer.ts
  • orchestrator/packages/orchestrator/src/config.ts
  • orchestrator/packages/orchestrator/src/git-root.ts
  • orchestrator/packages/task-source-memory/src/memory-task-source.ts
  • orchestrator/packages/core/src/types.ts
  • orchestrator/packages/core/vite.config.ts
  • orchestrator/packages/orchestrator/src/config.spec.ts
  • orchestrator/packages/core/src/repo-installer.spec.ts
  • orchestrator/packages/core/src/hook-executor.ts
  • orchestrator/packages/core/src/hook-executor.spec.ts
  • orchestrator/packages/orchestrator/src/git-root.spec.ts
  • orchestrator/packages/orchestrator/src/index.spec.ts
  • orchestrator/packages/orchestrator/src/core/index.ts
  • orchestrator/packages/core/tsconfig.json

Comment thread orchestrator/packages/engine/src/test-engine.ts
Comment thread orchestrator/packages/orchestrator/src/agent-helper.ts Outdated
Comment thread orchestrator/packages/orchestrator/src/core/orchestrator.ts Outdated
Comment thread orchestrator/packages/orchestrator/src/orchestrator-class.ts
Comment thread orchestrator/packages/task-source-bifrost/src/bifrost-task-source.ts Outdated
Comment thread orchestrator/publish.js Outdated
@devzeebo devzeebo merged commit 71abe54 into main May 18, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant