mirror of
https://github.com/stablyai/orca.git
synced 2026-11-14 01:47:24 +00:00
Cut the orchestration guide to what Orca does not already enforce or explain
This commit is contained in:
Jinwoo-H
@@ -32,8 +32,7 @@ const GUIDE_REFERENCES = {
|
||||
'low-level-topology.md',
|
||||
'messaging-and-gates.md',
|
||||
'placement-and-remote.md',
|
||||
'recovery-and-cleanup.md',
|
||||
'worker-contract.md'
|
||||
'recovery-and-cleanup.md'
|
||||
],
|
||||
'orca-cli': ['artifacts.md', 'automations.md', 'browser.md', 'skill-sharing.md'],
|
||||
'orca-per-workspace-env': [
|
||||
|
||||
@@ -15,75 +15,46 @@ description: >-
|
||||
|
||||
# Orca orchestration
|
||||
|
||||
You (the coordinator) start worker agents through Orca, end your turn, and Orca
|
||||
wakes you when a worker reports. A **Run** is your inbox, a **Task** is one
|
||||
piece of work, and a **Dispatch** is one worker's attempt at it.
|
||||
|
||||
| Situation | Do this |
|
||||
| --------------------------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| The user wants another agent's result back, supervision, a task DAG, or ask/reply | Follow the recipe below |
|
||||
| Your prompt has a preamble with Task and Dispatch IDs | Follow "If you are a dispatched worker" |
|
||||
| The user wants work handed off with nothing back | Use the `orca-cli` skill; start no workers here |
|
||||
| A message carries a legacy authority label | Load `references/legacy-contract-migration.md` first |
|
||||
If your prompt has a preamble with Task and Dispatch IDs, you are a worker:
|
||||
follow the preamble. To hand work off with nothing back, use `orca-cli`.
|
||||
|
||||
## Recipe
|
||||
|
||||
`ORCA` stands for the executable you used to run `skills get`; type it in its
|
||||
place and use it for every command. If it fails, report its exact error.
|
||||
place and use it for every command.
|
||||
|
||||
```text
|
||||
ORCA orchestration worker-start --spec "<task>" --worktree current --agent codex --json
|
||||
```
|
||||
|
||||
- Start every independent worker, tell the user what you started, then **end
|
||||
your turn**. "Report back" and "tell me when it's done" still mean end your
|
||||
turn; Orca wakes you and you report then.
|
||||
- If a receipt has `next`, do what it says. If a receipt has none while a
|
||||
worker still runs, Orca may not wake you when it fails: block instead (see
|
||||
the end of the next section).
|
||||
- Start every independent worker, then **end your turn**. "Report back" and
|
||||
"tell me when it's done" still mean end your turn; Orca wakes you and you
|
||||
report then.
|
||||
- If a receipt has `next`, follow it. When Orca has nothing for you, end your
|
||||
turn.
|
||||
- `--worktree current` uses your workspace. Use a new one only when the user
|
||||
asks or sharing would conflict:
|
||||
`--worktree new-top-level --repo id:<repoId> --name <short-name>`
|
||||
(`ORCA repo list --json` gives the id).
|
||||
- `--agent` is the agent the user asked for (`claude`, `codex`, ...). Add
|
||||
`--model` only if the user named one.
|
||||
- If `worker-start` fails, do not rerun it; read `failedStage` and load
|
||||
`references/recovery-and-cleanup.md`.
|
||||
- Do not poll, sleep, or run watch scripts. To steer a worker, use
|
||||
- To steer a worker, use
|
||||
`ORCA orchestration send --to dispatch:<dispatch_id> --subject "<topic>" --body "<guidance>"`,
|
||||
never its terminal.
|
||||
never its terminal. A sent message is only queued; confirm the worker applied
|
||||
it before reporting the corrected result.
|
||||
|
||||
## When Orca wakes you
|
||||
|
||||
You get "You have N orchestration messages. Run `orca orchestration check
|
||||
--run <run_id>`", typed into your terminal or sent as a chat message. Run it:
|
||||
|
||||
```text
|
||||
ORCA orchestration check --run <run_id> --json
|
||||
```
|
||||
|
||||
- Answer each `question`:
|
||||
- Run the `check` command the wake gives you, and repeat it until `count` is 0. Answer each `question` with
|
||||
`ORCA orchestration reply --id <message_id> --body "<answer>" --json`.
|
||||
- A `worker_done` is that worker's result. If a worker stopped without one,
|
||||
Orca tells you and includes its last output; steer it with `send`, stop and
|
||||
retry it, or tell the user.
|
||||
- Repeat `check` until `count` is 0. In a Task DAG, start newly ready Tasks
|
||||
(`references/coordinator-loop.md`).
|
||||
- An `escalation` with `stopReason` means the worker stopped without
|
||||
`worker_done`: steer it with `send`, stop and retry it, or tell the user.
|
||||
- A `worker_done` settles its Task; never mark a reported failure completed.
|
||||
- When every worker has settled, report to the user per Task: outcome,
|
||||
evidence, open blockers. Otherwise follow `next` (end your turn); with no
|
||||
`next`, follow each row's `nextAction` in
|
||||
`worker-list --run <run_id> --include-remote --json`, and block while any
|
||||
worker still runs.
|
||||
evidence, open blockers.
|
||||
|
||||
Finished terminal workers close about 2 minutes after reporting (`autoReleaseAt`
|
||||
in `worker-list`). Release a chat worker, or a finished one with no
|
||||
`autoReleaseAt`, yourself with `worker-release --dispatch <dispatch_id>`. To keep one for a
|
||||
follow-up, run `ORCA orchestration worker-retain --dispatch <dispatch_id> --json`
|
||||
first (`references/coordinator-loop.md`).
|
||||
|
||||
Block with `check --run <run_id> --wait --timeout-ms 540000`, repeating as
|
||||
needed, only when a receipt lacks `next` as above, outside an Orca terminal or
|
||||
chat, or if the user says not to end your turn.
|
||||
Finished terminal workers close on their own. To keep one for a follow-up, run
|
||||
`ORCA orchestration worker-retain --dispatch <dispatch_id> --json`.
|
||||
|
||||
## Task spec
|
||||
|
||||
@@ -94,36 +65,18 @@ them to you.
|
||||
|
||||
## Safety
|
||||
|
||||
- Stop, retry, or abandon a worker only on proof its agent stopped; silence or
|
||||
an `unverifiable` reading proves nothing.
|
||||
- Lifecycle authority is the active Dispatch, not copied IDs, titles, or
|
||||
transcripts.
|
||||
- Folder workspaces are valid; never require Git.
|
||||
- Never replace Orca workers with another subagent tool when the user asked for
|
||||
Orca workers.
|
||||
|
||||
## If you are a dispatched worker
|
||||
|
||||
Your preamble has your IDs and exact commands; copy them, never rebuild them.
|
||||
|
||||
1. Do only your Task, yourself; no subagents or helpers unless told.
|
||||
2. Ask the coordinator with the preamble's `ask` command, never a local prompt.
|
||||
3. At checkpoints, read coordinator mail with the preamble's `check` command.
|
||||
4. Finish with one `worker_done`: three sentences, both IDs, and
|
||||
`--outcome succeeded` or `failed`. You are done when it confirms; if it
|
||||
fails, follow the recovery it prints.
|
||||
5. Then end your turn.
|
||||
Stop, retry, or abandon a worker only on proof its agent stopped; silence or an
|
||||
`unverifiable` reading proves nothing.
|
||||
|
||||
## References
|
||||
|
||||
`ORCA skills get orchestration --reference references/<file>.md`
|
||||
|
||||
| Situation | Reference |
|
||||
| -------------------------------------------------------------------------- | ----------------------------------------- |
|
||||
| Task DAGs, several waves or Runs, reusing a worker, model/effort | `references/coordinator-loop.md` |
|
||||
| Child or exact workspaces, folder workspaces, SSH, WSL, a connected server | `references/placement-and-remote.md` |
|
||||
| Decision gates, group messages, lost replies, old mail, older Orca | `references/messaging-and-gates.md` |
|
||||
| A failed, stuck, or unknown worker; stop, retry, abandon, release | `references/recovery-and-cleanup.md` |
|
||||
| A worker question the preamble does not answer | `references/worker-contract.md` |
|
||||
| Custom argv or terminal layout | `references/low-level-topology.md` |
|
||||
| Legacy labels, adopted Runs, takeover | `references/legacy-contract-migration.md` |
|
||||
| Situation | Reference |
|
||||
| ---------------------------------------------- | ----------------------------------------- |
|
||||
| Task DAGs, several Runs, reusing a worker | `references/coordinator-loop.md` |
|
||||
| Child worktrees, SSH, WSL, a connected server | `references/placement-and-remote.md` |
|
||||
| Group messages, inbox scripts | `references/messaging-and-gates.md` |
|
||||
| A failed or unknown worker; retry, stop, reset | `references/recovery-and-cleanup.md` |
|
||||
| Custom argv or terminal layout | `references/low-level-topology.md` |
|
||||
| Legacy labels, adopted Runs, takeover | `references/legacy-contract-migration.md` |
|
||||
|
||||
@@ -2,9 +2,8 @@
|
||||
|
||||
## Task DAGs
|
||||
|
||||
Create every Task before your first turn ends. Add `--deps` only for real
|
||||
dependencies; prefer parallel waves to long chains. Workers editing the same
|
||||
files at once need separate workspaces.
|
||||
A Task needs a Run, so create one first. Workers editing the same files at once
|
||||
need separate workspaces.
|
||||
|
||||
```text
|
||||
ORCA orchestration run-create --objective "<goal>" --json
|
||||
@@ -13,46 +12,20 @@ ORCA orchestration task-list --ready --brief --json
|
||||
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json
|
||||
```
|
||||
|
||||
On every wake, start the Tasks `task-list --ready` shows. `--brief` shortens long specs (`spec_truncated` marks them); omit it when you
|
||||
need the full text. Pass `json_array` with the quoting rules of your shell.
|
||||
On every wake, start the Tasks `task-list --ready` shows.
|
||||
|
||||
## Several Runs
|
||||
|
||||
`worker-start --spec` creates a Run when you have none. A later `run-create`
|
||||
starts another Run and keeps the earlier ones: their mail still wakes you with
|
||||
`check --run <id>`, but commands without `--run` use the newest Run, so pass
|
||||
`--run <id>` when acting on an earlier one.
|
||||
`run-use` keeps only the Run it names.
|
||||
|
||||
## Helpers and nesting
|
||||
|
||||
Helpers a worker starts report to that worker, not you, and show in your
|
||||
`worker-list` with `creatorDispatchId`. Nesting is capped
|
||||
(`nested_worker_depth_exceeded`); a new Run does not reset it.
|
||||
|
||||
## Model and effort
|
||||
|
||||
Pass `--model` only when the user named a model; otherwise the worker uses its
|
||||
default. Add `--effort` only with `--model`, and only if that model
|
||||
supports it. Neither works with `--terminal`.
|
||||
|
||||
```text
|
||||
ORCA orchestration worker-start --task <task_id> --worktree current --agent claude --model opus --effort high --json
|
||||
```
|
||||
|
||||
OpenCode takes `--model` only in an existing workspace, never `--effort`.
|
||||
Report the receipt's `launch.effective`, not your request.
|
||||
A later `run-create` keeps your earlier Runs: their mail still wakes you, but
|
||||
commands without `--run` use the newest Run, so pass `--run <id>` for an earlier
|
||||
one. `run-use` keeps only the Run it names.
|
||||
|
||||
## Reusing a worker
|
||||
|
||||
Finished terminal workers close about 2 minutes after `worker_done`. To give
|
||||
the same agent follow-up work, start the next Task on its terminal (this also
|
||||
stops the close):
|
||||
To give the same agent follow-up work, start the next Task on its terminal and
|
||||
workspace:
|
||||
|
||||
```text
|
||||
ORCA orchestration worker-show --dispatch <dispatch_id> --json
|
||||
ORCA orchestration worker-start --task <next_task_id> --terminal <agent_terminal_handle> --worktree <its_workspace> --json
|
||||
```
|
||||
|
||||
Run `worker-retain` only to keep one open with no follow-up yet;
|
||||
`worker-read` reads saved output.
|
||||
|
||||
@@ -1,48 +1,6 @@
|
||||
# Legacy contract migration
|
||||
|
||||
Use this only for a legacy label, adopted Run, compatibility receipt, or
|
||||
takeover. New work uses current commands.
|
||||
|
||||
## Labels
|
||||
|
||||
- `[LEGACY COMPATIBILITY]`: live. Run only the exact command printed with it,
|
||||
with the same executable.
|
||||
- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]`: a one-time replay. Handle it
|
||||
so a repeat does no harm, and acknowledge only as it says.
|
||||
- `[LEGACY READ-ONLY]`: look only; no reply, ack, or lifecycle change.
|
||||
- No label: current rules.
|
||||
|
||||
A current Run, binding, or Dispatch wins over legacy fallback. An adoption
|
||||
record alone grants nothing. If ownership or the exact legacy contract is
|
||||
unproven, only inspect; never fall back to doing the work locally.
|
||||
|
||||
Adoption keeps the live worker, terminal, workspace, Task, and Dispatch; it
|
||||
never restarts, replaces, or writes to them.
|
||||
|
||||
## Compatibility receipts
|
||||
|
||||
Run a receipt's next-step arguments exactly, with the same executable. If an
|
||||
`ask` may already be answered, run the recovery `check` Orca printed before
|
||||
asking again.
|
||||
|
||||
On packaged Windows a legacy `ask` commits the question, prints an exact
|
||||
`ask --resume <message_id>` command, and exits with status `75`; run that
|
||||
command after the update. For WSL, keep the printed `orca-ide` executable.
|
||||
|
||||
## Inspect and take over
|
||||
|
||||
These only read:
|
||||
|
||||
```text
|
||||
ORCA orchestration run-list --json
|
||||
ORCA orchestration run-show --id <adopted_run_id> --json
|
||||
ORCA orchestration task-list --run <adopted_run_id> --json
|
||||
ORCA orchestration check --terminal <legacy_handle> --peek --json
|
||||
ORCA terminal read --terminal <legacy_handle> --json
|
||||
```
|
||||
|
||||
`run_legacy_local` is an empty record after adoption; the work lives in the Run
|
||||
whose objective is `Recovered orchestration work from a contract update`.
|
||||
Follow a legacy label's printed command exactly, with the same executable.
|
||||
|
||||
Only if the original coordinator is gone or cannot prove ownership, take over
|
||||
from your own terminal:
|
||||
@@ -52,6 +10,5 @@ ORCA orchestration run-use --id <adopted_run_id> --takeover-legacy --json
|
||||
ORCA orchestration check --run <adopted_run_id> --json
|
||||
```
|
||||
|
||||
Takeover fences only the old coordinator and keeps every worker and file.
|
||||
Never take over from an active coordinator, and never start a second editor
|
||||
just because Orca updated.
|
||||
|
||||
@@ -1,20 +1,11 @@
|
||||
# Low-level topology
|
||||
|
||||
Use this only when `worker-start` cannot express the argv or terminal layout
|
||||
you need (model and effort are not custom argv).
|
||||
|
||||
```text
|
||||
ORCA terminal create --worktree active --title <task_name> --command "<agent_command>" --json
|
||||
ORCA terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
|
||||
ORCA orchestration dispatch --task <task_id> --to <handle> --inject --json
|
||||
```
|
||||
|
||||
Wait for `tui-idle` only when startup could drop injected input. If a
|
||||
`terminal send` submit is unconfirmed, rerun the same send with its receipt's
|
||||
`--retry-request <id>` and `--wait-submit <seconds>`; that never sends twice.
|
||||
|
||||
`dispatch --inject` records the Task and Dispatch but does not supervise the
|
||||
process: worker commands report it `unsupervised`, `worker-stop` and
|
||||
`worker-abandon` leave it running, and release does not close it. To own an
|
||||
existing agent terminal, use `worker-start --terminal <handle>` instead. Never
|
||||
use low-level dispatch to get around the nesting cap or to hand work off.
|
||||
If a `terminal send` submit is unconfirmed, rerun the same send with its
|
||||
receipt's `--retry-request <id>` and `--wait-submit <seconds>`; that never sends
|
||||
twice.
|
||||
|
||||
@@ -1,51 +1,8 @@
|
||||
# Messaging and gates
|
||||
|
||||
## Reading mail
|
||||
Handle a whole `check` batch before the next `check`. Scripts that only watch
|
||||
the inbox must use `check --peek`, which marks nothing handled.
|
||||
|
||||
`check --run <run_id>` returns your Run's oldest batch of mail (up to 50
|
||||
messages) and marks it handled; handle all of it before the next `check`.
|
||||
`--peek` only looks; scripts that watch the inbox must use it. `check` takes
|
||||
`--terminal <handle>`, never `--from`; an Orca terminal fills it in.
|
||||
|
||||
- **Lost reply.** If a `check` or other mutation's reply was lost, rerun the
|
||||
same command with the `--retry-request <id>` it printed.
|
||||
- **Lost context.** Reread handled mail:
|
||||
`ORCA orchestration inbox --terminal run:<run_id> --limit 50 --full --json`
|
||||
(a worker uses `dispatch:<dispatch_id>`).
|
||||
|
||||
## Addresses
|
||||
|
||||
Steer one worker by its Dispatch, never by a terminal handle:
|
||||
|
||||
```text
|
||||
ORCA orchestration send --to dispatch:<dispatch_id> --subject "Follow-up" --body "<guidance>" --json
|
||||
```
|
||||
|
||||
Omit `--from` as a coordinator; a worker copies the `--from` in its preamble.
|
||||
|
||||
Groups reach the live workers of your own Run: `@all`, `@idle`, and one per
|
||||
agent (`@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`,
|
||||
`@cursor`). `@worktree:<id>` reaches every Orca terminal in that workspace,
|
||||
coordinators included. Use groups only for deliberate fan-out. A worker raising a blocker
|
||||
sends to `run:<id>`.
|
||||
|
||||
## Questions and gates
|
||||
|
||||
A worker asks with `ask`; you answer with `reply --id <message_id>`. If its
|
||||
wait times out, the question stays pending and the worker resumes it.
|
||||
|
||||
Use a gate only for a decision in your own Task DAG, never to answer an `ask`:
|
||||
|
||||
```text
|
||||
ORCA orchestration gate-create --task <task_id> --question "<decision>" --options <json_array> --json
|
||||
ORCA orchestration gate-resolve --id <gate_id> --resolution "<choice>" --json
|
||||
ORCA orchestration gate-list --task <task_id> --json
|
||||
```
|
||||
|
||||
## Older Orca
|
||||
|
||||
- A `check` batch without `"deliveryAcknowledged": true` is not marked handled;
|
||||
ack it with `check --ack <delivery_id>` or it comes back.
|
||||
- A receipt without `next` means act on the result yourself.
|
||||
- If `worker-start` says the coordinator must be bound to a Run, run
|
||||
`ORCA orchestration run-create --objective "<goal>" --json`, then rerun it.
|
||||
Groups (`@all`, `@idle`, `@codex`, ...) reach the live workers of your Run;
|
||||
`@worktree:<id>` also reaches coordinators in that workspace. Use groups only
|
||||
for deliberate fan-out.
|
||||
|
||||
@@ -1,55 +1,12 @@
|
||||
# Placement and remote execution
|
||||
|
||||
## Placement
|
||||
|
||||
A new worker is a new agent, not a new worktree. Use the current or an
|
||||
existing workspace unless the user asked for a new one or sharing would
|
||||
conflict.
|
||||
|
||||
```text
|
||||
# Current workspace; setup does not rerun.
|
||||
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json
|
||||
|
||||
# Child of the current worktree.
|
||||
ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json
|
||||
|
||||
# New top-level worktree; --repo is needed outside that project.
|
||||
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --repo id:<repoId> --name <name> --agent codex --setup run --json
|
||||
```
|
||||
|
||||
`new-child`, and `new-top-level` without `--repo`, need you inside an Orca
|
||||
worktree.
|
||||
For an existing worktree, pass the full ID Orca returned as
|
||||
`id:<repo-id>::<path>`; a repo ID is not a worktree ID.
|
||||
|
||||
## Folder workspaces
|
||||
|
||||
Folders are first-class: never run Git or require a worktree for one. `repo add`
|
||||
rejects a plain folder; register it with:
|
||||
|
||||
```text
|
||||
ORCA project setup-existing-folder --project <project_id> --host <host_id> --path <abs_path> --kind folder --json
|
||||
```
|
||||
|
||||
Then place work there with its exact selector. `new-child` and `new-top-level`
|
||||
do not apply to folders.
|
||||
|
||||
## Connected servers
|
||||
|
||||
The Run stays on your server; `--on` picks only where the worker runs:
|
||||
|
||||
```text
|
||||
# On a connected server; the Run stays on yours.
|
||||
ORCA orchestration worker-start --task <task_id> --on <environment> --worktree new-top-level --repo <exact_remote_repo_selector> --name <name> --agent codex --setup run --json
|
||||
```
|
||||
|
||||
`current` and `new-child` are invalid with `--on`; use an exact remote
|
||||
workspace or `new-top-level` with an exact remote repo. After start, do
|
||||
everything by Dispatch ID (`send --to dispatch:<id>`, `worker-show`,
|
||||
`worker-read`, `worker-stop`) without `--on` or a remote terminal handle. A
|
||||
retry states `--on` and placement again. List remote workers with `worker-list --run <run_id> --include-remote`.
|
||||
|
||||
The execution host owns process, file, and cleanup facts; lost contact reads
|
||||
`unverifiable`, never `exited`. Servers update separately, so optional fields
|
||||
may be missing.
|
||||
|
||||
For WSL, run the exact executable Orca prints (such as `orca-ide`).
|
||||
After start, address a remote worker only by Dispatch ID, never by a terminal
|
||||
handle.
|
||||
|
||||
@@ -1,108 +1,17 @@
|
||||
# Recovery and cleanup
|
||||
|
||||
Act only on proof. When you cannot tell, keep the work and report it as
|
||||
unknown.
|
||||
Act only on proof. `worker-list --run <run_id> --include-remote --json` gives
|
||||
each worker's liveness and `nextAction`; follow it.
|
||||
|
||||
| What you can prove | Do this |
|
||||
| -------------------------- | ------------------------------------------------------- |
|
||||
| Running, or `unverifiable` | Wait or inspect; never stop, retry, abandon, or release |
|
||||
| `failed` or `stopped` | Retry with `--retry-of`, placement stated again |
|
||||
| `outcome_unknown` | Inspect, then choose `worker-stop` or `worker-abandon` |
|
||||
| `exited` agent | Follow the row's `nextAction` in `worker-list` |
|
||||
|
||||
## Inspect
|
||||
|
||||
```text
|
||||
ORCA orchestration worker-list --run <run_id> --include-remote --json
|
||||
ORCA orchestration worker-show --dispatch <dispatch_id> --json
|
||||
ORCA orchestration worker-read --dispatch <dispatch_id> --limit 50 --json
|
||||
```
|
||||
|
||||
`worker-list` decides whether an agent is alive (`projection.liveness`) and
|
||||
what to do (`projection.nextAction`). Without `--include-remote`, remote rows
|
||||
read `unverifiable`. Past 100 rows, page with `--cursor <page.nextCursor>`.
|
||||
|
||||
`worker-show`'s `observation.status` covers only the terminal, so a `live`
|
||||
terminal can hold a dead agent. But when the list row is `unverifiable` with
|
||||
`missing_status`, `host_unavailable`, or `capability_unsupported`, a
|
||||
`worker-show` verdict from the execution host is better evidence.
|
||||
|
||||
Continue `worker-read` with its cursor; on `source_changed`, drop the cursor.
|
||||
Never guess a session ID, transcript path, or remote terminal handle.
|
||||
|
||||
## Proof that a worker stopped
|
||||
|
||||
An `escalation` with `stopReason` means Orca saw the worker end its turn, or
|
||||
stop at a prompt, without `worker_done`; it carries the last output and the
|
||||
Dispatch stays open. Steer it with `send --to dispatch:<id>`, or `worker-stop`
|
||||
it and then retry. `exited` liveness is also proof. Silence, an unchanged
|
||||
`worker-read`, and `unverifiable` prove nothing.
|
||||
|
||||
## Was the mutation applied?
|
||||
|
||||
If a mutation's reply was lost, ask before rerunning:
|
||||
|
||||
```text
|
||||
ORCA orchestration request-show --request <request_id> --json
|
||||
```
|
||||
|
||||
`completed`: it took effect; use its receipt. `pending`: rerun the same command
|
||||
with `--retry-request <request_id>`. `absent`: unknown; inspect the Task,
|
||||
Dispatch, and terminal before retrying.
|
||||
|
||||
## Refused starts
|
||||
|
||||
`error.data.nextSteps`, when present, is the exact fix.
|
||||
|
||||
| Code | Fix |
|
||||
| -------------------- | --------------------------------------------------------------------------- |
|
||||
| `task_not_found` | Check `task-list --json`; create the Task if missing |
|
||||
| `task_not_startable` | Wait for dependencies, or fix the failed one; a bad `--retry-of` lands here |
|
||||
| `inject_rejected` | Start a known agent in that terminal, or skip `--inject` |
|
||||
| Not bound to a Run | Older Orca: see `references/messaging-and-gates.md` |
|
||||
| `runtime_error` | Read the message and inspect; never rerun unchanged |
|
||||
|
||||
A start that failed before its agent was ready still owns its terminal; release
|
||||
it with the `worker-release` its receipt names, never `terminal close`.
|
||||
|
||||
## Retry, stop, abandon
|
||||
|
||||
Retry by naming the Task (`--spec` would create a new one). Placement is not
|
||||
inherited:
|
||||
Retry a failed or stopped attempt on the same Task; `--spec` would create a new
|
||||
one. Placement is not inherited:
|
||||
|
||||
```text
|
||||
ORCA orchestration worker-start --task <task_id> --retry-of <dispatch_id> --worktree <placement> --agent <agent> --json
|
||||
```
|
||||
|
||||
Three failed starts fail the Task and refuse further retries; tell the user
|
||||
rather than working around it with a new Run or Task.
|
||||
|
||||
```text
|
||||
ORCA orchestration worker-stop --dispatch <dispatch_id> --json
|
||||
ORCA orchestration worker-abandon --dispatch <dispatch_id> --json
|
||||
```
|
||||
|
||||
`worker-stop` closes only that worker's agent terminal, never the workspace or
|
||||
other terminals. Its `processAction` is `closed_agent_terminal` (do not also
|
||||
`terminal close`), `none`, or `unknown`. `stop_unknown` exits 1; check
|
||||
`worker-show` before acting again. `worker-abandon` only ends Orca's tracking;
|
||||
it touches no process or file and keeps the terminal open.
|
||||
|
||||
To cancel a Task, stop or abandon its worker, then:
|
||||
|
||||
```text
|
||||
ORCA orchestration task-update --id <task_id> --status failed --result cancelled --json
|
||||
```
|
||||
|
||||
Its dependents stay blocked until a `--retry-of` replacement succeeds.
|
||||
|
||||
## Retain and release
|
||||
|
||||
Finished terminal workers close themselves about 2 minutes after `worker_done`;
|
||||
Orca saves their output first. `worker-retain` keeps one open; `worker-release`
|
||||
closes a chat worker or closes one early. Neither touches reused, pre-existing,
|
||||
setup, coordinator, active, or user-typed-in terminals. If a receipt says
|
||||
`release_pending` or `release_unknown`, follow its recovery.
|
||||
`worker-stop` exits 1 with `stop_unknown` when it cannot prove the agent
|
||||
stopped; check `worker-show` before acting again.
|
||||
|
||||
`orchestration reset` deletes coordination state; run it only when the user
|
||||
gives that state up.
|
||||
|
||||
@@ -1,62 +0,0 @@
|
||||
# Worker contract
|
||||
|
||||
Your preamble is authoritative: copy its commands exactly, including any extra
|
||||
flag.
|
||||
|
||||
## Ask
|
||||
|
||||
Ask through Orca, never a local prompt the coordinator cannot see:
|
||||
|
||||
```text
|
||||
ORCA orchestration ask --from <worker_handle> --question "<question>" --options "<choice-a>,<choice-b>" --timeout-ms 600000
|
||||
ORCA orchestration ask --from <worker_handle> --resume <message_id> --timeout-ms 600000
|
||||
```
|
||||
|
||||
A wait lasts up to `--timeout-ms` (default 10 minutes, at most 30). On a
|
||||
timeout or disconnect the question stays pending: resume it by message ID; do
|
||||
not ask again.
|
||||
|
||||
## Coordinator mail
|
||||
|
||||
Nothing interrupts you; mail arrives only when you check. Check at natural
|
||||
checkpoints and once right before `worker_done`:
|
||||
|
||||
```text
|
||||
ORCA orchestration check --terminal <worker_handle> --json
|
||||
```
|
||||
|
||||
Repeat until `count` is 0. For a lost reply or lost context, and for older
|
||||
Orca, see `references/messaging-and-gates.md`.
|
||||
|
||||
Never `run-use` the Run your Dispatch is in, or any parent Run. If a plain
|
||||
`check` returns `consumer_fenced`, you no longer own this Dispatch: stop, and
|
||||
send no `worker_done`. If `send` or `ask` returns it, you ran it from a terminal that is
|
||||
not yours.
|
||||
|
||||
## Helpers
|
||||
|
||||
Start helpers only as the preamble's SUB-DISPATCH section says. Their mail
|
||||
arrives in your `check`; answer with `reply`. Wait for every helper to settle
|
||||
before your `worker_done`, and name any that failed.
|
||||
|
||||
## Escalate
|
||||
|
||||
Only before you finish, and only when the coordinator must act:
|
||||
|
||||
```text
|
||||
ORCA orchestration send --from <worker_handle> --type escalation --subject "Blocked: <reason>" --body "<details>" --task-id <task_id> --dispatch-id <dispatch_id>
|
||||
```
|
||||
|
||||
## Finish
|
||||
|
||||
Send one `worker_done`. The body is three sentences: what changed, what you
|
||||
found, what remains. Use `--outcome failed` when the work is not done; never
|
||||
hide failure in prose. Add `--files-modified` or `--report-path` only with real
|
||||
paths.
|
||||
|
||||
```text
|
||||
ORCA orchestration send --from <worker_handle> --type worker_done --subject "<short status>" --body "<work, findings, remaining>" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded
|
||||
```
|
||||
|
||||
Then end your turn; do not poll or start other work. A later direct user
|
||||
request is new work: do it without the settled IDs.
|
||||
+55
-425
@@ -2350,75 +2350,46 @@ const ORCHESTRATION_MARKDOWN = [
|
||||
"",
|
||||
"# Orca orchestration",
|
||||
"",
|
||||
"You (the coordinator) start worker agents through Orca, end your turn, and Orca",
|
||||
"wakes you when a worker reports. A **Run** is your inbox, a **Task** is one",
|
||||
"piece of work, and a **Dispatch** is one worker's attempt at it.",
|
||||
"",
|
||||
"| Situation | Do this |",
|
||||
"| --------------------------------------------------------------------------------- | ---------------------------------------------------- |",
|
||||
"| The user wants another agent's result back, supervision, a task DAG, or ask/reply | Follow the recipe below |",
|
||||
"| Your prompt has a preamble with Task and Dispatch IDs | Follow \"If you are a dispatched worker\" |",
|
||||
"| The user wants work handed off with nothing back | Use the `orca-cli` skill; start no workers here |",
|
||||
"| A message carries a legacy authority label | Load `references/legacy-contract-migration.md` first |",
|
||||
"If your prompt has a preamble with Task and Dispatch IDs, you are a worker:",
|
||||
"follow the preamble. To hand work off with nothing back, use `orca-cli`.",
|
||||
"",
|
||||
"## Recipe",
|
||||
"",
|
||||
"`ORCA` stands for the executable you used to run `skills get`; type it in its",
|
||||
"place and use it for every command. If it fails, report its exact error.",
|
||||
"place and use it for every command.",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration worker-start --spec \"<task>\" --worktree current --agent codex --json",
|
||||
"```",
|
||||
"",
|
||||
"- Start every independent worker, tell the user what you started, then **end",
|
||||
" your turn**. \"Report back\" and \"tell me when it's done\" still mean end your",
|
||||
" turn; Orca wakes you and you report then.",
|
||||
"- If a receipt has `next`, do what it says. If a receipt has none while a",
|
||||
" worker still runs, Orca may not wake you when it fails: block instead (see",
|
||||
" the end of the next section).",
|
||||
"- Start every independent worker, then **end your turn**. \"Report back\" and",
|
||||
" \"tell me when it's done\" still mean end your turn; Orca wakes you and you",
|
||||
" report then.",
|
||||
"- If a receipt has `next`, follow it. When Orca has nothing for you, end your",
|
||||
" turn.",
|
||||
"- `--worktree current` uses your workspace. Use a new one only when the user",
|
||||
" asks or sharing would conflict:",
|
||||
" `--worktree new-top-level --repo id:<repoId> --name <short-name>`",
|
||||
" (`ORCA repo list --json` gives the id).",
|
||||
"- `--agent` is the agent the user asked for (`claude`, `codex`, ...). Add",
|
||||
" `--model` only if the user named one.",
|
||||
"- If `worker-start` fails, do not rerun it; read `failedStage` and load",
|
||||
" `references/recovery-and-cleanup.md`.",
|
||||
"- Do not poll, sleep, or run watch scripts. To steer a worker, use",
|
||||
"- To steer a worker, use",
|
||||
" `ORCA orchestration send --to dispatch:<dispatch_id> --subject \"<topic>\" --body \"<guidance>\"`,",
|
||||
" never its terminal.",
|
||||
" never its terminal. A sent message is only queued; confirm the worker applied",
|
||||
" it before reporting the corrected result.",
|
||||
"",
|
||||
"## When Orca wakes you",
|
||||
"",
|
||||
"You get \"You have N orchestration messages. Run `orca orchestration check",
|
||||
"--run <run_id>`\", typed into your terminal or sent as a chat message. Run it:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration check --run <run_id> --json",
|
||||
"```",
|
||||
"",
|
||||
"- Answer each `question`:",
|
||||
"- Run the `check` command the wake gives you, and repeat it until `count` is 0. Answer each `question` with",
|
||||
" `ORCA orchestration reply --id <message_id> --body \"<answer>\" --json`.",
|
||||
"- A `worker_done` is that worker's result. If a worker stopped without one,",
|
||||
" Orca tells you and includes its last output; steer it with `send`, stop and",
|
||||
" retry it, or tell the user.",
|
||||
"- Repeat `check` until `count` is 0. In a Task DAG, start newly ready Tasks",
|
||||
" (`references/coordinator-loop.md`).",
|
||||
"- An `escalation` with `stopReason` means the worker stopped without",
|
||||
" `worker_done`: steer it with `send`, stop and retry it, or tell the user.",
|
||||
"- A `worker_done` settles its Task; never mark a reported failure completed.",
|
||||
"- When every worker has settled, report to the user per Task: outcome,",
|
||||
" evidence, open blockers. Otherwise follow `next` (end your turn); with no",
|
||||
" `next`, follow each row's `nextAction` in",
|
||||
" `worker-list --run <run_id> --include-remote --json`, and block while any",
|
||||
" worker still runs.",
|
||||
" evidence, open blockers.",
|
||||
"",
|
||||
"Finished terminal workers close about 2 minutes after reporting (`autoReleaseAt`",
|
||||
"in `worker-list`). Release a chat worker, or a finished one with no",
|
||||
"`autoReleaseAt`, yourself with `worker-release --dispatch <dispatch_id>`. To keep one for a",
|
||||
"follow-up, run `ORCA orchestration worker-retain --dispatch <dispatch_id> --json`",
|
||||
"first (`references/coordinator-loop.md`).",
|
||||
"",
|
||||
"Block with `check --run <run_id> --wait --timeout-ms 540000`, repeating as",
|
||||
"needed, only when a receipt lacks `next` as above, outside an Orca terminal or",
|
||||
"chat, or if the user says not to end your turn.",
|
||||
"Finished terminal workers close on their own. To keep one for a follow-up, run",
|
||||
"`ORCA orchestration worker-retain --dispatch <dispatch_id> --json`.",
|
||||
"",
|
||||
"## Task spec",
|
||||
"",
|
||||
@@ -2429,39 +2400,21 @@ const ORCHESTRATION_MARKDOWN = [
|
||||
"",
|
||||
"## Safety",
|
||||
"",
|
||||
"- Stop, retry, or abandon a worker only on proof its agent stopped; silence or",
|
||||
" an `unverifiable` reading proves nothing.",
|
||||
"- Lifecycle authority is the active Dispatch, not copied IDs, titles, or",
|
||||
" transcripts.",
|
||||
"- Folder workspaces are valid; never require Git.",
|
||||
"- Never replace Orca workers with another subagent tool when the user asked for",
|
||||
" Orca workers.",
|
||||
"",
|
||||
"## If you are a dispatched worker",
|
||||
"",
|
||||
"Your preamble has your IDs and exact commands; copy them, never rebuild them.",
|
||||
"",
|
||||
"1. Do only your Task, yourself; no subagents or helpers unless told.",
|
||||
"2. Ask the coordinator with the preamble's `ask` command, never a local prompt.",
|
||||
"3. At checkpoints, read coordinator mail with the preamble's `check` command.",
|
||||
"4. Finish with one `worker_done`: three sentences, both IDs, and",
|
||||
" `--outcome succeeded` or `failed`. You are done when it confirms; if it",
|
||||
" fails, follow the recovery it prints.",
|
||||
"5. Then end your turn.",
|
||||
"Stop, retry, or abandon a worker only on proof its agent stopped; silence or an",
|
||||
"`unverifiable` reading proves nothing.",
|
||||
"",
|
||||
"## References",
|
||||
"",
|
||||
"`ORCA skills get orchestration --reference references/<file>.md`",
|
||||
"",
|
||||
"| Situation | Reference |",
|
||||
"| -------------------------------------------------------------------------- | ----------------------------------------- |",
|
||||
"| Task DAGs, several waves or Runs, reusing a worker, model/effort | `references/coordinator-loop.md` |",
|
||||
"| Child or exact workspaces, folder workspaces, SSH, WSL, a connected server | `references/placement-and-remote.md` |",
|
||||
"| Decision gates, group messages, lost replies, old mail, older Orca | `references/messaging-and-gates.md` |",
|
||||
"| A failed, stuck, or unknown worker; stop, retry, abandon, release | `references/recovery-and-cleanup.md` |",
|
||||
"| A worker question the preamble does not answer | `references/worker-contract.md` |",
|
||||
"| Custom argv or terminal layout | `references/low-level-topology.md` |",
|
||||
"| Legacy labels, adopted Runs, takeover | `references/legacy-contract-migration.md` |",
|
||||
"| Situation | Reference |",
|
||||
"| ---------------------------------------------- | ----------------------------------------- |",
|
||||
"| Task DAGs, several Runs, reusing a worker | `references/coordinator-loop.md` |",
|
||||
"| Child worktrees, SSH, WSL, a connected server | `references/placement-and-remote.md` |",
|
||||
"| Group messages, inbox scripts | `references/messaging-and-gates.md` |",
|
||||
"| A failed or unknown worker; retry, stop, reset | `references/recovery-and-cleanup.md` |",
|
||||
"| Custom argv or terminal layout | `references/low-level-topology.md` |",
|
||||
"| Legacy labels, adopted Runs, takeover | `references/legacy-contract-migration.md` |",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
@@ -2471,9 +2424,8 @@ const ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN = [
|
||||
"",
|
||||
"## Task DAGs",
|
||||
"",
|
||||
"Create every Task before your first turn ends. Add `--deps` only for real",
|
||||
"dependencies; prefer parallel waves to long chains. Workers editing the same",
|
||||
"files at once need separate workspaces.",
|
||||
"A Task needs a Run, so create one first. Workers editing the same files at once",
|
||||
"need separate workspaces.",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration run-create --objective \"<goal>\" --json",
|
||||
@@ -2482,99 +2434,31 @@ const ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN = [
|
||||
"ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json",
|
||||
"```",
|
||||
"",
|
||||
"On every wake, start the Tasks `task-list --ready` shows. `--brief` shortens long specs (`spec_truncated` marks them); omit it when you",
|
||||
"need the full text. Pass `json_array` with the quoting rules of your shell.",
|
||||
"On every wake, start the Tasks `task-list --ready` shows.",
|
||||
"",
|
||||
"## Several Runs",
|
||||
"",
|
||||
"`worker-start --spec` creates a Run when you have none. A later `run-create`",
|
||||
"starts another Run and keeps the earlier ones: their mail still wakes you with",
|
||||
"`check --run <id>`, but commands without `--run` use the newest Run, so pass",
|
||||
"`--run <id>` when acting on an earlier one.",
|
||||
"`run-use` keeps only the Run it names.",
|
||||
"",
|
||||
"## Helpers and nesting",
|
||||
"",
|
||||
"Helpers a worker starts report to that worker, not you, and show in your",
|
||||
"`worker-list` with `creatorDispatchId`. Nesting is capped",
|
||||
"(`nested_worker_depth_exceeded`); a new Run does not reset it.",
|
||||
"",
|
||||
"## Model and effort",
|
||||
"",
|
||||
"Pass `--model` only when the user named a model; otherwise the worker uses its",
|
||||
"default. Add `--effort` only with `--model`, and only if that model",
|
||||
"supports it. Neither works with `--terminal`.",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration worker-start --task <task_id> --worktree current --agent claude --model opus --effort high --json",
|
||||
"```",
|
||||
"",
|
||||
"OpenCode takes `--model` only in an existing workspace, never `--effort`.",
|
||||
"Report the receipt's `launch.effective`, not your request.",
|
||||
"A later `run-create` keeps your earlier Runs: their mail still wakes you, but",
|
||||
"commands without `--run` use the newest Run, so pass `--run <id>` for an earlier",
|
||||
"one. `run-use` keeps only the Run it names.",
|
||||
"",
|
||||
"## Reusing a worker",
|
||||
"",
|
||||
"Finished terminal workers close about 2 minutes after `worker_done`. To give",
|
||||
"the same agent follow-up work, start the next Task on its terminal (this also",
|
||||
"stops the close):",
|
||||
"To give the same agent follow-up work, start the next Task on its terminal and",
|
||||
"workspace:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration worker-show --dispatch <dispatch_id> --json",
|
||||
"ORCA orchestration worker-start --task <next_task_id> --terminal <agent_terminal_handle> --worktree <its_workspace> --json",
|
||||
"```",
|
||||
"",
|
||||
"Run `worker-retain` only to keep one open with no follow-up yet;",
|
||||
"`worker-read` reads saved output.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
// oxfmt-ignore
|
||||
const ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN = [
|
||||
"# Legacy contract migration",
|
||||
"",
|
||||
"Use this only for a legacy label, adopted Run, compatibility receipt, or",
|
||||
"takeover. New work uses current commands.",
|
||||
"",
|
||||
"## Labels",
|
||||
"",
|
||||
"- `[LEGACY COMPATIBILITY]`: live. Run only the exact command printed with it,",
|
||||
" with the same executable.",
|
||||
"- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]`: a one-time replay. Handle it",
|
||||
" so a repeat does no harm, and acknowledge only as it says.",
|
||||
"- `[LEGACY READ-ONLY]`: look only; no reply, ack, or lifecycle change.",
|
||||
"- No label: current rules.",
|
||||
"",
|
||||
"A current Run, binding, or Dispatch wins over legacy fallback. An adoption",
|
||||
"record alone grants nothing. If ownership or the exact legacy contract is",
|
||||
"unproven, only inspect; never fall back to doing the work locally.",
|
||||
"",
|
||||
"Adoption keeps the live worker, terminal, workspace, Task, and Dispatch; it",
|
||||
"never restarts, replaces, or writes to them.",
|
||||
"",
|
||||
"## Compatibility receipts",
|
||||
"",
|
||||
"Run a receipt's next-step arguments exactly, with the same executable. If an",
|
||||
"`ask` may already be answered, run the recovery `check` Orca printed before",
|
||||
"asking again.",
|
||||
"",
|
||||
"On packaged Windows a legacy `ask` commits the question, prints an exact",
|
||||
"`ask --resume <message_id>` command, and exits with status `75`; run that",
|
||||
"command after the update. For WSL, keep the printed `orca-ide` executable.",
|
||||
"",
|
||||
"## Inspect and take over",
|
||||
"",
|
||||
"These only read:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration run-list --json",
|
||||
"ORCA orchestration run-show --id <adopted_run_id> --json",
|
||||
"ORCA orchestration task-list --run <adopted_run_id> --json",
|
||||
"ORCA orchestration check --terminal <legacy_handle> --peek --json",
|
||||
"ORCA terminal read --terminal <legacy_handle> --json",
|
||||
"```",
|
||||
"",
|
||||
"`run_legacy_local` is an empty record after adoption; the work lives in the Run",
|
||||
"whose objective is `Recovered orchestration work from a contract update`.",
|
||||
"Follow a legacy label's printed command exactly, with the same executable.",
|
||||
"",
|
||||
"Only if the original coordinator is gone or cannot prove ownership, take over",
|
||||
"from your own terminal:",
|
||||
@@ -2584,7 +2468,6 @@ const ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN = [
|
||||
"ORCA orchestration check --run <adopted_run_id> --json",
|
||||
"```",
|
||||
"",
|
||||
"Takeover fences only the old coordinator and keeps every worker and file.",
|
||||
"Never take over from an active coordinator, and never start a second editor",
|
||||
"just because Orca updated.",
|
||||
"",
|
||||
@@ -2594,24 +2477,15 @@ const ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN = [
|
||||
const ORCHESTRATION_LOW_LEVEL_TOPOLOGY_REFERENCE_MARKDOWN = [
|
||||
"# Low-level topology",
|
||||
"",
|
||||
"Use this only when `worker-start` cannot express the argv or terminal layout",
|
||||
"you need (model and effort are not custom argv).",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA terminal create --worktree active --title <task_name> --command \"<agent_command>\" --json",
|
||||
"ORCA terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json",
|
||||
"ORCA orchestration dispatch --task <task_id> --to <handle> --inject --json",
|
||||
"```",
|
||||
"",
|
||||
"Wait for `tui-idle` only when startup could drop injected input. If a",
|
||||
"`terminal send` submit is unconfirmed, rerun the same send with its receipt's",
|
||||
"`--retry-request <id>` and `--wait-submit <seconds>`; that never sends twice.",
|
||||
"",
|
||||
"`dispatch --inject` records the Task and Dispatch but does not supervise the",
|
||||
"process: worker commands report it `unsupervised`, `worker-stop` and",
|
||||
"`worker-abandon` leave it running, and release does not close it. To own an",
|
||||
"existing agent terminal, use `worker-start --terminal <handle>` instead. Never",
|
||||
"use low-level dispatch to get around the nesting cap or to hand work off.",
|
||||
"If a `terminal send` submit is unconfirmed, rerun the same send with its",
|
||||
"receipt's `--retry-request <id>` and `--wait-submit <seconds>`; that never sends",
|
||||
"twice.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
@@ -2619,55 +2493,12 @@ const ORCHESTRATION_LOW_LEVEL_TOPOLOGY_REFERENCE_MARKDOWN = [
|
||||
const ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN = [
|
||||
"# Messaging and gates",
|
||||
"",
|
||||
"## Reading mail",
|
||||
"Handle a whole `check` batch before the next `check`. Scripts that only watch",
|
||||
"the inbox must use `check --peek`, which marks nothing handled.",
|
||||
"",
|
||||
"`check --run <run_id>` returns your Run's oldest batch of mail (up to 50",
|
||||
"messages) and marks it handled; handle all of it before the next `check`.",
|
||||
"`--peek` only looks; scripts that watch the inbox must use it. `check` takes",
|
||||
"`--terminal <handle>`, never `--from`; an Orca terminal fills it in.",
|
||||
"",
|
||||
"- **Lost reply.** If a `check` or other mutation's reply was lost, rerun the",
|
||||
" same command with the `--retry-request <id>` it printed.",
|
||||
"- **Lost context.** Reread handled mail:",
|
||||
" `ORCA orchestration inbox --terminal run:<run_id> --limit 50 --full --json`",
|
||||
" (a worker uses `dispatch:<dispatch_id>`).",
|
||||
"",
|
||||
"## Addresses",
|
||||
"",
|
||||
"Steer one worker by its Dispatch, never by a terminal handle:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration send --to dispatch:<dispatch_id> --subject \"Follow-up\" --body \"<guidance>\" --json",
|
||||
"```",
|
||||
"",
|
||||
"Omit `--from` as a coordinator; a worker copies the `--from` in its preamble.",
|
||||
"",
|
||||
"Groups reach the live workers of your own Run: `@all`, `@idle`, and one per",
|
||||
"agent (`@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`,",
|
||||
"`@cursor`). `@worktree:<id>` reaches every Orca terminal in that workspace,",
|
||||
"coordinators included. Use groups only for deliberate fan-out. A worker raising a blocker",
|
||||
"sends to `run:<id>`.",
|
||||
"",
|
||||
"## Questions and gates",
|
||||
"",
|
||||
"A worker asks with `ask`; you answer with `reply --id <message_id>`. If its",
|
||||
"wait times out, the question stays pending and the worker resumes it.",
|
||||
"",
|
||||
"Use a gate only for a decision in your own Task DAG, never to answer an `ask`:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration gate-create --task <task_id> --question \"<decision>\" --options <json_array> --json",
|
||||
"ORCA orchestration gate-resolve --id <gate_id> --resolution \"<choice>\" --json",
|
||||
"ORCA orchestration gate-list --task <task_id> --json",
|
||||
"```",
|
||||
"",
|
||||
"## Older Orca",
|
||||
"",
|
||||
"- A `check` batch without `\"deliveryAcknowledged\": true` is not marked handled;",
|
||||
" ack it with `check --ack <delivery_id>` or it comes back.",
|
||||
"- A receipt without `next` means act on the result yourself.",
|
||||
"- If `worker-start` says the coordinator must be bound to a Run, run",
|
||||
" `ORCA orchestration run-create --objective \"<goal>\" --json`, then rerun it.",
|
||||
"Groups (`@all`, `@idle`, `@codex`, ...) reach the live workers of your Run;",
|
||||
"`@worktree:<id>` also reaches coordinators in that workspace. Use groups only",
|
||||
"for deliberate fan-out.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
@@ -2675,59 +2506,16 @@ const ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN = [
|
||||
const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [
|
||||
"# Placement and remote execution",
|
||||
"",
|
||||
"## Placement",
|
||||
"",
|
||||
"A new worker is a new agent, not a new worktree. Use the current or an",
|
||||
"existing workspace unless the user asked for a new one or sharing would",
|
||||
"conflict.",
|
||||
"",
|
||||
"```text",
|
||||
"# Current workspace; setup does not rerun.",
|
||||
"ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json",
|
||||
"",
|
||||
"# Child of the current worktree.",
|
||||
"ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json",
|
||||
"",
|
||||
"# New top-level worktree; --repo is needed outside that project.",
|
||||
"ORCA orchestration worker-start --task <task_id> --worktree new-top-level --repo id:<repoId> --name <name> --agent codex --setup run --json",
|
||||
"```",
|
||||
"",
|
||||
"`new-child`, and `new-top-level` without `--repo`, need you inside an Orca",
|
||||
"worktree.",
|
||||
"For an existing worktree, pass the full ID Orca returned as",
|
||||
"`id:<repo-id>::<path>`; a repo ID is not a worktree ID.",
|
||||
"",
|
||||
"## Folder workspaces",
|
||||
"",
|
||||
"Folders are first-class: never run Git or require a worktree for one. `repo add`",
|
||||
"rejects a plain folder; register it with:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA project setup-existing-folder --project <project_id> --host <host_id> --path <abs_path> --kind folder --json",
|
||||
"```",
|
||||
"",
|
||||
"Then place work there with its exact selector. `new-child` and `new-top-level`",
|
||||
"do not apply to folders.",
|
||||
"",
|
||||
"## Connected servers",
|
||||
"",
|
||||
"The Run stays on your server; `--on` picks only where the worker runs:",
|
||||
"",
|
||||
"```text",
|
||||
"# On a connected server; the Run stays on yours.",
|
||||
"ORCA orchestration worker-start --task <task_id> --on <environment> --worktree new-top-level --repo <exact_remote_repo_selector> --name <name> --agent codex --setup run --json",
|
||||
"```",
|
||||
"",
|
||||
"`current` and `new-child` are invalid with `--on`; use an exact remote",
|
||||
"workspace or `new-top-level` with an exact remote repo. After start, do",
|
||||
"everything by Dispatch ID (`send --to dispatch:<id>`, `worker-show`,",
|
||||
"`worker-read`, `worker-stop`) without `--on` or a remote terminal handle. A",
|
||||
"retry states `--on` and placement again. List remote workers with `worker-list --run <run_id> --include-remote`.",
|
||||
"",
|
||||
"The execution host owns process, file, and cleanup facts; lost contact reads",
|
||||
"`unverifiable`, never `exited`. Servers update separately, so optional fields",
|
||||
"may be missing.",
|
||||
"",
|
||||
"For WSL, run the exact executable Orca prints (such as `orca-ide`).",
|
||||
"After start, address a remote worker only by Dispatch ID, never by a terminal",
|
||||
"handle.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
@@ -2735,182 +2523,24 @@ const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [
|
||||
const ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN = [
|
||||
"# Recovery and cleanup",
|
||||
"",
|
||||
"Act only on proof. When you cannot tell, keep the work and report it as",
|
||||
"unknown.",
|
||||
"Act only on proof. `worker-list --run <run_id> --include-remote --json` gives",
|
||||
"each worker's liveness and `nextAction`; follow it.",
|
||||
"",
|
||||
"| What you can prove | Do this |",
|
||||
"| -------------------------- | ------------------------------------------------------- |",
|
||||
"| Running, or `unverifiable` | Wait or inspect; never stop, retry, abandon, or release |",
|
||||
"| `failed` or `stopped` | Retry with `--retry-of`, placement stated again |",
|
||||
"| `outcome_unknown` | Inspect, then choose `worker-stop` or `worker-abandon` |",
|
||||
"| `exited` agent | Follow the row's `nextAction` in `worker-list` |",
|
||||
"",
|
||||
"## Inspect",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration worker-list --run <run_id> --include-remote --json",
|
||||
"ORCA orchestration worker-show --dispatch <dispatch_id> --json",
|
||||
"ORCA orchestration worker-read --dispatch <dispatch_id> --limit 50 --json",
|
||||
"```",
|
||||
"",
|
||||
"`worker-list` decides whether an agent is alive (`projection.liveness`) and",
|
||||
"what to do (`projection.nextAction`). Without `--include-remote`, remote rows",
|
||||
"read `unverifiable`. Past 100 rows, page with `--cursor <page.nextCursor>`.",
|
||||
"",
|
||||
"`worker-show`'s `observation.status` covers only the terminal, so a `live`",
|
||||
"terminal can hold a dead agent. But when the list row is `unverifiable` with",
|
||||
"`missing_status`, `host_unavailable`, or `capability_unsupported`, a",
|
||||
"`worker-show` verdict from the execution host is better evidence.",
|
||||
"",
|
||||
"Continue `worker-read` with its cursor; on `source_changed`, drop the cursor.",
|
||||
"Never guess a session ID, transcript path, or remote terminal handle.",
|
||||
"",
|
||||
"## Proof that a worker stopped",
|
||||
"",
|
||||
"An `escalation` with `stopReason` means Orca saw the worker end its turn, or",
|
||||
"stop at a prompt, without `worker_done`; it carries the last output and the",
|
||||
"Dispatch stays open. Steer it with `send --to dispatch:<id>`, or `worker-stop`",
|
||||
"it and then retry. `exited` liveness is also proof. Silence, an unchanged",
|
||||
"`worker-read`, and `unverifiable` prove nothing.",
|
||||
"",
|
||||
"## Was the mutation applied?",
|
||||
"",
|
||||
"If a mutation's reply was lost, ask before rerunning:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration request-show --request <request_id> --json",
|
||||
"```",
|
||||
"",
|
||||
"`completed`: it took effect; use its receipt. `pending`: rerun the same command",
|
||||
"with `--retry-request <request_id>`. `absent`: unknown; inspect the Task,",
|
||||
"Dispatch, and terminal before retrying.",
|
||||
"",
|
||||
"## Refused starts",
|
||||
"",
|
||||
"`error.data.nextSteps`, when present, is the exact fix.",
|
||||
"",
|
||||
"| Code | Fix |",
|
||||
"| -------------------- | --------------------------------------------------------------------------- |",
|
||||
"| `task_not_found` | Check `task-list --json`; create the Task if missing |",
|
||||
"| `task_not_startable` | Wait for dependencies, or fix the failed one; a bad `--retry-of` lands here |",
|
||||
"| `inject_rejected` | Start a known agent in that terminal, or skip `--inject` |",
|
||||
"| Not bound to a Run | Older Orca: see `references/messaging-and-gates.md` |",
|
||||
"| `runtime_error` | Read the message and inspect; never rerun unchanged |",
|
||||
"",
|
||||
"A start that failed before its agent was ready still owns its terminal; release",
|
||||
"it with the `worker-release` its receipt names, never `terminal close`.",
|
||||
"",
|
||||
"## Retry, stop, abandon",
|
||||
"",
|
||||
"Retry by naming the Task (`--spec` would create a new one). Placement is not",
|
||||
"inherited:",
|
||||
"Retry a failed or stopped attempt on the same Task; `--spec` would create a new",
|
||||
"one. Placement is not inherited:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration worker-start --task <task_id> --retry-of <dispatch_id> --worktree <placement> --agent <agent> --json",
|
||||
"```",
|
||||
"",
|
||||
"Three failed starts fail the Task and refuse further retries; tell the user",
|
||||
"rather than working around it with a new Run or Task.",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration worker-stop --dispatch <dispatch_id> --json",
|
||||
"ORCA orchestration worker-abandon --dispatch <dispatch_id> --json",
|
||||
"```",
|
||||
"",
|
||||
"`worker-stop` closes only that worker's agent terminal, never the workspace or",
|
||||
"other terminals. Its `processAction` is `closed_agent_terminal` (do not also",
|
||||
"`terminal close`), `none`, or `unknown`. `stop_unknown` exits 1; check",
|
||||
"`worker-show` before acting again. `worker-abandon` only ends Orca's tracking;",
|
||||
"it touches no process or file and keeps the terminal open.",
|
||||
"",
|
||||
"To cancel a Task, stop or abandon its worker, then:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration task-update --id <task_id> --status failed --result cancelled --json",
|
||||
"```",
|
||||
"",
|
||||
"Its dependents stay blocked until a `--retry-of` replacement succeeds.",
|
||||
"",
|
||||
"## Retain and release",
|
||||
"",
|
||||
"Finished terminal workers close themselves about 2 minutes after `worker_done`;",
|
||||
"Orca saves their output first. `worker-retain` keeps one open; `worker-release`",
|
||||
"closes a chat worker or closes one early. Neither touches reused, pre-existing,",
|
||||
"setup, coordinator, active, or user-typed-in terminals. If a receipt says",
|
||||
"`release_pending` or `release_unknown`, follow its recovery.",
|
||||
"`worker-stop` exits 1 with `stop_unknown` when it cannot prove the agent",
|
||||
"stopped; check `worker-show` before acting again.",
|
||||
"",
|
||||
"`orchestration reset` deletes coordination state; run it only when the user",
|
||||
"gives that state up.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
// oxfmt-ignore
|
||||
const ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN = [
|
||||
"# Worker contract",
|
||||
"",
|
||||
"Your preamble is authoritative: copy its commands exactly, including any extra",
|
||||
"flag.",
|
||||
"",
|
||||
"## Ask",
|
||||
"",
|
||||
"Ask through Orca, never a local prompt the coordinator cannot see:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration ask --from <worker_handle> --question \"<question>\" --options \"<choice-a>,<choice-b>\" --timeout-ms 600000",
|
||||
"ORCA orchestration ask --from <worker_handle> --resume <message_id> --timeout-ms 600000",
|
||||
"```",
|
||||
"",
|
||||
"A wait lasts up to `--timeout-ms` (default 10 minutes, at most 30). On a",
|
||||
"timeout or disconnect the question stays pending: resume it by message ID; do",
|
||||
"not ask again.",
|
||||
"",
|
||||
"## Coordinator mail",
|
||||
"",
|
||||
"Nothing interrupts you; mail arrives only when you check. Check at natural",
|
||||
"checkpoints and once right before `worker_done`:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration check --terminal <worker_handle> --json",
|
||||
"```",
|
||||
"",
|
||||
"Repeat until `count` is 0. For a lost reply or lost context, and for older",
|
||||
"Orca, see `references/messaging-and-gates.md`.",
|
||||
"",
|
||||
"Never `run-use` the Run your Dispatch is in, or any parent Run. If a plain",
|
||||
"`check` returns `consumer_fenced`, you no longer own this Dispatch: stop, and",
|
||||
"send no `worker_done`. If `send` or `ask` returns it, you ran it from a terminal that is",
|
||||
"not yours.",
|
||||
"",
|
||||
"## Helpers",
|
||||
"",
|
||||
"Start helpers only as the preamble's SUB-DISPATCH section says. Their mail",
|
||||
"arrives in your `check`; answer with `reply`. Wait for every helper to settle",
|
||||
"before your `worker_done`, and name any that failed.",
|
||||
"",
|
||||
"## Escalate",
|
||||
"",
|
||||
"Only before you finish, and only when the coordinator must act:",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration send --from <worker_handle> --type escalation --subject \"Blocked: <reason>\" --body \"<details>\" --task-id <task_id> --dispatch-id <dispatch_id>",
|
||||
"```",
|
||||
"",
|
||||
"## Finish",
|
||||
"",
|
||||
"Send one `worker_done`. The body is three sentences: what changed, what you",
|
||||
"found, what remains. Use `--outcome failed` when the work is not done; never",
|
||||
"hide failure in prose. Add `--files-modified` or `--report-path` only with real",
|
||||
"paths.",
|
||||
"",
|
||||
"```text",
|
||||
"ORCA orchestration send --from <worker_handle> --type worker_done --subject \"<short status>\" --body \"<work, findings, remaining>\" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded",
|
||||
"```",
|
||||
"",
|
||||
"Then end your turn; do not poll or start other work. A later direct user",
|
||||
"request is new work: do it without the settled IDs.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
// oxfmt-ignore
|
||||
export const BUNDLED_SKILL_GUIDES = [
|
||||
{
|
||||
@@ -2981,6 +2611,6 @@ export const BUNDLED_SKILL_GUIDES = [
|
||||
description: "Run work in separate Orca worker agents and get their results back. Use when the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply, decision gates), or when the work needs something your own subagents cannot give: a different agent (such as Codex from Claude) or its own Orca workspace. Also use when you are a dispatched worker (a prompt with Task and Dispatch IDs: ask, worker_done). Otherwise prefer your own subagents, including for long or parallel work. Use `orca-cli` to hand work off with nothing expected back (\"hand off\", \"handover\", \"give this to another agent\", \"another worktree\"), and for terminal control, shell commands, worktree management, and reading or waiting on terminals.",
|
||||
markdown: ORCHESTRATION_MARKDOWN,
|
||||
aliases: [],
|
||||
references: [{ name: "coordinator-loop", markdown: ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN }, { name: "legacy-contract-migration", markdown: ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN }, { name: "low-level-topology", markdown: ORCHESTRATION_LOW_LEVEL_TOPOLOGY_REFERENCE_MARKDOWN }, { name: "messaging-and-gates", markdown: ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN }, { name: "placement-and-remote", markdown: ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN }, { name: "recovery-and-cleanup", markdown: ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN }, { name: "worker-contract", markdown: ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN }]
|
||||
references: [{ name: "coordinator-loop", markdown: ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN }, { name: "legacy-contract-migration", markdown: ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN }, { name: "low-level-topology", markdown: ORCHESTRATION_LOW_LEVEL_TOPOLOGY_REFERENCE_MARKDOWN }, { name: "messaging-and-gates", markdown: ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN }, { name: "placement-and-remote", markdown: ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN }, { name: "recovery-and-cleanup", markdown: ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN }]
|
||||
}
|
||||
] as const satisfies readonly BundledSkillGuide[]
|
||||
|
||||
Reference in New Issue
Block a user