@enderfga/claw-orchestrator 7.16.0 → 7.16.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/README.md +4 -4
  2. package/dist/src/claude-goal-session.d.ts +7 -3
  3. package/dist/src/claude-goal-session.js +7 -4
  4. package/dist/src/claude-goal-session.js.map +1 -1
  5. package/dist/src/council.js +2 -1
  6. package/dist/src/council.js.map +1 -1
  7. package/dist/src/kernel/agent-step.d.ts +8 -1
  8. package/dist/src/kernel/agent-step.js +1 -1
  9. package/dist/src/kernel/agent-step.js.map +1 -1
  10. package/dist/src/kernel/nodes/agent.d.ts +15 -0
  11. package/dist/src/kernel/nodes/agent.js +53 -15
  12. package/dist/src/kernel/nodes/agent.js.map +1 -1
  13. package/dist/src/kernel/nodes/goal.d.ts +10 -7
  14. package/dist/src/kernel/nodes/goal.js +33 -18
  15. package/dist/src/kernel/nodes/goal.js.map +1 -1
  16. package/dist/src/kernel/secrets.js +3 -2
  17. package/dist/src/kernel/secrets.js.map +1 -1
  18. package/dist/src/kernel/types.d.ts +6 -1
  19. package/dist/src/kernel/types.js.map +1 -1
  20. package/dist/src/models.js +8 -0
  21. package/dist/src/models.js.map +1 -1
  22. package/dist/src/persistent-agy-session.js +4 -0
  23. package/dist/src/persistent-agy-session.js.map +1 -1
  24. package/dist/src/persistent-session.d.ts +1 -0
  25. package/dist/src/persistent-session.js +3 -0
  26. package/dist/src/persistent-session.js.map +1 -1
  27. package/package.json +1 -1
  28. package/skills/references/claude-cli-tracking.md +2 -1
  29. package/skills/references/council.md +11 -0
  30. package/skills/references/multi-engine.md +6 -5
  31. package/skills/references/tools.md +1 -1
  32. package/skills/references/verification.md +0 -2
  33. package/skills/references/workflow.md +38 -28
package/skills/references/multi-engine.md CHANGED
@@ -45,7 +45,7 @@ as options (see the notes under [Antigravity](#google-antigravity-engine-agy) an
45
45
 
46
46
  ### Claude Code (`engine: 'claude'`)
47
47
 
48
- Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.310**.
48
+ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.316**.
49
49
 
50
50
  - Persistent multi-turn conversations
51
51
  - Real-time streaming (text, tool_use, tool_result, system events)
@@ -82,7 +82,7 @@ await manager.startSession({
82
82
 
83
83
  ### OpenAI Codex (`engine: 'codex'`)
84
84
 
85
- Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.164.0**.
85
+ Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.166.0**.
86
86
 
87
87
  - Non-interactive execution via `codex exec --sandbox workspace-write --skip-git-repo-check --json`
88
88
  - Real `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens). **These are cumulative over the thread, not per turn**, so they replace the session totals rather than being added to them; subtracting consecutive values gives one turn's prompt
@@ -120,7 +120,7 @@ await manager.startSession({
120
120
 
121
121
  ### OpenAI Codex App-Server (`engine: 'codex-app'`)
122
122
 
123
- Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no goal surface. Tested with `codex` CLI **0.164.0**.
123
+ Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no goal surface. Tested with `codex` CLI **0.166.0**.
124
124
 
125
125
  - Long-running subprocess; one `codex app-server` per session
126
126
  - JSON-RPC 2.0 over stdio with v2 protocol method names (`initialize`, `thread/start`, `turn/start`, ...)
@@ -152,7 +152,7 @@ await manager.codexGoal('codex-goal-task', { action: 'set', objective: 'build a
152
152
 
153
153
  Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
154
154
  Gemini CLI tiers stopped serving 2026-06-18). Each `send()` spawns a new process
155
- in print mode, with the message as the `-p` argument. Tested with `agy` **1.4.6**.
155
+ in print mode, with the message as the `-p` argument. Tested with `agy` **1.4.12**.
156
156
 
157
157
  - One-shot execution per message (no persistent subprocess)
158
158
  - **Structured output and real usage** — `--output-format stream-json` emits an
@@ -196,6 +196,7 @@ in print mode, with the message as the `-p` argument. Tested with `agy` **1.4.6*
196
196
  must explicitly choose `bypassPermissions` for a write-enabled session; it is
197
197
  not a recovery mechanism. In particular, an Autoloop Planner stays on
198
198
  `--mode plan` when its preserved conversation is resumed.
199
+ - `settings` is passed as `--settings`: settings.json keys as inline JSON or a file path, for this run only. agy refuses a key it does not know.
199
200
  - The engine always passes `--print-timeout`, set just inside the send timeout
200
201
  (10% earlier, at most 10s). Since agy 1.2.9 a headless run whose agent started a
201
202
  background task (a dev server, a watcher) stays open until that deadline and
@@ -304,7 +305,7 @@ await manager.startSession({
304
305
 
305
306
  ### OpenCode (`engine: 'opencode'`)
306
307
 
307
- Wraps the [OpenCode](https://github.com/anomalyco/opencode) CLI with `run --format json`. Each `send()` spawns a new process. Tested with `opencode` **1.19.4**.
308
+ Wraps the [OpenCode](https://github.com/anomalyco/opencode) CLI with `run --format json`. Each `send()` spawns a new process. Tested with `opencode` **1.19.5**.
308
309
 
309
310
  - Conversation continuity: the session id from the event envelope is captured and passed back as `--session <id>` on later sends, so the model sees prior turns. `--continue` is deliberately not used: it means "the last session on this machine", which collides between concurrent sessions.
310
311
  - NDJSON event stream with envelope `{ type, timestamp, sessionID, ... }`
package/skills/references/tools.md CHANGED
@@ -35,7 +35,7 @@ else the value applies.
35
35
  | `resumeSessionId` | string | Resume an earlier conversation by the engine's own id: a Claude Code session id, a Codex or `codex-app` thread id, an Antigravity conversation id, a Grok or OpenCode session id, an ACP agent's session id, or a custom engine's id when its config maps a resume flag |
36
36
  | `jsonSchema` | string | JSON Schema for structured output. Claude and Grok: `--json-schema` (inline). Codex: `--output-schema` (written to a temp file, requires Codex 0.132+). Other engines ignore it. |
37
37
  | `mcpConfig` | string \| string[] | MCP server config file(s) |
38
- | `settings` | string | Settings.json path or inline JSON |
38
+ | `settings` | string | Settings.json path or inline JSON, for this session only. Claude Code and Antigravity (`agy --settings`, which validates its keys) take it |
39
39
  | `pluginUrl` | string \| string[] | Claude only. Plugin `.zip` URL(s) fetched for this session only (`--plugin-url`) |
40
40
  | `ultracode` | boolean | Claude only. Enable "ultracode" / dynamic workflows — Claude plans a JS orchestration script per substantive task and fans out to subagents. Injected as the `ultracode:true` settings key (merged into `settings`). The workflow runs in the background: `session_send` returns at launch, and the completion turn is not returned by a later send (see [sessions.md](./sessions.md#ultracode-claude-dynamic-workflows)). |
41
41
  | `noSessionPersistence` | boolean | Do not save session to disk — both the engine's own transcript and this orchestrator's resume registry, so a later start under the same name does not reattach |
package/skills/references/verification.md CHANGED
@@ -20,8 +20,6 @@ goes through `normalizeContract()`, which drops anything it does not recognise,
20
20
  it carries no fields the executor did not model; one with no recognised check is
21
21
  refused before the run starts. That argument takes each check bare,
22
22
  `{ "type": "command", … }`, or wrapped, `{ "id"?, "spec": { … }, "required"? }`.
23
- A contract written inside a spec — `spec.contract`, or a verifier's inline
24
- `contract` — is used as written, so its checks must be in the wrapped form.
25
23
 
26
24
  A workflow start normalises every contract the run carries the same way: the
27
25
  `contract` start option, the spec's own `contract`, and each verifier node's
package/skills/references/workflow.md CHANGED
@@ -190,18 +190,18 @@ Every node has an `id` and a `kind`, plus these optional fields:
190
190
 
191
191
  The kind-specific fields:
192
192
 
193
- | Kind | Fields |
194
- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
195
- | `agent` | `prompt` (required); `engine`, `model`, `effort`, `acpAgent` (a bundled ACP preset id, for `engine: "acp"`); `cwd` (default: the run's); `sessionName`, to reuse one named session across nodes; `permissionMode` (default `bypassPermissions`); `appendSystemPrompt`, standing instructions for the session |
196
- | `fanout` | `prompt` (required, the shared task) and `agents` (required); `synthesize`, `synthesisEngine` (default `claude`), `synthesisModel`, `synthesisAcpAgent`, `synthesisPermissionMode` (default `bypassPermissions`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `cwd`; `agentTimeoutMs` |
197
- | `council` | `task` (required) and `agents` (required); `projectDir` (default: the run's cwd); `maxRounds` (default 15, as for `council_start`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `defaultPermissionMode`; `agentTimeoutMs` |
198
- | `verifier` | `contract` (required): an inline contract, or `"run"` for the run-level one; `cwd` (default: the run's) |
199
- | `human_gate` | `prompt` (required) |
200
- | `router` | `routes` (required): `[{ "when": <condition>, "to": <node id> }]`, first match wins; `default`, taken when nothing matches (omitted: fall through to the next node) |
201
- | `subflow` | `workflow` (required): an inline `WorkflowSpec`, or the id of an existing run, whose stored spec runs again as a new child run. Template names do not resolve here |
202
- | `goal` | `objective` (required); `engine`, `cwd`, `model`, `effort`, `sandboxMode`, `launcher`, `threadId`, `tokenBudget`, `capacityRetry`, `stallMs` — see [Goal](#goal) |
203
- | `autoloop` | `workspace` and `config` (the `autoloop_start` options). Started by `autoloop_start` |
204
- | `ultraapp_synth`, `ultraapp_deploy` | `appRunId`, `runDir`, `slug`; the deploy stage adds `version` and `codebasePath`. Started by UltraApp builds |
193
+ | Kind | Fields |
194
+ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195
+ | `agent` | `prompt` (required); `engine`, `model`, `effort`, `acpAgent` (a bundled ACP preset id, for `engine: "acp"`); `cwd` (default: the run's); `sessionName`, to keep one conversation across visits and nodes (each turn's process stops, and the next start under the name resumes the conversation; the name outlives the run, so make it unique to the run); `permissionMode` (default `bypassPermissions`); `appendSystemPrompt`, standing instructions for the session |
196
+ | `fanout` | `prompt` (required, the shared task) and `agents` (required); `synthesize`, `synthesisEngine` (default `claude`), `synthesisModel`, `synthesisAcpAgent`, `synthesisPermissionMode` (default `bypassPermissions`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `cwd`; `agentTimeoutMs` |
197
+ | `council` | `task` (required) and `agents` (required); `projectDir` (default: the run's cwd); `maxRounds` (default 15, as for `council_start`); `maxTurnsPerAgent` and `maxBudgetUsd`, per agent; `defaultPermissionMode`; `agentTimeoutMs` |
198
+ | `verifier` | `contract` (required): an inline contract, or `"run"` for the run-level one; `cwd` (default: the run's) |
199
+ | `human_gate` | `prompt` (required) |
200
+ | `router` | `routes` (required): `[{ "when": <condition>, "to": <node id> }]`, first match wins; `default`, taken when nothing matches (omitted: fall through to the next node) |
201
+ | `subflow` | `workflow` (required): an inline `WorkflowSpec`, or the id of an existing run, whose stored spec runs again as a new child run. Template names do not resolve here |
202
+ | `goal` | `objective` (required); `engine`, `cwd`, `model`, `effort`, `sandboxMode`, `launcher`, `threadId`, `tokenBudget`, `capacityRetry`, `stallMs` — see [Goal](#goal) |
203
+ | `autoloop` | `workspace` and `config` (the `autoloop_start` options). Started by `autoloop_start` |
204
+ | `ultraapp_synth`, `ultraapp_deploy` | `appRunId`, `runDir`, `slug`; the deploy stage adds `version` and `codebasePath`. Started by UltraApp builds |
205
205
 
206
206
  An entry in a fan-out's or council's `agents` takes `name` (required), `engine`,
207
207
  `model`, `effort`, `acpAgent`, `persona`, `prompt`, `permissionMode` and `baseUrl`;
@@ -306,11 +306,11 @@ with `visits_lt`.
306
306
  }
307
307
  ```
308
308
 
309
- A contract written inside a spec — the run-level `contract`, or a verifier's
310
- inline one — is used as written, so each check goes in the `{ "spec": { … } }`
311
- wrapper shown here, with `id` and `required` beside `spec`. The `contract` argument
312
- of `workflow_start` and `POST /workflow/new` is normalized first and also accepts
313
- bare checks (`{ "type": "command", … }`); when given, it replaces the spec's own.
309
+ Every contract a run carries — the run-level `contract`, a verifier's inline one,
310
+ and the `contract` argument of `workflow_start` and `POST /workflow/new` — is
311
+ normalized at start, so a check may be written bare (`{ "type": "command", … }`) or
312
+ in the `{ "spec": { … } }` wrapper shown here, with `id` and `required` beside
313
+ `spec`. The `contract` argument, when given, replaces the spec's own.
314
314
  See [`verification.md`](./verification.md#the-one-rule-about-where-contracts-come-from).
315
315
 
316
316
  When the router sends control back to `implement`, the agent is told what the
@@ -403,12 +403,19 @@ what an unattended run needs around that loop.
403
403
  of the checkpoint, so it carries across process restarts and repair visits.
404
404
  - **Repair on the same thread.** Revisited after a red verifier — a red verdict
405
405
  other than the one in force when its current objective was set — the node clears
406
- the finished goal and sets a new objective on the same thread: the failing
407
- checks first (as diagnostic data, like an agent node's repair brief), then the
408
- original objective. The agent keeps its context. The original objective is
409
- always kept whole; when both do not fit in 4,000 characters the checks are cut
410
- (the full output stays in the run's evidence). A first goal that was never set
411
- left nothing on its thread, so its revisit starts a new one.
406
+ the finished goal and sets a new objective on the same thread, carrying the
407
+ failing checks (as diagnostic data, like an agent node's repair brief) with the
408
+ original objective. The agent keeps its context. On Codex the checks come first,
409
+ as the definition of done. On Claude they come after the objective as context,
410
+ and the condition the goal is judged on stays the objective (see below). The
411
+ original objective is always kept whole; when the rest does not fit in 4,000
412
+ characters the checks are cut (the full output stays in the run's evidence). A
413
+ first goal that was never set left nothing on its thread, so its revisit starts
414
+ a new one.
415
+ - **A fresh thread is told why.** Any goal objective set while the run carries a
416
+ red verdict the node has not seen gets the failing checks: a revisit whose
417
+ thread was never set, and a different goal node that takes over after a red
418
+ verdict on its own first visit.
412
419
  - **Steering is live.** `workflow_steer` text goes into the running turn through
413
420
  `turn/steer`; with no turn running it waits for the next one. Text queued
414
421
  before the goal is set is put in front of the objective.
@@ -447,7 +454,9 @@ stream-json mode:
447
454
  asking to stop, and continuing only repeats that). The template's verifier
448
455
  still judges the tree. Write the objective as a condition the agent can show
449
456
  it met from inside the session; one that depends on something after the
450
- agent stops can never be met.
457
+ agent stops can never be met. That is why a repair objective on Claude does
458
+ not call the runtime's checks the definition of done: they run after the agent
459
+ stops, so the judge could never see them pass.
451
460
  - The session id is the thread id. A new session is started with
452
461
  `--session-id` so it is known before the goal is set, and the session is kept
453
462
  out of the registry with `skipPersistence` (not `noSessionPersistence`, which
@@ -456,8 +465,9 @@ stream-json mode:
456
465
  continues it at once.
457
466
  - Steers are written into the running turn, which the CLI folds in. Cancel and
458
467
  pause send stream-json's `interrupt` control request; the goal stays set.
459
- - `tokensUsed` counts the session's input, output and cache-read tokens, and is
460
- carried across reopened processes. `tokenBudget` counts from when the current
468
+ - `tokensUsed` counts the session's input, output and cache-write tokens, and is
469
+ carried across reopened processes. Cache reads are not counted: every turn
470
+ re-reads the whole cached conversation, which would spend a budget on re-reading. `tokenBudget` counts from when the current
461
471
  objective was set; past it the turn is interrupted and the goal ends
462
472
  `budgetLimited`. `sandboxMode` does not apply; put the boundary in `launcher`.
463
473
 
@@ -516,8 +526,8 @@ which is not the same as success.
516
526
  The implicit `__verify` is the last node, and a run only ends `completed` after
517
527
  its last node has run, so every such path is checked. A spec that places its own
518
528
  `"contract": "run"` verifier gets no `__verify`, and must route every path through
519
- that node: a run whose path skips it ends `completed` / `unverified`, with no
520
- check run.
529
+ that node: a run whose path skips it ends `failed` / `unverified`, with no check
530
+ run (see below).
521
531
 
522
532
  A run whose spec declares a run-level `contract` cannot complete without having
523
533
  run it. The kernel appends a terminal verifier unless the spec places its own