Files
orca/docs/site/content/docs/cli/orchestration.mdx
T
Jinwoo-H c46a06032e feat(cli): name the Orca that owns a workspace 'server'
orca server ... replaces orca environment ... and orca host name; --server and
--parent-server replace --environment and --parent-environment. Old spellings
stay accepted as input only: help, suggestions, errors and printed commands use
the new names, and giving both spellings different values is invalid_argument.
--host is still parsed but leaves help; orca host list/rm are hidden.

Listings name each row's owning server (server: / server=) from data already
returned, mapping a stored owner to a saved-server name only from this
computer's own store, and print server=unknown instead of guessing local. The
ports footer and search hits drop host=. CLI-built JSON uses server keys
(server, address.server, parent.server, unknown-server, servers, knownServers,
status target kind server). create/set print the same parent line as ps.
2026-11-09 02:12:19 -05:00

198 lines
10 KiB
Plaintext

---
title: Orchestration
description: Coordinate agents with Runs, tasks, supervised workers, messages, and decision gates.
---
import { Callout } from '@/components/docs/prose'
Orchestration is Orca's structured multi-agent layer: a **Run** (namespace + coordinator inbox), **Tasks**, **Dispatches**, supervised **workers**, messages, and decision gates.
Use it when you need ownership, completion tracking, or a DAG. For one-off prompts, use `orca terminal send`. For full ownership handoffs without supervision, use worktree/terminal commands from the `orca-cli` skill.
<Callout title="Experimental">
Enable orchestration under Settings → Experimental before using these commands. The CLI talks to
the running Orca server, so `orca status --json` should succeed first.
</Callout>
<Callout title="Legacy commands retired">
`orca orchestration run` and `run-stop` (and `coordinator-start` / `coordinator-stop`) perform
**no effects**. They return recovery text pointing at `orca skills get orchestration --full`. Use
the Run + worker-start flow below.
</Callout>
## Output
Every orchestration command prints a short view by default: the IDs and state the next command needs, with the next step last. `--json` prints the same fields as one line of JSON (`{"ok":true,"result":{...}}`). `--full --json` prints the complete record Orca returned as pretty JSON; `--full` alone prints the longer text receipt. A failed or unconfirmed outcome exits non-zero and writes `error: <code>: <message>` to stderr.
## Core model
- **Run** — durable namespace and home inbox. Never schedules or places workers.
- **Task** — a work item with a spec, dependencies, and status: `pending`, `ready`, `dispatched`, `completed`, `failed`, or `blocked`.
- **Dispatch** — one attempt of a task on a terminal; lifecycle authority for `worker_done`.
- **Message** — inbox mail (`status`, `dispatch`, `worker_done`, `escalation`, `question`, `heartbeat`, …).
- **Decision gate** — a coordinator-owned question that blocks a task until it is resolved.
Completion authority comes from the active dispatch context. Worker completion messages should include both `taskId` and `dispatchId`.
Task IDs printed in terminals, such as `task_...`, are clickable links. Clicking one asks the Orca runtime for the task's current dispatch and focuses the assigned terminal, including when the task lives in a remote or SSH runtime.
## Preferred supervised loop
```bash
orca orchestration run-create --objective "Split checkout QA and summarize blockers"
orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit"
orca orchestration worker-start --task <taskId> --worktree current --agent codex
# or new worktree:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run
# optional per-worker model / effort (Claude, Codex, Cursor, Antigravity, Grok, Muse; not with --terminal):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high
```
`--agent` takes any Orca agent ID enabled on the worker server, for example `claude`, `codex`, `cursor`, `antigravity`, `muse`, `opencode`, or `opencode2`. `--model` accepts opaque provider model IDs for Claude, Codex, Cursor, Antigravity, Grok, and Muse (for example `--agent muse --model muse-spark-1.3`); OpenCode accepts a per-launch model only in an existing worktree, when the execution host verifies its CLI version and model availability; OpenCode effort remains unsupported. Other agents run the model from their own config. `--effort` requires `--model` and only applies when that agent/model supports the level. Neither flag can combine with `--terminal` (reuse an existing pane). Overrides apply to that launch only and show as `model` / `effort` in the start receipt (`--full --json` shows `launch.requested` / `launch.effective`). Federated starts need a worker host that advertises launch-preference support.
After starting workers, end your turn. Orca wakes the coordinator when a worker reports, asks, or stops; run the `check` command the wake gives you and handle every message it prints:
```bash
orca orchestration check --run <runId>
```
Worker completion (from the worker pane; include injected IDs):
```bash
orca orchestration send \
--type worker_done \
--subject "Completed mobile audit" \
--body "Fixed footer overlap; no follow-ups." \
--task-id <taskId> \
--dispatch-id <dispatchId> \
--outcome succeeded \
--files-modified "src/app/settings/Billing.tsx"
```
`worker_done` requires `--outcome succeeded|failed`.
Inspect / recover:
```bash
orca orchestration worker-show --dispatch <dispatchId>
orca orchestration worker-read --dispatch <dispatchId> --limit 50
orca orchestration worker-stop --dispatch <dispatchId>
# After an accepted worker_done: reuse the same terminal for a follow-up Dispatch, or release it
# (archives inspectable output, then closes only that coordinator-owned agent terminal):
orca orchestration worker-release --dispatch <dispatchId>
# Keep a worker open after it finishes (or start it with worker-start --keep-open):
orca orchestration worker-keep-open --dispatch <dispatchId>
# retry placement is explicit — --retry-of does not inherit --on/worktree:
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex
```
Do not leave completed worker terminals open just to re-read output — use `worker-read` after `worker-release`. Do not substitute a broad `terminal close` when release returns `release_pending` or `release_unknown`; follow the receipt's recovery action.
## Federated workers (optional)
```bash
orca orchestration worker-start \
--task <taskId> \
--on windows \
--worktree new-top-level \
--repo <exact_remote_repo_selector> \
--name remote-worker \
--agent codex \
--setup run
orca orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…"
```
Use `--worktree new-child` instead to nest the server's worktree under your workspace in the sidebar. A server too old to nest across machines still starts the worker, top-level, with a `warning` in the receipt.
Later commands route by Dispatch ID; do not repeat `--on`.
## Low-level dispatch (custom topology)
```bash
orca worktree create --name billing-audit --agent codex --json
orca terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <taskId> --to <workerHandle> --inject
```
## Messaging notes
- Default `check` returns the bound Run's oldest unread mail as one Delivery (FIFO) and marks it handled. `--ack <deliveryId>` acknowledges a Delivery from an older Orca that does not mark it; alone it reads no new mail, and with `--wait` it then waits for and takes the next Delivery.
- `--peek` / `--all` do not consume mail and return no `deliveryId`, so they do not drain a mailbox on their own. `--all` and a Run `--peek` show at most 100 rows. To drain, repeat plain `check` until it prints `No messages.` (with `--json`, until `messages` is empty); on an older Orca that asks for `--ack <deliveryId>`, ack each Delivery first or `check` returns it again.
- Group addresses: `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, `@worktree:<id>` — never for `worker_done`.
- Every group except `@worktree:<id>` means the live Dispatches of the sender's own Run, delivered to their Dispatch mailboxes (or child Run mailboxes for nested coordinators). A sender in no Run is refused; `--run` must match the audience and never grants membership.
- Run groups exclude their owning coordinator. A worker raising a blocker sends to `run:<id>`. `@worktree:<id>` includes coordinators in that workspace.
- Quote PowerShell group addresses: `--to "@all"`.
```bash
orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review."
orca orchestration send --to @idle --subject "Anyone free?"
orca orchestration send --to @codex --subject "Codex workers in this Run only"
```
While a wait is active, the CLI emits small JSON heartbeat lines to stderr every 15 seconds. Stdout remains the final command result.
## Worker contract
Dispatched workers receive a preamble that tells them how to communicate with the coordinator:
- Send `worker_done` exactly once, even on failure, with `--outcome`.
- Include a short `--body` summary: what was done, what was found, and what remains.
- Include both task and dispatch IDs so stale retries cannot complete the wrong dispatch.
- Use `orca orchestration ask` for questions instead of local TUI prompts, then end your turn. Orca wakes you with the answer as mail; `check` shows it.
```bash
orca orchestration ask \
--question "Should I update the shared component or only this page?" \
--options "shared,page-only"
```
`ask` records the question and returns at once with `pending: true`. Add `--wait` (or `--resume <message_id>`) to block until the answer instead; with `--json`, read it with `jq -r .result.answer`.
## Decision gates
Use `ask` for worker-to-coordinator questions. Use explicit gates when the coordinator has created a task DAG and wants to block a task until a decision is recorded:
```bash
orca orchestration gate-create \
--task <taskId> \
--question "Merge the shared button change into the task branch?" \
--options '["yes","no"]'
orca orchestration gate-resolve --id <gateId> --resolution "yes"
```
## Recovery
```bash
orca orchestration dispatch-show --task <taskId>
orca orchestration dispatch-show --task <taskId> --preamble
orca orchestration task-list
orca orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}'
```
Reset only when you are intentionally abandoning orchestration state:
```bash
orca orchestration reset --tasks
orca orchestration reset --messages
orca orchestration reset --all
```
`reset` affects runtime-global orchestration state. Do not run it while another coordinator is active unless that is the intended cleanup.
## Choosing the right command
Use `orca terminal send` for a lightweight prompt to an agent you are watching.
Use `orca orchestration worker-start` (or `dispatch --inject`) when a worker must report `worker_done`, ask questions through the coordinator, and be tracked by task ID.
Use `orca orchestration run-create` + tasks + workers when you want a durable Run namespace and supervised multi-agent loop — not the retired `orchestration run` command.
## Full guide
Command flags evolve with the app. After install, agents should run:
```bash
orca skills get orchestration --full
```