unify orchestrator v2 execution model under work item terminology - #44
Merged
Conversation
Merge interfaces-task and interfaces-task-source into @bifrost-ai/interfaces-work. Replace the split Task/Script concepts with WorkItem instances and WorkItemHandlers. Handlers receive the work item and an execution context separately; RPC methods and runner registration APIs use the same vocabulary. Reserve "task" for the LLM task agent (kind: "task").
Contributor
|
Warning Review limit reached
Next review available in: 23 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthroughThis PR renames the "task/script" execution model to a "work item" model across orchestrator-v2. It replaces ChangesTask → Work Item Rename
Sequence Diagram(s)sequenceDiagram
participant Orchestrator
participant Dispatcher
participant Runner
participant WorkItemSource
Orchestrator->>Dispatcher: dispatchWorkItem(workItem)
Dispatcher->>Runner: RPC dispatch(workItem)
Runner->>Runner: executeWorkItem(handler, workItem, ctx)
Runner->>Orchestrator: workItem.complete / workItem.fail / workItem.pause
Runner->>Orchestrator: workItemSource.setState(workItemId, state)
Orchestrator->>WorkItemSource: completeWorkItem / failWorkItem / pauseWorkItem / setState
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 10
🧹 Nitpick comments (2)
orchestrator-v2/packages/runner/src/work-item-execution-context.ts (1)
1-6: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsolidate duplicate import from the same module.
WorkItemis imported in a separate statement (line 6) right after anotherimport typefrom the identical module (lines 1-5). Merge into a single import.♻️ Proposed fix
import type { DataRegistry, + WorkItem, WorkItemExecutionContext, WorkItemHandler, } from "`@bifrost-ai/interfaces-work`"; -import type { WorkItem } from "`@bifrost-ai/interfaces-work`";🤖 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-v2/packages/runner/src/work-item-execution-context.ts` around lines 1 - 6, The imports in work-item-execution-context are split across two separate import type statements from the same module, which should be consolidated. Merge WorkItem into the existing `@bifrost-ai/interfaces-work` import alongside DataRegistry, WorkItemExecutionContext, and WorkItemHandler so there is only one type import from that module.orchestrator-v2/docs/script-tasks.md (1)
1-1: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRename
script-tasks.mdto match the work-item terminologyThe file content is now entirely about the work-item model, while
script-tasks.mdstill reflects the old naming. Update the links indocs/README.md,docs/agent-3-task.md,docs/agent-4-workflow.md, anddocs/runner.mdwith the rename.🤖 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-v2/docs/script-tasks.md` at line 1, Rename the documentation file to use the work-item terminology instead of the old script-task name, and update every reference to it in docs/README.md, docs/agent-3-task.md, docs/agent-4-workflow.md, and docs/runner.md. Make sure the links and any mentions of script-tasks.md now point to the new filename consistently across the docs.
🤖 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-v2/docs/agent-4-workflow.md`:
- Around line 211-213: The Task source reference in the workflow docs points to
a missing page, so update that link to the existing package documentation or
remove the bullet entirely. Fix the markdown in the agent-4-workflow document
near the Task Agent, Script tasks, and Task source list so the Task source entry
targets a valid docs location and no broken link remains.
In `@orchestrator-v2/docs/orchestrator.md`:
- Around line 44-60: The documentation still uses the old task-based names in
the ResultHandler and dispatch-lifecycle sections. Update the orchestrator docs
to rename `task.fail` to `workItem.fail`, `task.pause` to `workItem.pause`, and
`workItemSource.failTask` to `workItemSource.failWorkItem`, keeping the wording
aligned with the existing RPC naming scheme used elsewhere in the repo.
- Line 17: The orchestrator docs still reference the stale WorkItemSource method
name `watchTasks()`. Update the documentation entry that describes streaming
tasks to use the correct symbol `watchWorkItems()` so it matches the actual
`WorkItemSource` API and the README/test-helpers naming consistently.
In `@orchestrator-v2/docs/README.md`:
- Line 22: The architecture diagram node label still mixes old and new task
terminology, so update the Mermaid label in the README to use the same work-item
naming as the RPC methods below. In the diagram entry currently labeled with
completeWorkItem / failTask / pauseTask, rename the latter two parts to
failWorkItem and pauseWorkItem so it matches the workItem.complete / fail /
pause naming and stays consistent with the diagram’s other symbols.
- Around line 68-69: The boundary list in README has duplicate entries for
interfaces-work, so consolidate the two descriptions into a single package row
instead of keeping two lines with the same name. Update the documentation
section that lists package boundaries to reflect one merged interfaces-work
entry covering both the pure types and Task + WorkItemSource contracts, and
remove the redundant duplicate line.
- Around line 78-91: The README still uses stale WorkItem terminology and
duplicates the same package in two status rows. Update the opening description
to reflect WorkItem execution instead of “scripts remotely,” and in the status
table rename the `interfaces-work` entries to match the refactor, using the
appropriate labels for work item types and work item source interface. Keep the
table consistent by removing the old script/task wording wherever it appears.
In `@orchestrator-v2/packages/orchestrator/src/dispatch-ack-handler.ts`:
- Around line 26-45: The handle() method in DispatchAckHandler is ignoring the
promise returned by reject(), which can surface as an unhandled rejection if
failWorkItem() fails. Update the reject call sites in handle() to attach a
.catch(...) handler, or make reject() handle its own failures internally, and
ensure any failure from workItemSource.failWorkItem is safely logged/absorbed
without changing the existing rejection flow.
In `@orchestrator-v2/packages/runner/README.md`:
- Around line 43-53: The registry model table in README still has stale
terminology and needs to match the updated API names. Update the header from
“Script access” to “Handler access”, and change the Agent row’s lookup text to
use the same symbols as the rest of the runner docs:
`kind`/`workItem`/`handlers` instead of `agentType`/`task`/`agents`. Keep the
table aligned with `createRpcWorkItemExecutionContext`,
`registerWorkItemHandler`, and `ctx.handlers.get(...)` so the README reflects
the current naming consistently.
- Around line 78-81: The module map in the runner README lists outdated
filenames, so update the entries for the WorkItemExecutionContext and handler
execution modules to match the current names. Replace the references to
script-context.ts and execute-script.ts with work-item-execution-context.ts and
execute-work-item.ts so the table lines up with the actual files and readers can
locate the right modules.
In `@orchestrator-v2/packages/runner/src/dispatch-handler.ts`:
- Around line 22-25: The fire-and-forget call to handleDispatch in the
peer.subscribe callback can reject and cause an unhandled promise failure.
Update the subscription callback around handleDispatch to explicitly catch
errors from the async path, including rejections coming from executeWorkItem or
rpc.call in the completion/failure/pause flow, and route them to an appropriate
error handler or log instead of letting them escape.
---
Nitpick comments:
In `@orchestrator-v2/docs/script-tasks.md`:
- Line 1: Rename the documentation file to use the work-item terminology instead
of the old script-task name, and update every reference to it in docs/README.md,
docs/agent-3-task.md, docs/agent-4-workflow.md, and docs/runner.md. Make sure
the links and any mentions of script-tasks.md now point to the new filename
consistently across the docs.
In `@orchestrator-v2/packages/runner/src/work-item-execution-context.ts`:
- Around line 1-6: The imports in work-item-execution-context are split across
two separate import type statements from the same module, which should be
consolidated. Merge WorkItem into the existing `@bifrost-ai/interfaces-work`
import alongside DataRegistry, WorkItemExecutionContext, and WorkItemHandler so
there is only one type import from that module.
🪄 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: a48c8396-9b93-4eb2-9494-ac0a93580ad3
⛔ Files ignored due to path filters (1)
orchestrator-v2/pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (56)
orchestrator-v2/README.mdorchestrator-v2/docs/README.mdorchestrator-v2/docs/agent-4-workflow.mdorchestrator-v2/docs/orchestrator.mdorchestrator-v2/docs/protocol.mdorchestrator-v2/docs/runner.mdorchestrator-v2/docs/script-tasks.mdorchestrator-v2/package.jsonorchestrator-v2/packages/agent-3-task/package.jsonorchestrator-v2/packages/agent-3-task/src/create-task-agent.tsorchestrator-v2/packages/agent-3-task/src/enroll-task-agent.tsorchestrator-v2/packages/agent-3-task/src/run-task-agent.spec.tsorchestrator-v2/packages/agent-3-task/src/run-task-agent.tsorchestrator-v2/packages/agent-3-task/tsconfig.jsonorchestrator-v2/packages/engine/src/test-engine.spec.tsorchestrator-v2/packages/engine/src/test-engine.tsorchestrator-v2/packages/engine/src/types.tsorchestrator-v2/packages/interfaces-task-source/README.mdorchestrator-v2/packages/interfaces-task-source/src/index.tsorchestrator-v2/packages/interfaces-task-source/src/types.tsorchestrator-v2/packages/interfaces-task/package.jsonorchestrator-v2/packages/interfaces-task/src/index.tsorchestrator-v2/packages/interfaces-task/src/types.tsorchestrator-v2/packages/interfaces-task/tsconfig.jsonorchestrator-v2/packages/interfaces-task/vite.config.tsorchestrator-v2/packages/interfaces-work/package.jsonorchestrator-v2/packages/interfaces-work/src/index.tsorchestrator-v2/packages/interfaces-work/src/types.tsorchestrator-v2/packages/interfaces-work/tsconfig.jsonorchestrator-v2/packages/interfaces-work/vite.config.tsorchestrator-v2/packages/orchestrator/package.jsonorchestrator-v2/packages/orchestrator/src/dispatch-ack-handler.tsorchestrator-v2/packages/orchestrator/src/dispatch-tracker.tsorchestrator-v2/packages/orchestrator/src/dispatcher.tsorchestrator-v2/packages/orchestrator/src/orchestrator.spec.tsorchestrator-v2/packages/orchestrator/src/orchestrator.tsorchestrator-v2/packages/orchestrator/src/result-handler.tsorchestrator-v2/packages/orchestrator/src/rpc-router.tsorchestrator-v2/packages/orchestrator/src/test-helpers.tsorchestrator-v2/packages/orchestrator/src/types.tsorchestrator-v2/packages/orchestrator/tsconfig.jsonorchestrator-v2/packages/runner/README.mdorchestrator-v2/packages/runner/package.jsonorchestrator-v2/packages/runner/src/data-registry.tsorchestrator-v2/packages/runner/src/dispatch-handler.tsorchestrator-v2/packages/runner/src/execute-script.tsorchestrator-v2/packages/runner/src/execute-work-item.tsorchestrator-v2/packages/runner/src/index.tsorchestrator-v2/packages/runner/src/runner.spec.tsorchestrator-v2/packages/runner/src/runner.tsorchestrator-v2/packages/runner/src/script-context.tsorchestrator-v2/packages/runner/src/types.tsorchestrator-v2/packages/runner/src/work-item-execution-context.tsorchestrator-v2/packages/runner/tsconfig.jsonorchestrator-v2/publish.jsorchestrator-v2/tsconfig.json
💤 Files with no reviewable changes (10)
- orchestrator-v2/packages/interfaces-task-source/README.md
- orchestrator-v2/packages/interfaces-task/vite.config.ts
- orchestrator-v2/packages/interfaces-task/src/types.ts
- orchestrator-v2/packages/interfaces-task/src/index.ts
- orchestrator-v2/packages/interfaces-task-source/src/index.ts
- orchestrator-v2/packages/interfaces-task/tsconfig.json
- orchestrator-v2/packages/runner/src/script-context.ts
- orchestrator-v2/packages/interfaces-task-source/src/types.ts
- orchestrator-v2/packages/runner/src/execute-script.ts
- orchestrator-v2/packages/interfaces-task/package.json
Owner
Author
|
@CodeRabbit review |
Contributor
✅ Action performedReview finished.
|
matt-wright86
added a commit
that referenced
this pull request
Jul 4, 2026
Rebuilds the agent-3-task Runner augmentation on top of the work-item unification (#44). registerTaskAgent/registerEngine on Runner.prototype now target registerWorkItemHandler, and a bare new Runner() lazily creates its guarded data registry via a new ensure(type, guard) instead of throwing "Unknown data type". - ensure(type, guard) on MutableDataRegistry (+ shared ensureRegistry helper) - ./augment export + a runner dependency on agent-3-task - regression test for bare-Runner registration Co-Authored-By: Eric Siebeneich <eric.siebeneich@gmail.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 7, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Merge
interfaces-taskandinterfaces-task-sourceinto@bifrost-ai/interfaces-work, replacing the overloaded Task/Script split with a single work item model: dispatchedWorkIteminstances and registeredWorkItemHandlers that receive(workItem, ctx).Motivation
"Task" meant three different things in orchestrator v2 (orchestrator work unit, runner script, LLM task agent). This refactor unifies the orchestrator work unit and runner executor under work item vocabulary and reserves task for the LLM task agent (
kind: "task").Type of change
Checklist
go/npxwere not used — everything went throughmake/npm runmake lintpassesmake testpassesmake buildpassesmain; rebased on latestmainNotes for reviewers
Breaking API changes (orchestrator-v2 only):
Task,TaskSourceWorkItem,WorkItemSourceScriptTaskDefinition,ScriptContextWorkItemHandler,WorkItem+WorkItemExecutionContextregisterAgent(type, handler)registerWorkItemHandler({ kind, name, run })task.complete/task.fail/task.pauseworkItem.complete/workItem.fail/workItem.pausetaskSource.setStateworkItemSource.setStateagentType/agentName/taskId/taskStatekind/name/workItemId/stateValidation for this PR was run with
vp checkandvp testinorchestrator-v2(40 tests passing).Made with Cursor