@enderfga/claw-orchestrator 7.5.3 → 7.5.5
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.
- package/README.md +21 -22
- package/configs/engines/README.md +7 -6
- package/dist/bin/cli.js +1 -1
- package/dist/bin/cli.js.map +1 -1
- package/dist/src/acp-server.d.ts +1 -1
- package/dist/src/acp-server.js +7 -5
- package/dist/src/acp-server.js.map +1 -1
- package/dist/src/autoloop/notify.d.ts +5 -7
- package/dist/src/autoloop/notify.js +21 -20
- package/dist/src/autoloop/notify.js.map +1 -1
- package/dist/src/embedded-server.js +8 -5
- package/dist/src/embedded-server.js.map +1 -1
- package/dist/src/fanout.d.ts +6 -0
- package/dist/src/fanout.js +1 -0
- package/dist/src/fanout.js.map +1 -1
- package/dist/src/index.js +21 -13
- package/dist/src/index.js.map +1 -1
- package/dist/src/kernel/engine.d.ts +39 -1
- package/dist/src/kernel/engine.js +120 -10
- package/dist/src/kernel/engine.js.map +1 -1
- package/dist/src/kernel/nodes/fanout.js +1 -0
- package/dist/src/kernel/nodes/fanout.js.map +1 -1
- package/dist/src/kernel/types.d.ts +9 -0
- package/dist/src/kernel/types.js.map +1 -1
- package/dist/src/openai-compat.d.ts +2 -2
- package/dist/src/openai-compat.js +5 -2
- package/dist/src/openai-compat.js.map +1 -1
- package/dist/src/session-manager.d.ts +7 -2
- package/dist/src/session-manager.js +21 -7
- package/dist/src/session-manager.js.map +1 -1
- package/dist/src/types.d.ts +2 -0
- package/openclaw.plugin.json +1 -1
- package/package.json +2 -2
- package/skills/SKILL.md +31 -32
- package/skills/references/acp.md +19 -36
- package/skills/references/autoloop.md +158 -180
- package/skills/references/claude-cli-tracking.md +27 -27
- package/skills/references/cli.md +62 -79
- package/skills/references/council.md +40 -63
- package/skills/references/dashboard.md +42 -55
- package/skills/references/getting-started.md +20 -14
- package/skills/references/inbox.md +6 -4
- package/skills/references/mcp.md +29 -24
- package/skills/references/multi-engine.md +105 -153
- package/skills/references/observability.md +42 -32
- package/skills/references/openai-compat.md +169 -303
- package/skills/references/sessions.md +20 -29
- package/skills/references/tools.md +67 -78
- package/skills/references/ultra.md +17 -16
- package/skills/references/ultraapp.md +59 -64
- package/skills/references/verification.md +29 -52
- package/skills/references/workflow.md +49 -107
- package/skills/ultraapp/SKILL.md +9 -10
|
@@ -27,14 +27,14 @@ const info = await manager.startSession({
|
|
|
27
27
|
|
|
28
28
|
Key options:
|
|
29
29
|
|
|
30
|
-
| Option | Description
|
|
31
|
-
| -------------------- |
|
|
32
|
-
| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md)
|
|
33
|
-
| `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name
|
|
34
|
-
| `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`)
|
|
35
|
-
| `effort` | `low`, `medium`, `high`, `max`, `auto`
|
|
36
|
-
| `bare` | Skip hooks, LSP, auto-memory, CLAUDE.md
|
|
37
|
-
| `worktree` | Run in isolated git worktree
|
|
30
|
+
| Option | Description |
|
|
31
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
|
|
33
|
+
| `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name |
|
|
34
|
+
| `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
|
|
35
|
+
| `effort` | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` — each engine clamps to its own ladder (see [Multi-Engine](./multi-engine.md)) |
|
|
36
|
+
| `bare` | Skip hooks, LSP, auto-memory, CLAUDE.md |
|
|
37
|
+
| `worktree` | Run in isolated git worktree |
|
|
38
38
|
| `appendSystemPrompt` | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
|
|
39
39
|
|
|
40
40
|
### Sending Messages
|
|
@@ -120,10 +120,6 @@ source's record, so handing it off again carries the whole conversation rather t
|
|
|
120
120
|
part. The history is cleared only after a first send succeeds, so a first turn that fails on the
|
|
121
121
|
new engine does not strand the conversation it was carrying.
|
|
122
122
|
|
|
123
|
-
Verified end to end over MCP against the installed engines: a fact planted in a Claude session was
|
|
124
|
-
recalled by Codex 0.154.0 after a handoff, and again by Claude after a second handoff back, which
|
|
125
|
-
also named Codex as the engine it had taken over from.
|
|
126
|
-
|
|
127
123
|
### ultracode (Claude dynamic workflows)
|
|
128
124
|
|
|
129
125
|
Set `ultracode: true` on a Claude `session_start` to have Claude orchestrate a JS workflow per substantive task and fan out to subagents. It is injected as the `ultracode: true` settings key merged into `--settings`:
|
|
@@ -141,7 +137,7 @@ Code session. Read the outcome by sending a follow-up once the workflow has had
|
|
|
141
137
|
|
|
142
138
|
### Codex app-server turn control (`engine: 'codex-app'`)
|
|
143
139
|
|
|
144
|
-
Mid-turn and thread control via Codex
|
|
140
|
+
Mid-turn and thread control via the Codex app-server v2 RPCs, surfaced as tools: `codex_interrupt` (cancel the in-flight turn), `codex_steer` (add input without restarting), `codex_fork` (branch the thread), `codex_rollback` (drop the last N turns), `codex_models` (list models + supported reasoning efforts), `codex_thread_list` (list the threads the session can see).
|
|
145
141
|
|
|
146
142
|
### Fan-out (cross-engine parallel)
|
|
147
143
|
|
|
@@ -215,7 +211,7 @@ in cleanup), `gemini` succeeds on exit 53 because its turn limit resolves,
|
|
|
215
211
|
read-only enforcement did not load.
|
|
216
212
|
|
|
217
213
|
**A succeeded turn is not a turn that did the work.** When the engine refuses a
|
|
218
|
-
tool call it usually does not fail the turn.
|
|
214
|
+
tool call it usually does not fail the turn. On Claude Code with
|
|
219
215
|
`--permission-prompts none` — which a session gets whenever no prompt tool is
|
|
220
216
|
configured — a turn asked to write a file came back `subtype: 'success'`,
|
|
221
217
|
`is_error: false`, with the refused Bash call listed in the result event and no
|
|
@@ -246,7 +242,7 @@ Built-in format translation lets Claude Code CLI talk to non-Anthropic models:
|
|
|
246
242
|
- **Gemini** thought signature caching (round-trip thinking)
|
|
247
243
|
- Auto-detect provider from model name patterns
|
|
248
244
|
|
|
249
|
-
See `src/proxy/` for implementation details.
|
|
245
|
+
See [`src/proxy/`](https://github.com/Enderfga/claw-orchestrator/tree/main/src/proxy) for implementation details.
|
|
250
246
|
|
|
251
247
|
## Circuit Breaker
|
|
252
248
|
|
|
@@ -258,7 +254,7 @@ SessionManager tracks consecutive failures per engine type. After 3 consecutive
|
|
|
258
254
|
|
|
259
255
|
## Orphaned Process Cleanup
|
|
260
256
|
|
|
261
|
-
If the plugin crashes without calling `stop()`, child CLI processes (claude, codex, agy,
|
|
257
|
+
If the plugin crashes without calling `stop()`, child CLI processes (claude, codex, agy, grok, opencode, and legacy engines) may become orphans. SessionManager tracks PIDs in `~/.openclaw/session-pids.json` and cleans up stale processes on startup:
|
|
262
258
|
|
|
263
259
|
1. Reads PID file from previous run
|
|
264
260
|
2. For each PID, checks if process is alive (`kill -0`)
|
|
@@ -270,18 +266,13 @@ If the plugin crashes without calling `stop()`, child CLI processes (claude, cod
|
|
|
270
266
|
|
|
271
267
|
Session stats are returned by `getStats()` and surfaced through `coding_session_status`.
|
|
272
268
|
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
| Field | Type | Description |
|
|
276
|
-
| ---------------- | ------------------- | -------------------------------------------------- |
|
|
277
|
-
| `retries` | number | Total API retries that occurred during the session |
|
|
278
|
-
| `lastRetryError` | string \| undefined | Error message from the most recent retry (if any) |
|
|
279
|
-
|
|
280
|
-
Fields added in plugin v2.14.0 (Claude CLI 2.1.121):
|
|
269
|
+
Claude Code–specific stats:
|
|
281
270
|
|
|
282
|
-
| Field
|
|
283
|
-
|
|
|
284
|
-
| `
|
|
271
|
+
| Field | Type | Description |
|
|
272
|
+
| ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
273
|
+
| `retries` | number | Total API retries that occurred during the session |
|
|
274
|
+
| `lastRetryError` | string \| undefined | Error message from the most recent retry (if any) |
|
|
275
|
+
| `pluginErrors` | `Array<{plugin, reason}>` \| undefined | Plugins that failed to load due to unmet dependencies, captured from the `system/init` event. `undefined` when no plugin errors occurred. |
|
|
285
276
|
|
|
286
277
|
### `system/api_retry` events
|
|
287
278
|
|
|
@@ -304,7 +295,7 @@ const session = manager.getSession('my-session');
|
|
|
304
295
|
console.log(session.pid); // e.g., 12345 or undefined
|
|
305
296
|
```
|
|
306
297
|
|
|
307
|
-
## Verifying what a session did
|
|
298
|
+
## Verifying what a session did
|
|
308
299
|
|
|
309
300
|
A plain session leaves no verdict — it ran, and nothing checked the result. To
|
|
310
301
|
check it, hand `verify_run` a contract and the directory:
|
|
@@ -319,5 +310,5 @@ verify_run({
|
|
|
319
310
|
For work that should be checked as part of running it, use a workflow instead —
|
|
320
311
|
see [`workflow.md`](./workflow.md).
|
|
321
312
|
|
|
322
|
-
`SendOptions` also
|
|
313
|
+
`SendOptions` also accepts `nodeKind` and `taskKind`, both stamped onto the run
|
|
323
314
|
ledger row. `taskKind` is caller-declared and never inferred from the prompt.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Tools Reference
|
|
2
2
|
|
|
3
|
-
All tools are registered as
|
|
3
|
+
All 78 tools are registered as OpenClaw plugin tools and exposed over MCP by `clawo-mcp` (see [mcp.md](./mcp.md)). The embedded HTTP server covers a subset of them.
|
|
4
4
|
|
|
5
5
|
## Session Lifecycle (6)
|
|
6
6
|
|
|
@@ -16,18 +16,17 @@ Start a persistent coding session with full CLI flag support.
|
|
|
16
16
|
| `model` | string | Model alias or full name |
|
|
17
17
|
| `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
|
|
18
18
|
| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values. `read-only` is enforced on every other built-in engine too: Claude → plan mode; Antigravity → its plan mode; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. **`grok` refuses a read-only session** rather than approximate one — its enforcement has not been adversarially verified. A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
|
|
19
|
-
| `effort` | string | `low`, `medium`, `high`, `max`, `auto` |
|
|
20
19
|
| `allowedTools` | string[] | Tools to auto-approve |
|
|
21
20
|
| `disallowedTools` | string[] | Tools to deny |
|
|
22
21
|
| `maxTurns` | number | Max agent loop turns |
|
|
23
22
|
| `maxBudgetUsd` | number | Max API spend (USD). Enforced by the runtime on every engine: once the session's cumulative cost reaches the cap, further sends are refused before the engine is spawned. See [observability.md](observability.md) for the accuracy caveat on engines that estimate token counts. |
|
|
24
23
|
| `systemPrompt` | string | Replace system prompt |
|
|
25
|
-
| `appendSystemPrompt` | string | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation
|
|
24
|
+
| `appendSystemPrompt` | string | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
|
|
26
25
|
| `agents` | object | Custom sub-agents JSON |
|
|
27
26
|
| `agent` | string | Default agent to use |
|
|
28
27
|
| `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
|
|
29
28
|
| `worktree` | string \| boolean | Run in git worktree |
|
|
30
|
-
| `fallbackModel` | string
|
|
29
|
+
| `fallbackModel` | string \| string[] | Fallback model(s) when the primary is overloaded; an array is tried in order |
|
|
31
30
|
| `resumeSessionId` | string | Resume existing session by ID |
|
|
32
31
|
| `jsonSchema` | string | JSON Schema for structured output. Claude: `--json-schema` (inline). Codex: `--output-schema` (written to a temp file, requires Codex 0.132+). Other engines ignore it. |
|
|
33
32
|
| `mcpConfig` | string \| string[] | MCP server config file(s) |
|
|
@@ -35,20 +34,21 @@ Start a persistent coding session with full CLI flag support.
|
|
|
35
34
|
| `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). |
|
|
36
35
|
| `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 |
|
|
37
36
|
| `ignoreUserConfig` | boolean | Codex only. Run without loading `$CODEX_HOME/config.toml`, so an orchestrated run is decided by what the caller passed rather than by the machine's own Codex config — notably a `model = …` line in that file, which otherwise picks the model while the ledger records this engine's default. Auth still resolves from `CODEX_HOME`. |
|
|
37
|
+
| `codexProfile` | string | Codex only. Named profile from `~/.codex/config.toml`, passed as `codex exec --profile` |
|
|
38
38
|
| `restricted` | boolean | Claude Code only. Restricted mode (`--restricted`): the CLI removes the built-in tools that run commands or code — Bash, PowerShell, the REPL — plus `WebFetch` unless `tools` names them, and ignores user, project and local settings files. Separate from `sandboxMode: 'read-only'`: that maps to plan mode, which holds on its own, while this makes the shell absent rather than refused. It also drops the caller's CLAUDE.md and hooks, so it is never switched on implicitly. |
|
|
39
39
|
| `betas` | string \| string[] | Custom beta headers |
|
|
40
40
|
| `enableAgentTeams` | boolean | Enable experimental agent teams |
|
|
41
41
|
| `enableAutoMode` | boolean | Enable auto permission mode |
|
|
42
|
-
| `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-
|
|
42
|
+
| `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-engine-custom). |
|
|
43
43
|
| `crossSessionInbound` | string | `accept` / `hold` / `refuse` — policy for peer messages from other Claude Code sessions on this machine (Claude engine). Delivered as a settings key; there is no CLI flag. Without it the CLI holds messages whose two sides run different permission modes, which is the usual orchestrated-session-to-human-terminal case |
|
|
44
44
|
| `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
|
|
45
45
|
| `forwardSubagentText` | boolean | Forward subagent text and thinking into the output stream (Claude engine, CLI 2.1.211+). Without it the parent stream stays quiet while a subagent works |
|
|
46
|
-
| `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use) When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout.
|
|
46
|
+
| `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use). When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout. |
|
|
47
47
|
| `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
|
|
48
48
|
| `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
|
|
49
|
-
| `debug` | string
|
|
49
|
+
| `debug` | string \| string[] | Debug categories to enable (e.g. `"api,mcp"` or `["api", "mcp"]`) |
|
|
50
50
|
| `debugFile` | string | File path to write debug output to |
|
|
51
|
-
| `fromPr` | string
|
|
51
|
+
| `fromPr` | string | Resume a session linked to a GitHub PR number or URL |
|
|
52
52
|
| `channels` | string \| string[] | MCP channel subscription spec (research preview) |
|
|
53
53
|
| `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
|
|
54
54
|
| `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
|
|
@@ -119,7 +119,7 @@ Dashboard view: all sessions with ready/busy/paused state, cost, context %, last
|
|
|
119
119
|
|
|
120
120
|
### `coding_session_status`
|
|
121
121
|
|
|
122
|
-
Detailed status: tokens, cost, context %, tool calls, uptime. (
|
|
122
|
+
Detailed status: tokens, cost, context %, tool calls, uptime. (Prefixed to avoid clashing with OpenClaw's built-in `session_status`.)
|
|
123
123
|
|
|
124
124
|
| Parameter | Type | Required |
|
|
125
125
|
| --------- | ------ | -------- |
|
|
@@ -190,9 +190,9 @@ Returns `{ ok, stdout, stderr, dryRun }`.
|
|
|
190
190
|
|
|
191
191
|
---
|
|
192
192
|
|
|
193
|
-
## Claude (
|
|
193
|
+
## Claude (5)
|
|
194
194
|
|
|
195
|
-
Tools targeting Claude Code's CLI. `plugin_details`
|
|
195
|
+
Tools targeting Claude Code's CLI. `plugin_details` and `claude_agents_list` are one-shot wrappers. The `claude_goal_*` tools require a session started with `engine: "claude"` (the default) and pre-format the `/goal` slash command introduced in CLI 2.1.139.
|
|
196
196
|
|
|
197
197
|
### `plugin_details`
|
|
198
198
|
|
|
@@ -240,6 +240,17 @@ Returns the regular turn result; goal info is in the assistant's reply text.
|
|
|
240
240
|
|
|
241
241
|
> Note: Claude's `/goal` is interactive-only in the upstream TUI sense — it has no dedicated CLI flag or JSON event. These wrappers work because Claude Code interprets slash-prefixed user messages in non-interactive (`-p` / stream-json) mode the same way. The wrappers exist for engine-guard and discoverability, not protocol translation.
|
|
242
242
|
|
|
243
|
+
### `claude_agents_list`
|
|
244
|
+
|
|
245
|
+
Wraps `claude agents --json` — lists Claude Code background agent sessions (state/model/title/progress). One-shot spawn, not tied to a managed session. (`claude continue/respawn/stop/logs` do not exist as headless subcommands; use `resumeSessionId` on `session_start` to resume.)
|
|
246
|
+
|
|
247
|
+
| Parameter | Type | Description |
|
|
248
|
+
| --------- | ------- | --------------------------------------------------------- |
|
|
249
|
+
| `all` | boolean | Include completed sessions (`--all`). |
|
|
250
|
+
| `cwd` | string | Scope to sessions started under this directory (`--cwd`). |
|
|
251
|
+
|
|
252
|
+
Returns `{ ok, agents }`.
|
|
253
|
+
|
|
243
254
|
---
|
|
244
255
|
|
|
245
256
|
## Codex (13)
|
|
@@ -313,11 +324,11 @@ Send `/goal pause`, `/goal resume`, or `/goal clear` respectively. Requires `eng
|
|
|
313
324
|
|
|
314
325
|
Returns `{ ok, text, goal }`.
|
|
315
326
|
|
|
316
|
-
> **Stability note:** Codex's `goals` feature is
|
|
327
|
+
> **Stability note:** Codex's `goals` feature is experimental upstream. The wrapper only formats the `/goal` slash text, so upstream changes affect that text, not the protocol.
|
|
317
328
|
|
|
318
|
-
###
|
|
329
|
+
### Codex app-server RPCs
|
|
319
330
|
|
|
320
|
-
Codex app-server v2
|
|
331
|
+
`codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models` and `codex_thread_list` call Codex app-server v2 methods and require `engine: "codex-app"`. Method names and parameter shapes follow `codex app-server generate-json-schema`.
|
|
321
332
|
|
|
322
333
|
| Tool | RPC | Params | Returns |
|
|
323
334
|
| ------------------- | ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
@@ -334,21 +345,6 @@ opening a fresh one.
|
|
|
334
345
|
|
|
335
346
|
---
|
|
336
347
|
|
|
337
|
-
## Claude CLI (1)
|
|
338
|
-
|
|
339
|
-
### `claude_agents_list`
|
|
340
|
-
|
|
341
|
-
Wraps `claude agents --json` — lists Claude Code background agent sessions (state/model/title/progress). One-shot spawn, not tied to a managed session. (`claude continue/respawn/stop/logs` do not exist as headless subcommands; use `resumeSessionId` on `session_start` to resume.)
|
|
342
|
-
|
|
343
|
-
| Parameter | Type | Description |
|
|
344
|
-
| --------- | ------- | --------------------------------------------------------- |
|
|
345
|
-
| `all` | boolean | Include completed sessions (`--all`). |
|
|
346
|
-
| `cwd` | string | Scope to sessions started under this directory (`--cwd`). |
|
|
347
|
-
|
|
348
|
-
Returns `{ ok, agents }`.
|
|
349
|
-
|
|
350
|
-
---
|
|
351
|
-
|
|
352
348
|
## Fan-out (3)
|
|
353
349
|
|
|
354
350
|
Run one task across N engine/model agents **in parallel** and collect their answers, with an optional synthesis pass. Cross-engine best-of-N / diverse-perspective primitive — no rounds, votes, or git worktrees. For isolated parallel _editing_, use Council.
|
|
@@ -382,7 +378,7 @@ Abort a running fan-out by `id` (already-started agents finish; synthesis is ski
|
|
|
382
378
|
|
|
383
379
|
### `coding_agents_list`
|
|
384
380
|
|
|
385
|
-
List agent definitions from `.claude/agents/` (project + global). (
|
|
381
|
+
List agent definitions from `.claude/agents/` (project + global). (Prefixed to avoid clashing with OpenClaw's built-in `agents_list`.)
|
|
386
382
|
|
|
387
383
|
| Parameter | Type |
|
|
388
384
|
| --------- | ------ |
|
|
@@ -542,15 +538,16 @@ Get status and plan text when completed.
|
|
|
542
538
|
|
|
543
539
|
### `ultrareview_start`
|
|
544
540
|
|
|
545
|
-
|
|
541
|
+
Start 1–20 reviewer agents that review the code in parallel, each from a different angle. Runs in background.
|
|
546
542
|
|
|
547
|
-
| Parameter | Type
|
|
548
|
-
| -------------------- |
|
|
549
|
-
| `cwd` | string
|
|
550
|
-
| `agentCount` | number
|
|
551
|
-
| `maxDurationMinutes` | number
|
|
552
|
-
| `model` | string
|
|
553
|
-
| `focus` | string
|
|
543
|
+
| Parameter | Type | Required | Description |
|
|
544
|
+
| -------------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
|
|
545
|
+
| `cwd` | string | yes | Project directory |
|
|
546
|
+
| `agentCount` | number | | Agents (1-20, default 5) |
|
|
547
|
+
| `maxDurationMinutes` | number | | Duration (5-25 min, default 10) |
|
|
548
|
+
| `model` | string | | Model for reviewers |
|
|
549
|
+
| `focus` | string | | Review focus area |
|
|
550
|
+
| `engines` | string[] | | Engines to spread reviewers across (default `["claude"]`). Every reviewer runs read-only, so `grok` and `custom` are not allowed |
|
|
554
551
|
|
|
555
552
|
### `ultrareview_status`
|
|
556
553
|
|
|
@@ -597,21 +594,13 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
|
|
|
597
594
|
> permission to choose what binary runs. Built-in engines stay fully selectable
|
|
598
595
|
> over HTTP.
|
|
599
596
|
>
|
|
600
|
-
>
|
|
601
|
-
>
|
|
602
|
-
>
|
|
603
|
-
>
|
|
604
|
-
>
|
|
605
|
-
>
|
|
606
|
-
>
|
|
607
|
-
> gap: a custom-engine run that crashed could not be brought back by any remote
|
|
608
|
-
> caller, because the material it needed had nowhere to come from. So a remote
|
|
609
|
-
> resume names the secret instead of carrying it — `plannerCustomEngineRef` and
|
|
610
|
-
> friends on `POST /autoloop/<id>/resume`, `agentCustomEngineRefs` on
|
|
611
|
-
> `workflow_resume` — and the orchestrator resolves the name against its own
|
|
612
|
-
> `CLAWO_CUSTOM_ENGINE_<NAME>` environment. `GET /autoloop/<id>/resume-requirements`
|
|
613
|
-
> says which roles need one. The name is not sensitive, the value never leaves the
|
|
614
|
-
> host, and an unknown name fails loudly rather than starting without credentials.
|
|
597
|
+
> **Resuming by reference.** A remote resume names the credential instead of
|
|
598
|
+
> carrying it — `plannerCustomEngineRef` and friends on `POST /autoloop/<id>/resume`,
|
|
599
|
+
> `agentCustomEngineRefs` on `workflow_resume` — and the orchestrator resolves the
|
|
600
|
+
> name against its own `CLAWO_CUSTOM_ENGINE_<NAME>` environment.
|
|
601
|
+
> `GET /autoloop/<id>/resume-requirements` lists which roles need one. The name is
|
|
602
|
+
> not sensitive, the value never leaves the host, and an unknown name fails rather
|
|
603
|
+
> than starting without credentials.
|
|
615
604
|
|
|
616
605
|
Custom configs are not persisted or accepted from Planner output. See [`multi-engine.md`](./multi-engine.md) for their shape.
|
|
617
606
|
|
|
@@ -626,7 +615,7 @@ when it coincides with lease expiry.
|
|
|
626
615
|
Recovery is exposed by `POST /autoloop/<id>/resume`, not by an MCP resume tool.
|
|
627
616
|
Its timeout body is limited to `send_timeout_ms` plus
|
|
628
617
|
`pending_dispatch_id`. The send timeout must be finite, in range, and strictly
|
|
629
|
-
larger than the run's latest effective value (
|
|
618
|
+
larger than the run's latest effective value (600000 for runs that predate this setting). Equal
|
|
630
619
|
or smaller values are rejected, and there is deliberately no
|
|
631
620
|
`allow_decrease`. Lease and hard-cap overrides are not accepted on resume.
|
|
632
621
|
Each successful increase appends one migration row to `decisions.jsonl`; the
|
|
@@ -695,7 +684,7 @@ Full snapshot of a run: spec + chat + state.
|
|
|
695
684
|
|
|
696
685
|
| Parameter | Type | Required |
|
|
697
686
|
| --------- | ------ | -------- |
|
|
698
|
-
| `
|
|
687
|
+
| `runId` | string | yes |
|
|
699
688
|
|
|
700
689
|
### `ultraapp_status`
|
|
701
690
|
|
|
@@ -703,15 +692,13 @@ Lightweight status (mode + timestamps).
|
|
|
703
692
|
|
|
704
693
|
| Parameter | Type | Required |
|
|
705
694
|
| --------- | ------ | -------- |
|
|
706
|
-
| `
|
|
695
|
+
| `runId` | string | yes |
|
|
707
696
|
|
|
708
697
|
### `ultraapp_new`
|
|
709
698
|
|
|
710
|
-
Create a fresh run
|
|
699
|
+
Create a fresh run and start the interview session. Returns `{ ok, runId }`. The first question arrives via `ultraapp_get`.
|
|
711
700
|
|
|
712
|
-
|
|
713
|
-
| -------------- | ------ | -------- | ----------------------------------------------------------------------------- |
|
|
714
|
-
| `firstMessage` | string | | Free-form opening line; the interview Opus reads it before its first question |
|
|
701
|
+
(no params)
|
|
715
702
|
|
|
716
703
|
### `ultraapp_answer`
|
|
717
704
|
|
|
@@ -719,19 +706,18 @@ Submit an answer to the current interview question.
|
|
|
719
706
|
|
|
720
707
|
| Parameter | Type | Required | Description |
|
|
721
708
|
| ---------- | ------ | -------- | -------------------------------------------------------------------- |
|
|
722
|
-
| `
|
|
709
|
+
| `runId` | string | yes | Run id |
|
|
723
710
|
| `value` | string | yes | One of the question's `options[].value`, or `''` when using freeform |
|
|
724
711
|
| `freeform` | string | | Free-form text when none of the options fit |
|
|
725
712
|
|
|
726
713
|
### `ultraapp_add_file`
|
|
727
714
|
|
|
728
|
-
|
|
715
|
+
Reference a local example file by absolute path (under `$HOME` or `/tmp`; symlinks and dotfiles are rejected). The interview extracts metadata from it. To upload a file from a browser, use the dashboard.
|
|
729
716
|
|
|
730
|
-
| Parameter
|
|
731
|
-
|
|
|
732
|
-
| `
|
|
733
|
-
| `
|
|
734
|
-
| `content` | string \| Buffer | yes |
|
|
717
|
+
| Parameter | Type | Required |
|
|
718
|
+
| -------------- | ------ | -------- |
|
|
719
|
+
| `runId` | string | yes |
|
|
720
|
+
| `absolutePath` | string | yes |
|
|
735
721
|
|
|
736
722
|
### `ultraapp_spec_edit`
|
|
737
723
|
|
|
@@ -739,7 +725,7 @@ Apply RFC 6902 JSON Patch ops to the AppSpec mid-interview.
|
|
|
739
725
|
|
|
740
726
|
| Parameter | Type | Required |
|
|
741
727
|
| --------- | -------- | -------- |
|
|
742
|
-
| `
|
|
728
|
+
| `runId` | string | yes |
|
|
743
729
|
| `patch` | object[] | yes |
|
|
744
730
|
|
|
745
731
|
### `ultraapp_build_start`
|
|
@@ -748,7 +734,7 @@ Validate the spec strictly (shape + cross-refs + DAG) and enqueue the build. Cou
|
|
|
748
734
|
|
|
749
735
|
| Parameter | Type | Required |
|
|
750
736
|
| --------- | ------ | -------- |
|
|
751
|
-
| `
|
|
737
|
+
| `runId` | string | yes |
|
|
752
738
|
|
|
753
739
|
### `ultraapp_build_cancel`
|
|
754
740
|
|
|
@@ -756,7 +742,7 @@ Abort an active build. Council sessions are stopped and the worktrees are left a
|
|
|
756
742
|
|
|
757
743
|
| Parameter | Type | Required |
|
|
758
744
|
| --------- | ------ | -------- |
|
|
759
|
-
| `
|
|
745
|
+
| `runId` | string | yes |
|
|
760
746
|
|
|
761
747
|
### `ultraapp_feedback`
|
|
762
748
|
|
|
@@ -764,7 +750,7 @@ Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spe
|
|
|
764
750
|
|
|
765
751
|
| Parameter | Type | Required | Description |
|
|
766
752
|
| --------- | ------ | -------- | ----------------------- |
|
|
767
|
-
| `
|
|
753
|
+
| `runId` | string | yes | Run id |
|
|
768
754
|
| `text` | string | yes | The feedback (1+ chars) |
|
|
769
755
|
|
|
770
756
|
### `ultraapp_promote_version`
|
|
@@ -773,7 +759,7 @@ Atomically swap the deployed version. Stops the current container/process, start
|
|
|
773
759
|
|
|
774
760
|
| Parameter | Type | Required | Description |
|
|
775
761
|
| --------- | ------ | -------- | ------------------------------------ |
|
|
776
|
-
| `
|
|
762
|
+
| `runId` | string | yes | Run id |
|
|
777
763
|
| `version` | string | yes | Target version label (`v1`, `v2`, …) |
|
|
778
764
|
|
|
779
765
|
### `ultraapp_start_container`
|
|
@@ -782,7 +768,7 @@ Start the container/process for the active version (no-op if already running).
|
|
|
782
768
|
|
|
783
769
|
| Parameter | Type | Required |
|
|
784
770
|
| --------- | ------ | -------- |
|
|
785
|
-
| `
|
|
771
|
+
| `runId` | string | yes |
|
|
786
772
|
|
|
787
773
|
### `ultraapp_stop_container`
|
|
788
774
|
|
|
@@ -790,7 +776,7 @@ Stop the container/process without deleting any state.
|
|
|
790
776
|
|
|
791
777
|
| Parameter | Type | Required |
|
|
792
778
|
| --------- | ------ | -------- |
|
|
793
|
-
| `
|
|
779
|
+
| `runId` | string | yes |
|
|
794
780
|
|
|
795
781
|
### `ultraapp_delete`
|
|
796
782
|
|
|
@@ -798,11 +784,11 @@ Stop + remove the run completely (sessions, container, on-disk state, router ent
|
|
|
798
784
|
|
|
799
785
|
| Parameter | Type | Required |
|
|
800
786
|
| --------- | ------ | -------- |
|
|
801
|
-
| `
|
|
787
|
+
| `runId` | string | yes |
|
|
802
788
|
|
|
803
789
|
---
|
|
804
790
|
|
|
805
|
-
## Workflow
|
|
791
|
+
## Workflow & Verification (8)
|
|
806
792
|
|
|
807
793
|
Full semantics in [`workflow.md`](./workflow.md) and
|
|
808
794
|
[`verification.md`](./verification.md).
|
|
@@ -844,8 +830,11 @@ same as a failure).
|
|
|
844
830
|
trust.
|
|
845
831
|
- `workflow_cancel({ runId })`.
|
|
846
832
|
- `workflow_steer({ runId, text })` — the text is **prepended** to the next agent
|
|
847
|
-
node's prompt.
|
|
848
|
-
- `workflow_approve({ runId, approved })` — answers a `human_gate` node.
|
|
833
|
+
node's prompt. Steers not yet consumed are delivered after a restart too.
|
|
834
|
+
- `workflow_approve({ runId, approved })` — answers a `human_gate` node. A run
|
|
835
|
+
parked before the server restarted is resumed with the answer attached, so it
|
|
836
|
+
needs no separate `workflow_resume`. Returns `{ answered: false }` when the run
|
|
837
|
+
is not parked at a gate.
|
|
849
838
|
|
|
850
839
|
### `verify_run`
|
|
851
840
|
|
|
@@ -18,7 +18,7 @@ Runs in background — poll with `ultraplan_status`.
|
|
|
18
18
|
### Usage
|
|
19
19
|
|
|
20
20
|
```typescript
|
|
21
|
-
const plan = manager.ultraplanStart('Add OAuth2 support with Google and GitHub providers', {
|
|
21
|
+
const plan = await manager.ultraplanStart('Add OAuth2 support with Google and GitHub providers', {
|
|
22
22
|
cwd: '/path/to/project',
|
|
23
23
|
model: 'opus', // default
|
|
24
24
|
timeout: 1800000, // 30 min default
|
|
@@ -48,20 +48,20 @@ if (status?.status === 'completed') {
|
|
|
48
48
|
| `cwd` | `process.cwd()` | Project directory to explore |
|
|
49
49
|
| `timeout` | 1,800,000 ms (30 min) | Maximum planning time |
|
|
50
50
|
|
|
51
|
-
Results
|
|
51
|
+
Results are stored as a durable run and remain queryable after a restart.
|
|
52
52
|
|
|
53
53
|
---
|
|
54
54
|
|
|
55
55
|
## Ultrareview
|
|
56
56
|
|
|
57
|
-
A
|
|
57
|
+
A set of specialized reviewer agents that review your codebase in parallel, each from a different angle. Built on the fan-out primitive (see `fanout_start` in [tools.md](./tools.md)).
|
|
58
58
|
|
|
59
59
|
### How It Works
|
|
60
60
|
|
|
61
|
-
1.
|
|
62
|
-
2. Each agent
|
|
63
|
-
3. Agents run in parallel
|
|
64
|
-
4.
|
|
61
|
+
1. Starts a fan-out of N reviewer agents (1-20, default 5)
|
|
62
|
+
2. Each agent reviews from a different angle in the project directory, read-only on every engine (`sandboxMode: 'read-only'`, and plan mode on Claude), so no reviewer can change the code it is reviewing
|
|
63
|
+
3. Agents run in parallel; one failing reviewer does not stop the others
|
|
64
|
+
4. A read-only synthesis pass merges all findings into one report
|
|
65
65
|
|
|
66
66
|
### Available Review Angles (20)
|
|
67
67
|
|
|
@@ -91,14 +91,14 @@ A fleet of specialized bug-hunting agents that review your codebase in parallel,
|
|
|
91
91
|
### Usage
|
|
92
92
|
|
|
93
93
|
```typescript
|
|
94
|
-
const review = manager.ultrareviewStart('/path/to/project', {
|
|
94
|
+
const review = await manager.ultrareviewStart('/path/to/project', {
|
|
95
95
|
agentCount: 10, // use 10 of the 20 angles
|
|
96
96
|
maxDurationMinutes: 15, // 15 min timeout per agent
|
|
97
97
|
model: 'sonnet', // model for all reviewers
|
|
98
98
|
focus: 'Find security and performance bugs',
|
|
99
99
|
});
|
|
100
100
|
|
|
101
|
-
console.log(`Review ID: ${review.id}
|
|
101
|
+
console.log(`Review ID: ${review.id}`);
|
|
102
102
|
|
|
103
103
|
// Poll for completion
|
|
104
104
|
const status = manager.ultrareviewStatus(review.id);
|
|
@@ -116,11 +116,12 @@ if (status?.status === 'completed') {
|
|
|
116
116
|
|
|
117
117
|
### Configuration
|
|
118
118
|
|
|
119
|
-
| Parameter | Default | Range | Description
|
|
120
|
-
| -------------------- | ------------------------- | ----- |
|
|
121
|
-
| `agentCount` | 5 | 1-20 | Number of reviewer agents
|
|
122
|
-
| `maxDurationMinutes` | 10 | 5-25 | Per-agent timeout
|
|
123
|
-
| `model` | session default | — | Model for all reviewers
|
|
124
|
-
| `focus` | bugs + security + quality | — | Review focus description
|
|
119
|
+
| Parameter | Default | Range | Description |
|
|
120
|
+
| -------------------- | ------------------------- | ----- | ------------------------------------------------------------------------------- |
|
|
121
|
+
| `agentCount` | 5 | 1-20 | Number of reviewer agents |
|
|
122
|
+
| `maxDurationMinutes` | 10 | 5-25 | Per-agent timeout |
|
|
123
|
+
| `model` | session default | — | Model for all reviewers |
|
|
124
|
+
| `focus` | bugs + security + quality | — | Review focus description |
|
|
125
|
+
| `engines` | `['claude']` | — | Engines assigned to reviewers round-robin. Not `grok`, which refuses a read-only session, or `custom` |
|
|
125
126
|
|
|
126
|
-
|
|
127
|
+
Reviewers run once each (up to 20 turns); there is no cross-review round. Results are stored as a durable run and remain queryable after a restart.
|