@enderfga/claw-orchestrator 7.14.0 → 7.15.0
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 +160 -135
- package/configs/autoloop-reviewer-prompt.md +1 -1
- package/configs/engines/README.md +31 -11
- package/dist/bin/acp-server.js +7 -12
- package/dist/bin/acp-server.js.map +1 -1
- package/dist/bin/cli.js +71 -40
- package/dist/bin/cli.js.map +1 -1
- package/dist/bin/mcp-server.js +2 -54
- package/dist/bin/mcp-server.js.map +1 -1
- package/dist/src/acp-server.d.ts +17 -9
- package/dist/src/acp-server.js +149 -30
- package/dist/src/acp-server.js.map +1 -1
- package/dist/src/autoloop/agent-tools.d.ts +2 -0
- package/dist/src/autoloop/agent-tools.js +7 -0
- package/dist/src/autoloop/agent-tools.js.map +1 -1
- package/dist/src/autoloop/dispatcher.d.ts +6 -0
- package/dist/src/autoloop/dispatcher.js +23 -1
- package/dist/src/autoloop/dispatcher.js.map +1 -1
- package/dist/src/autoloop/planner-tools.js +2 -0
- package/dist/src/autoloop/planner-tools.js.map +1 -1
- package/dist/src/council.d.ts +8 -0
- package/dist/src/council.js +45 -12
- package/dist/src/council.js.map +1 -1
- package/dist/src/dashboard/index.html +28 -14
- package/dist/src/embedded-server.js +27 -8
- package/dist/src/embedded-server.js.map +1 -1
- package/dist/src/engine-spawn.js +3 -1
- package/dist/src/engine-spawn.js.map +1 -1
- package/dist/src/fanout.d.ts +13 -3
- package/dist/src/fanout.js +10 -0
- package/dist/src/fanout.js.map +1 -1
- package/dist/src/inbox-manager.d.ts +9 -0
- package/dist/src/inbox-manager.js +8 -2
- package/dist/src/inbox-manager.js.map +1 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.js +117 -51
- package/dist/src/index.js.map +1 -1
- package/dist/src/kernel/conditions.d.ts +1 -1
- package/dist/src/kernel/conditions.js +1 -1
- package/dist/src/kernel/engine.d.ts +28 -8
- package/dist/src/kernel/engine.js +93 -19
- package/dist/src/kernel/engine.js.map +1 -1
- package/dist/src/kernel/nodes/agent.js +2 -0
- package/dist/src/kernel/nodes/agent.js.map +1 -1
- package/dist/src/kernel/nodes/council.js +9 -4
- package/dist/src/kernel/nodes/council.js.map +1 -1
- package/dist/src/kernel/nodes/fanout.js +5 -0
- package/dist/src/kernel/nodes/fanout.js.map +1 -1
- package/dist/src/kernel/nodes/goal.d.ts +8 -1
- package/dist/src/kernel/nodes/goal.js +40 -19
- package/dist/src/kernel/nodes/goal.js.map +1 -1
- package/dist/src/kernel/nodes/subflow.js +9 -1
- package/dist/src/kernel/nodes/subflow.js.map +1 -1
- package/dist/src/kernel/nodes/ultraapp.d.ts +1 -0
- package/dist/src/kernel/nodes/ultraapp.js +1 -0
- package/dist/src/kernel/nodes/ultraapp.js.map +1 -1
- package/dist/src/kernel/nodes/verifier.js +5 -1
- package/dist/src/kernel/nodes/verifier.js.map +1 -1
- package/dist/src/kernel/projections.d.ts +1 -0
- package/dist/src/kernel/projections.js +7 -1
- package/dist/src/kernel/projections.js.map +1 -1
- package/dist/src/kernel/templates/index.d.ts +6 -3
- package/dist/src/kernel/templates/index.js +8 -3
- package/dist/src/kernel/templates/index.js.map +1 -1
- package/dist/src/kernel/types.d.ts +30 -10
- package/dist/src/kernel/types.js.map +1 -1
- package/dist/src/logger.d.ts +6 -0
- package/dist/src/logger.js +14 -0
- package/dist/src/logger.js.map +1 -1
- package/dist/src/mcp-annotations.d.ts +13 -0
- package/dist/src/mcp-annotations.js +100 -0
- package/dist/src/mcp-annotations.js.map +1 -0
- package/dist/src/models.d.ts +7 -0
- package/dist/src/models.js +9 -0
- package/dist/src/models.js.map +1 -1
- package/dist/src/openai-compat.d.ts +11 -5
- package/dist/src/openai-compat.js +55 -54
- package/dist/src/openai-compat.js.map +1 -1
- package/dist/src/persistent-acp-session.d.ts +7 -0
- package/dist/src/persistent-acp-session.js +26 -2
- package/dist/src/persistent-acp-session.js.map +1 -1
- package/dist/src/persistent-codex-app-session.d.ts +2 -0
- package/dist/src/persistent-codex-app-session.js +18 -9
- package/dist/src/persistent-codex-app-session.js.map +1 -1
- package/dist/src/persistent-codex-session.d.ts +14 -3
- package/dist/src/persistent-codex-session.js +22 -19
- package/dist/src/persistent-codex-session.js.map +1 -1
- package/dist/src/persistent-custom-session.d.ts +9 -0
- package/dist/src/persistent-custom-session.js +41 -21
- package/dist/src/persistent-custom-session.js.map +1 -1
- package/dist/src/persistent-grok-session.js +1 -1
- package/dist/src/persistent-grok-session.js.map +1 -1
- package/dist/src/run-ledger.d.ts +3 -3
- package/dist/src/session-manager.d.ts +34 -1
- package/dist/src/session-manager.js +160 -30
- package/dist/src/session-manager.js.map +1 -1
- package/dist/src/types.d.ts +34 -11
- package/dist/src/types.js.map +1 -1
- package/dist/src/ultraapp/build.d.ts +5 -11
- package/dist/src/ultraapp/build.js +5 -11
- package/dist/src/ultraapp/build.js.map +1 -1
- package/dist/src/ultraapp/council-adapter.d.ts +5 -2
- package/dist/src/ultraapp/council-adapter.js +6 -6
- package/dist/src/ultraapp/council-adapter.js.map +1 -1
- package/dist/src/ultraapp/files.d.ts +7 -0
- package/dist/src/ultraapp/files.js +7 -1
- package/dist/src/ultraapp/files.js.map +1 -1
- package/dist/src/ultraapp/manager.d.ts +23 -3
- package/dist/src/ultraapp/manager.js +170 -72
- package/dist/src/ultraapp/manager.js.map +1 -1
- package/dist/src/ultraapp/narrator.js +1 -1
- package/dist/src/ultraapp/narrator.js.map +1 -1
- package/dist/src/ultraapp/versions.d.ts +27 -5
- package/dist/src/ultraapp/versions.js +58 -13
- package/dist/src/ultraapp/versions.js.map +1 -1
- package/openclaw.plugin.json +4 -13
- package/package.json +13 -6
- package/skills/SKILL.md +52 -24
- package/skills/references/acp.md +140 -61
- package/skills/references/autoloop.md +141 -35
- package/skills/references/claude-cli-tracking.md +8 -6
- package/skills/references/cli.md +122 -93
- package/skills/references/council.md +44 -22
- package/skills/references/dashboard.md +37 -21
- package/skills/references/getting-started.md +49 -15
- package/skills/references/inbox.md +13 -8
- package/skills/references/mcp.md +25 -17
- package/skills/references/multi-engine.md +161 -145
- package/skills/references/observability.md +90 -58
- package/skills/references/openai-compat.md +172 -82
- package/skills/references/sessions.md +101 -65
- package/skills/references/tools.md +209 -158
- package/skills/references/ultra.md +7 -7
- package/skills/references/ultraapp.md +101 -56
- package/skills/references/verification.md +112 -56
- package/skills/references/workflow.md +227 -93
- package/assets/banner.jpg +0 -0
|
@@ -6,75 +6,83 @@ All 78 tools are registered as OpenClaw plugin tools and exposed over MCP by `cl
|
|
|
6
6
|
|
|
7
7
|
### `session_start`
|
|
8
8
|
|
|
9
|
-
Start a persistent coding session with full CLI flag support.
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
31
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
9
|
+
Start a persistent coding session with full CLI flag support. Most rows below are Claude Code CLI
|
|
10
|
+
flags and are ignored by engines without an equivalent; a row that names other engines says where
|
|
11
|
+
else the value applies.
|
|
12
|
+
|
|
13
|
+
| Parameter | Type | Description |
|
|
14
|
+
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `name` | string | Session name (auto-generated if omitted) |
|
|
16
|
+
| `cwd` | string | Working directory |
|
|
17
|
+
| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'acp'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `grok` wraps xAI Grok Build and reports its own per-turn cost. `opencode` wraps sst/opencode (pass model as `provider/model`). `acp` drives any Agent Client Protocol agent named by `acpAgent`. Use `custom` with `customEngine` for any CLI. (`'gemini'` and `'cursor'` are still accepted for existing callers but are legacy — not version-tracked; use `agy` for Google and `grok` in place of Cursor.) |
|
|
18
|
+
| `model` | string | Model alias or full name |
|
|
19
|
+
| `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`). Defaults to the plugin's `defaultPermissionMode` (`acceptEdits`). On `acp`, `bypassPermissions`, `acceptEdits`, `auto` and `dontAsk` allow the agent's permission requests and the others reject them |
|
|
20
|
+
| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values (default `workspace-write`). `read-only` is also enforced on Claude → plan mode; Antigravity → its plan mode; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`; Grok → its OS-enforced `--sandbox read-only` profile (refused for a project under the temp directory, on platforms without Seatbelt or Landlock, and when grok cannot apply it). A `custom` engine must map it via `permissionModes`, or the session refuses to start. The `acp` engine refuses `read-only`, because the agent runs its own tools; its permission requests are answered from `permissionMode`. Persisted across session resume. |
|
|
21
|
+
| `allowedTools` | string[] | Tools to auto-approve |
|
|
22
|
+
| `disallowedTools` | string[] | Tools to deny |
|
|
23
|
+
| `tools` | string \| string[] | Claude only. The built-in tool set (`--tools`): names such as `["Bash", "Edit", "Read"]`, `""` for none, or `"default"`. Under `restricted`, the command-running tools and `WebFetch` it names are kept |
|
|
24
|
+
| `addDir` | string[] | Directories the session may use besides `cwd` (`--add-dir`). Claude and Codex; a resumed Codex thread keeps the directories its first turn opened |
|
|
25
|
+
| `maxTurns` | number | Max agent loop turns |
|
|
26
|
+
| `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. |
|
|
27
|
+
| `autoCompactPercent` | number | Compact the conversation before a send once `contextPercent` reaches this value (1–99). Off by default. For long-lived sessions, where cost grows with context size; survives a server restart. A failed compaction does not block the send. |
|
|
28
|
+
| `systemPrompt` | string | Replace system prompt |
|
|
29
|
+
| `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. ACP has no system-prompt channel: an `acp` session puts `systemPrompt` and `appendSystemPrompt` at the top of the first message of a new session |
|
|
30
|
+
| `agents` | object | Custom sub-agents JSON |
|
|
31
|
+
| `agent` | string | Default agent to use |
|
|
32
|
+
| `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
|
|
33
|
+
| `worktree` | string \| boolean | Run in git worktree |
|
|
34
|
+
| `fallbackModel` | string \| string[] | Fallback model(s) when the primary is overloaded; an array is tried in order |
|
|
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
|
+
| `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
|
+
| `mcpConfig` | string \| string[] | MCP server config file(s) |
|
|
38
|
+
| `settings` | string | Settings.json path or inline JSON |
|
|
39
|
+
| `pluginUrl` | string \| string[] | Claude only. Plugin `.zip` URL(s) fetched for this session only (`--plugin-url`) |
|
|
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
|
+
| `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 |
|
|
42
|
+
| `launcher` | string[] | Argv prefix every engine process of the session runs under, e.g. a sandbox wrapper: `["/opt/sandbox.sh", "task"]`. Any engine; it runs with your authority, like a contract command check. See [Multi-Engine: Running an engine under a launcher](./multi-engine.md#running-an-engine-under-a-launcher) |
|
|
43
|
+
| `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`. |
|
|
44
|
+
| `codexProfile` | string | Codex only. Named profile from `~/.codex/config.toml`, passed as `codex exec --profile` |
|
|
45
|
+
| `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. |
|
|
46
|
+
| `betas` | string \| string[] | Custom beta headers |
|
|
47
|
+
| `enableAgentTeams` | boolean | Enable experimental agent teams |
|
|
48
|
+
| `enableAutoMode` | boolean | Enable auto permission mode |
|
|
49
|
+
| `customEngine` | object \| string | Custom engine config (required when `engine='custom'`), or the id of a bundled preset (`clawo engines` lists them). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-engine-custom). |
|
|
50
|
+
| `acpAgent` | string \| object | The ACP agent (required when `engine='acp'`): a bundled preset id (`kimi-code`, `dsh`), or, from a local caller only, `{ name, command, commandEnv?, args?, env?, contextWindow?, pricing? }`. Fan-out, council and workflow agent specs take a preset id in the same field, and `session_handoff` takes either form. Autoloop and ultrareview refuse `acp`. See [Multi-Engine: ACP agents](./multi-engine.md#acp-agents-engine-acp). |
|
|
51
|
+
| `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 |
|
|
52
|
+
| `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
|
|
53
|
+
| `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 |
|
|
54
|
+
| `chrome` | boolean | Let the session use the user's Chrome through the Claude in Chrome extension, acting with that browser's sign-ins (Claude engine, `--chrome`). Off by default. Needs Chrome running with the extension and a claude.ai login; survives a server restart |
|
|
55
|
+
| `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. |
|
|
56
|
+
| `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
|
|
57
|
+
| `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
|
|
58
|
+
| `debug` | string \| string[] | Debug categories to enable (e.g. `"api,mcp"` or `["api", "mcp"]`) |
|
|
59
|
+
| `debugFile` | string | File path to write debug output to |
|
|
60
|
+
| `fromPr` | string | Resume a session linked to a GitHub PR number or URL |
|
|
61
|
+
| `channels` | string \| string[] | MCP channel subscription spec (research preview) |
|
|
62
|
+
| `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
|
|
63
|
+
| `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
|
|
64
|
+
| `enableToolSearch` | boolean | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`) |
|
|
65
|
+
| `otelLogUserPrompts` | boolean | OpenTelemetry: log user prompts (sets `OTEL_LOG_USER_PROMPTS=1`) |
|
|
66
|
+
| `otelLogRawApiBodies` | boolean | OpenTelemetry: log raw API request/response bodies (sets `OTEL_LOG_RAW_API_BODIES=1`); debug only |
|
|
67
|
+
| `bedrockServiceTier` | `'default'` \| `'flex'` \| `'priority'` | AWS Bedrock service tier (sets `ANTHROPIC_BEDROCK_SERVICE_TIER`); only effective when routing through Bedrock |
|
|
68
|
+
| `effort` | `'low'` \| `'medium'` \| `'high'` \| `'xhigh'` \| `'max'` \| `'ultra'` \| `'auto'` | Reasoning effort level. Engines do not share one ladder: Claude Code takes up to `max` (`--effort`; `ultra` is sent as `max`), Codex (`codex`, `codex-app`) adds `ultra`, Grok stops at `xhigh`, Antigravity at `high`, and OpenCode forwards the level to its provider unvalidated. A level above an engine's ceiling clamps rather than being dropped. `auto` leaves the level to the engine. `acp` does not pass it to the engine. |
|
|
63
69
|
|
|
64
70
|
### `session_send`
|
|
65
71
|
|
|
66
72
|
Send a message and get the response.
|
|
67
73
|
|
|
68
|
-
| Parameter | Type | Required | Description
|
|
69
|
-
| --------- | ------- | -------- |
|
|
70
|
-
| `name` | string | yes | Session name
|
|
71
|
-
| `message` | string | yes | Message to send
|
|
72
|
-
| `effort` | string | |
|
|
73
|
-
| `plan` | boolean | |
|
|
74
|
-
| `timeout` | number | | Timeout in ms (default 300000)
|
|
75
|
-
| `stream` | boolean | | Collect
|
|
76
|
-
|
|
77
|
-
Returns `{ ok, output, sessionId, error?, permissionDenials?, images? }`. `
|
|
74
|
+
| Parameter | Type | Required | Description |
|
|
75
|
+
| --------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| `name` | string | yes | Session name |
|
|
77
|
+
| `message` | string | yes | Message to send |
|
|
78
|
+
| `effort` | string | | Effort for this message: `low` … `ultra` (no `auto`). Antigravity, Grok, OpenCode and `codex-app` pass it to the engine for this turn; on Claude, `high` and above prefix the message with `ultrathink` (a persistent custom engine does the same for `high` and `max`). Other engines ignore it |
|
|
79
|
+
| `plan` | boolean | | Ask for a plan only. Claude and persistent custom engines prefix the message with a plan-only instruction; the permission mode is unchanged, and other engines ignore it. To enforce read-only, start the session with `sandboxMode: 'read-only'` |
|
|
80
|
+
| `timeout` | number | | Timeout in ms (default 300000) |
|
|
81
|
+
| `stream` | boolean | | Collect the text chunks into `chunks[]` on the result (returned with the final result, not streamed to the caller) |
|
|
82
|
+
|
|
83
|
+
Returns `{ ok, output, sessionId, error?, usage, permissionDenials?, images?, chunks? }`. `usage` is
|
|
84
|
+
`{ tokensIn, tokensOut, costUsd }` for this turn alone — what it added to the session's running totals, which
|
|
85
|
+
`coding_session_status` reports. `permissionDenials` lists the tool
|
|
78
86
|
calls the engine refused during the turn — `[{ toolName, toolUseId?, input? }]` — and is present only
|
|
79
87
|
when there was at least one. Check it even when `error` is absent: a turn whose tool calls were all
|
|
80
88
|
denied still ends as a success. See [sessions.md](./sessions.md) on what "succeeded" does and does
|
|
@@ -88,15 +96,16 @@ Continue a session's conversation on another engine — or the same engine with
|
|
|
88
96
|
a new session in the source's working directory and carries the conversation into it; the source
|
|
89
97
|
keeps running untouched.
|
|
90
98
|
|
|
91
|
-
| Parameter | Type
|
|
92
|
-
| -------------- |
|
|
93
|
-
| `name` | string
|
|
94
|
-
| `engine` | string
|
|
95
|
-
| `model` | string
|
|
96
|
-
| `newName` | string
|
|
97
|
-
| `message` | string
|
|
98
|
-
| `maxChars` | number
|
|
99
|
-
| `
|
|
99
|
+
| Parameter | Type | Required | Description |
|
|
100
|
+
| -------------- | ---------------- | -------- | ---------------------------------------------------------------------------------- |
|
|
101
|
+
| `name` | string | yes | The session to hand off from |
|
|
102
|
+
| `engine` | string | yes | Engine for the new session. May be the same engine with a different model |
|
|
103
|
+
| `model` | string | | Model for the new session (default: the engine's default) |
|
|
104
|
+
| `newName` | string | | Name for the new session (default `<name>-<engine>`) |
|
|
105
|
+
| `message` | string | | Send this now and return the reply; otherwise the history waits for `session_send` |
|
|
106
|
+
| `maxChars` | number | | Cap on the carried history, in characters (default 240000, minimum 4000) |
|
|
107
|
+
| `acpAgent` | string \| object | | With `engine: 'acp'`: the agent to start, as in `session_start` |
|
|
108
|
+
| `customEngine` | object \| string | | As in `session_start`, when `engine` is `custom` |
|
|
100
109
|
|
|
101
110
|
Returns `{ ok, name, engine, from: { name, engine }, carried: { turns, omitted, chars }, result? }`.
|
|
102
111
|
`result` is the send result of `message`, when one was given. See [sessions.md](./sessions.md) for
|
|
@@ -104,7 +113,9 @@ what carries across, what does not, and what is kept when the conversation is to
|
|
|
104
113
|
|
|
105
114
|
### `session_stop`
|
|
106
115
|
|
|
107
|
-
Graceful shutdown (SIGTERM, then SIGKILL after 3s).
|
|
116
|
+
Graceful shutdown (SIGTERM, then SIGKILL after 3s). The session is also removed from the resume
|
|
117
|
+
registry and its inbox is cleared, so a later `session_start` under the same name begins a new
|
|
118
|
+
conversation with no messages left over from the old one.
|
|
108
119
|
|
|
109
120
|
| Parameter | Type | Required |
|
|
110
121
|
| --------- | ------ | -------- |
|
|
@@ -124,7 +135,7 @@ Dashboard view: all sessions with ready/busy/paused state, cost, context %, last
|
|
|
124
135
|
|
|
125
136
|
### `coding_session_status`
|
|
126
137
|
|
|
127
|
-
Detailed status: tokens, cost, context %, tool calls,
|
|
138
|
+
Detailed status: the `session_list` entry (`costUsd`, `budgetUsd`, `budgetExhausted`, …) plus the engine's `stats` — turns, tokens, cost, context %, tool calls, start time, last activity. (Prefixed to avoid clashing with OpenClaw's built-in `session_status`.)
|
|
128
139
|
|
|
129
140
|
| Parameter | Type | Required |
|
|
130
141
|
| --------- | ------ | -------- |
|
|
@@ -132,14 +143,15 @@ Detailed status: tokens, cost, context %, tool calls, uptime. (Prefixed to avoid
|
|
|
132
143
|
|
|
133
144
|
**Returned stats fields** (selected):
|
|
134
145
|
|
|
135
|
-
| Field | Type | Description
|
|
136
|
-
| ---------------- | ------------------- |
|
|
137
|
-
| `retries` | number |
|
|
138
|
-
| `lastRetryError` | string \| undefined |
|
|
146
|
+
| Field | Type | Description |
|
|
147
|
+
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
148
|
+
| `retries` | number | API retries during this session, from Claude Code's `system/api_retry` events (always 0 on other engines) |
|
|
149
|
+
| `lastRetryError` | string \| undefined | Category of the most recent retry (e.g. `overloaded`, `rate_limit`), or its HTTP status when no category was given |
|
|
139
150
|
|
|
140
151
|
### `session_grep`
|
|
141
152
|
|
|
142
|
-
|
|
153
|
+
Case-insensitive regex search over the session's in-memory event history, which keeps the 100 most
|
|
154
|
+
recent events.
|
|
143
155
|
|
|
144
156
|
| Parameter | Type | Required | Description |
|
|
145
157
|
| --------- | ------ | -------- | ------------------------ |
|
|
@@ -158,19 +170,20 @@ Reclaim context window via `/compact`.
|
|
|
158
170
|
|
|
159
171
|
### `session_update_tools`
|
|
160
172
|
|
|
161
|
-
Update tool permissions at runtime. Restarts session with `--resume
|
|
173
|
+
Update tool permissions at runtime. Restarts session with `--resume`; refused while a turn is in
|
|
174
|
+
flight.
|
|
162
175
|
|
|
163
|
-
| Parameter | Type | Description
|
|
164
|
-
| ----------------- | -------- |
|
|
165
|
-
| `name` | string | Session name
|
|
166
|
-
| `allowedTools` | string[] | New allowed tools (replaces or merges)
|
|
167
|
-
| `disallowedTools` | string[] | New disallowed tools
|
|
168
|
-
| `removeTools` | string[] | Tools to remove from lists
|
|
169
|
-
| `merge` | boolean | Merge with existing (default: replace) |
|
|
176
|
+
| Parameter | Type | Description |
|
|
177
|
+
| ----------------- | -------- | ---------------------------------------------------------------------------------- |
|
|
178
|
+
| `name` | string | Session name |
|
|
179
|
+
| `allowedTools` | string[] | New allowed tools (replaces or merges) |
|
|
180
|
+
| `disallowedTools` | string[] | New disallowed tools |
|
|
181
|
+
| `removeTools` | string[] | Tools to remove from lists |
|
|
182
|
+
| `merge` | boolean | Merge with existing (default: replace — both lists, so a list you omit is cleared) |
|
|
170
183
|
|
|
171
184
|
### `session_switch_model`
|
|
172
185
|
|
|
173
|
-
Hot-swap model mid-conversation. Restarts with `--resume
|
|
186
|
+
Hot-swap model mid-conversation. Restarts with `--resume`; refused while a turn is in flight.
|
|
174
187
|
|
|
175
188
|
| Parameter | Type | Required |
|
|
176
189
|
| --------- | ------ | -------- |
|
|
@@ -260,7 +273,7 @@ Returns `{ ok, agents }`.
|
|
|
260
273
|
|
|
261
274
|
## Codex (13)
|
|
262
275
|
|
|
263
|
-
Tools targeting OpenAI's `codex` CLI. The `codex_resume` and `codex_review` tools are one-shot wrappers and work without a managed session. The `codex_goal_*` tools require a session started with `engine: "codex-app"` (see [multi-engine.md](./multi-engine.md)) —
|
|
276
|
+
Tools targeting OpenAI's `codex` CLI. The `codex_resume` and `codex_review` tools are one-shot wrappers and work without a managed session. The `codex_goal_*` tools require a session started with `engine: "codex-app"` (see [multi-engine.md](./multi-engine.md#openai-codex-app-server-engine-codex-app)) — `engine: "codex"` runs `codex exec` once per send and has no goal surface.
|
|
264
277
|
|
|
265
278
|
### `codex_resume`
|
|
266
279
|
|
|
@@ -281,7 +294,9 @@ Returns `{ ok, text, threadId?, usage?, events }`.
|
|
|
281
294
|
|
|
282
295
|
### `codex_review`
|
|
283
296
|
|
|
284
|
-
Run a non-interactive Codex code review (`codex review`). Pick
|
|
297
|
+
Run a non-interactive Codex code review (`codex review`). Pick at most one diff scope
|
|
298
|
+
(`uncommitted`, `base` or `commit`); passing two is an error. `base` and `commit` must be plain git
|
|
299
|
+
refs.
|
|
285
300
|
|
|
286
301
|
| Parameter | Type | Description |
|
|
287
302
|
| ------------- | ------- | ---------------------------------------------- |
|
|
@@ -355,22 +370,22 @@ Run one task across N engine/model agents **in parallel** and collect their answ
|
|
|
355
370
|
|
|
356
371
|
### `fanout_start`
|
|
357
372
|
|
|
358
|
-
| Parameter | Type | Required | Description
|
|
359
|
-
| ------------------------------------ | ------- | -------- |
|
|
360
|
-
| `task` | string | yes | Shared task sent to every agent, optionally after its `persona`.
|
|
361
|
-
| `projectDir` | string | yes | Working directory all agents run in.
|
|
362
|
-
| `agents` | array | yes |
|
|
363
|
-
| `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2).
|
|
364
|
-
| `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`).
|
|
365
|
-
| `
|
|
366
|
-
| `
|
|
367
|
-
| `
|
|
373
|
+
| Parameter | Type | Required | Description |
|
|
374
|
+
| ------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
375
|
+
| `task` | string | yes | Shared task sent to every agent, optionally after its `persona`. |
|
|
376
|
+
| `projectDir` | string | yes | Working directory all agents run in. |
|
|
377
|
+
| `agents` | array | yes | Up to 16 specs: `{ name, engine?, model?, effort?, prompt?, persona?, baseUrl?, permissionMode?, customEngine?, acpAgent? }`. Names must be unique (each forms a session name); `permissionMode` defaults to `bypassPermissions`. |
|
|
378
|
+
| `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2). |
|
|
379
|
+
| `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`). |
|
|
380
|
+
| `synthesisAcpAgent` | string | | With `synthesisEngine: 'acp'`: the ACP agent preset the synthesis pass starts. |
|
|
381
|
+
| `agentTimeoutMs` | number | | Per-agent timeout (default 600000). |
|
|
382
|
+
| `maxTurnsPerAgent` | number | | Max agent loop turns (default 30). |
|
|
383
|
+
| `maxBudgetUsd` | number | | Per-agent spend cap. |
|
|
368
384
|
|
|
369
385
|
Runs in the background; returns `{ ok, id, status, ... }`. Poll with `fanout_status`.
|
|
370
386
|
Each agent's optional `effort` accepts `low`, `medium`, `high`, `xhigh`, `max`,
|
|
371
|
-
`ultra`, or `auto`. Omit it to keep the session default. The
|
|
372
|
-
|
|
373
|
-
that do not map effort retain their existing behavior.
|
|
387
|
+
`ultra`, or `auto`. Omit it to keep the session default. The engine applies or
|
|
388
|
+
clamps the value as documented for `session_start`.
|
|
374
389
|
|
|
375
390
|
Per-agent `persona` provides role instructions without replacing the shared
|
|
376
391
|
task. Fan-out sends `<persona>\n\n## Shared task\n\n<task>`. A non-empty
|
|
@@ -381,16 +396,23 @@ resume/recovery repeats the same message construction.
|
|
|
381
396
|
|
|
382
397
|
### `fanout_status`
|
|
383
398
|
|
|
384
|
-
Poll a fan-out by `id`. Returns `{ ok, id, status, results: [{ agent, engine, model, ok, output, error?, durationMs }], synthesis? }`.
|
|
399
|
+
Poll a fan-out by `id`. Returns `{ ok, id, status, results: [{ agent, engine, model, ok, output, error?, durationMs }], synthesis?, synthesisError?, error? }`.
|
|
400
|
+
`status` is `running`, `done`, `error` or `aborted`. `synthesisError` is set when synthesis was requested
|
|
401
|
+
and failed; without it, a missing `synthesis` means none was requested or fewer than two agents succeeded.
|
|
385
402
|
|
|
386
403
|
### `fanout_abort`
|
|
387
404
|
|
|
388
|
-
Abort a running fan-out by `id
|
|
405
|
+
Abort a running fan-out by `id`. Agents already running finish, agents still waiting for a session
|
|
406
|
+
slot never start, and synthesis is skipped.
|
|
389
407
|
|
|
390
408
|
---
|
|
391
409
|
|
|
392
410
|
## Agent Teams (3)
|
|
393
411
|
|
|
412
|
+
`team_list` and `team_send` work on every engine and do not need `enableAgentTeams`: a session's
|
|
413
|
+
"team" is every other active session in this orchestrator. See
|
|
414
|
+
[Multi-Engine: Team Tools Across Engines](./multi-engine.md#team-tools-across-engines).
|
|
415
|
+
|
|
394
416
|
### `coding_agents_list`
|
|
395
417
|
|
|
396
418
|
List agent definitions from `.claude/agents/` (project + global). (Prefixed to avoid clashing with OpenClaw's built-in `agents_list`.)
|
|
@@ -401,7 +423,8 @@ List agent definitions from `.claude/agents/` (project + global). (Prefixed to a
|
|
|
401
423
|
|
|
402
424
|
### `team_list`
|
|
403
425
|
|
|
404
|
-
List
|
|
426
|
+
List the other active sessions, each with its engine, idle/busy/paused state and turn count. Returns
|
|
427
|
+
`{ ok, response }`, where `response` is that list as text.
|
|
405
428
|
|
|
406
429
|
| Parameter | Type | Required |
|
|
407
430
|
| --------- | ------ | -------- |
|
|
@@ -409,7 +432,8 @@ List teammates in an agent team session.
|
|
|
409
432
|
|
|
410
433
|
### `team_send`
|
|
411
434
|
|
|
412
|
-
Send message to
|
|
435
|
+
Send a message to another active session through the cross-session inbox: delivered now if the
|
|
436
|
+
teammate is idle, queued if it is busy.
|
|
413
437
|
|
|
414
438
|
| Parameter | Type | Required |
|
|
415
439
|
| ---------- | ------ | -------- |
|
|
@@ -425,16 +449,16 @@ Send message to a specific teammate.
|
|
|
425
449
|
|
|
426
450
|
Start a multi-agent council. Runs in background, returns session ID immediately.
|
|
427
451
|
|
|
428
|
-
| Parameter | Type | Required | Description
|
|
429
|
-
| ----------------------- | -------------- | -------- |
|
|
430
|
-
| `task` | string | yes | Task description
|
|
431
|
-
| `projectDir` | string | yes | Working directory
|
|
432
|
-
| `agents` | AgentPersona[] | |
|
|
433
|
-
| `maxRounds` | number | | Max rounds (default 15)
|
|
434
|
-
| `agentTimeoutMs` | number | | Per-agent timeout (default 1800000)
|
|
435
|
-
| `maxTurnsPerAgent` | number | | Max tool turns per agent (default
|
|
436
|
-
| `maxBudgetUsd` | number | | Max API spend per agent
|
|
437
|
-
| `defaultPermissionMode` | string | | Default permission mode for agents (`acceptEdits`, `bypassPermissions`, etc.). Overridden by agent-level `permissionMode`. Default: `bypassPermissions`
|
|
452
|
+
| Parameter | Type | Required | Description |
|
|
453
|
+
| ----------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
454
|
+
| `task` | string | yes | Task description |
|
|
455
|
+
| `projectDir` | string | yes | Working directory |
|
|
456
|
+
| `agents` | AgentPersona[] | | `{ name, emoji, persona, engine?, model?, effort?, ultracode?, baseUrl?, permissionMode?, customEngine?, acpAgent? }`. Defaults to a Planner / Generator / Evaluator team |
|
|
457
|
+
| `maxRounds` | number | | Max rounds (default 15) |
|
|
458
|
+
| `agentTimeoutMs` | number | | Per-agent timeout (default 1800000) |
|
|
459
|
+
| `maxTurnsPerAgent` | number | | Max tool turns per agent per round (default 50) |
|
|
460
|
+
| `maxBudgetUsd` | number | | Max API spend per agent |
|
|
461
|
+
| `defaultPermissionMode` | string | | Default permission mode for agents (`acceptEdits`, `bypassPermissions`, etc.). Overridden by agent-level `permissionMode`. Default: `bypassPermissions` |
|
|
438
462
|
|
|
439
463
|
### `council_status`
|
|
440
464
|
|
|
@@ -446,15 +470,20 @@ Get status of a running or recently completed council.
|
|
|
446
470
|
|
|
447
471
|
### `council_abort`
|
|
448
472
|
|
|
449
|
-
Abort a running
|
|
473
|
+
Abort a council running in this process, stopping all agent sessions and removing the worktrees it created.
|
|
450
474
|
|
|
451
475
|
| Parameter | Type | Required |
|
|
452
476
|
| --------- | ------ | -------- |
|
|
453
477
|
| `id` | string | yes |
|
|
454
478
|
|
|
479
|
+
**Returns**: `{ ok: true, aborted: true }`. A council that is not running in this process — finished, or
|
|
480
|
+
running in another one — is left alone: `{ ok: false, aborted: false, state, error }`, with the run's state.
|
|
481
|
+
|
|
455
482
|
### `council_inject`
|
|
456
483
|
|
|
457
|
-
Inject a user message into the next round of a running council
|
|
484
|
+
Inject a user message into the next round of a running council; it is appended to every agent's
|
|
485
|
+
prompt for that round. A second inject before the round starts replaces the first. The council
|
|
486
|
+
must be running in this process.
|
|
458
487
|
|
|
459
488
|
| Parameter | Type | Required |
|
|
460
489
|
| --------- | ------ | -------- |
|
|
@@ -473,7 +502,7 @@ Review a completed council session. Returns a structured report of all changed f
|
|
|
473
502
|
|
|
474
503
|
### `council_accept`
|
|
475
504
|
|
|
476
|
-
Accept and finalize council work. Cleans up all council scaffolding: removes worktrees, deletes `council/*` branches, removes `plan.md` and `reviews/` directory.
|
|
505
|
+
Accept and finalize council work. Cleans up all council scaffolding: removes worktrees, deletes `council/*` branches, removes `plan.md` and `reviews/` directory. The status `accepted` is recorded on the run, so `council_status` reports it, after a restart too.
|
|
477
506
|
|
|
478
507
|
| Parameter | Type | Required |
|
|
479
508
|
| --------- | ------ | -------- |
|
|
@@ -483,7 +512,7 @@ Accept and finalize council work. Cleans up all council scaffolding: removes wor
|
|
|
483
512
|
|
|
484
513
|
### `council_reject`
|
|
485
514
|
|
|
486
|
-
Reject council work and provide feedback. Rewrites `plan.md` with rejection feedback and commits it. Does NOT delete any worktrees or branches — the council can be restarted to retry.
|
|
515
|
+
Reject council work and provide feedback. Rewrites `plan.md` with rejection feedback and commits it. Does NOT delete any worktrees or branches — the council can be restarted to retry. The status `rejected` is recorded on the run, as for `council_accept`.
|
|
487
516
|
|
|
488
517
|
| Parameter | Type | Required | Description |
|
|
489
518
|
| ---------- | ------ | -------- | ------------------------------------------- |
|
|
@@ -605,9 +634,10 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
|
|
|
605
634
|
> **Custom engines are local-only.** A `CustomEngineConfig` names an executable to
|
|
606
635
|
> spawn plus its argv and env, so it may only be supplied by a caller that already
|
|
607
636
|
> runs on the host (this MCP tool, or the `SessionManager` API). **Every** HTTP
|
|
608
|
-
> request body is checked, on every route, and one carrying
|
|
609
|
-
>
|
|
610
|
-
> is rejected with a 400 naming the offending key path.
|
|
637
|
+
> request body is checked, on every route, and one carrying an inline engine
|
|
638
|
+
> config at any depth — `customEngine`, `*_custom_engine`, `agentCustomEngines`,
|
|
639
|
+
> `acpAgent` — is rejected with a 400 naming the offending key path. A bundled
|
|
640
|
+
> preset id (a string) is accepted, since it cannot name a binary of its own. The embedded server is
|
|
611
641
|
> often reverse-tunnelled and its token is a monitoring credential, not
|
|
612
642
|
> permission to choose what binary runs. Built-in engines stay fully selectable
|
|
613
643
|
> over HTTP.
|
|
@@ -670,7 +700,8 @@ history.
|
|
|
670
700
|
|
|
671
701
|
### `autoloop_status`
|
|
672
702
|
|
|
673
|
-
Get the current state
|
|
703
|
+
Get the current state: `status`, `iter`, `push_log_count`, `subagents_spawned`, `status_reason`,
|
|
704
|
+
`pending_dispatch`, `unconfirmed_chat` and the recent phase errors and metrics. Returns `{ ok, state }`.
|
|
674
705
|
|
|
675
706
|
| Parameter | Type | Required |
|
|
676
707
|
| --------- | ------ | -------- |
|
|
@@ -678,7 +709,7 @@ Get the current state and push log.
|
|
|
678
709
|
|
|
679
710
|
### `autoloop_list`
|
|
680
711
|
|
|
681
|
-
List
|
|
712
|
+
List the Autoloop runs recorded on this machine, running and finished, newest first.
|
|
682
713
|
|
|
683
714
|
(no params)
|
|
684
715
|
|
|
@@ -708,9 +739,14 @@ Terminate the run and stop all role sessions.
|
|
|
708
739
|
|
|
709
740
|
Forge tab — turn a structured Q&A interview into a deployed web app reachable at `localhost:19000/forge/<slug>/`. See [`ultraapp.md`](./ultraapp.md) for the operator reference (lifecycle, conventions §1–§7, runtime modes, file layout, HTTP routes).
|
|
710
741
|
|
|
742
|
+
Deploying needs the Forge router, which `clawo serve` starts. Without it a build stops at
|
|
743
|
+
`build-complete`, and `ultraapp_promote_version`, `ultraapp_start_container` and
|
|
744
|
+
`ultraapp_stop_container` return `{ ok: false, error: 'router not configured' }`.
|
|
745
|
+
|
|
711
746
|
### `ultraapp_list`
|
|
712
747
|
|
|
713
|
-
List all ultraapp runs.
|
|
748
|
+
List all ultraapp runs with title, mode and timestamps. Modes: `interview`, `queued`, `building`,
|
|
749
|
+
`build-complete`, `deploying`, `done`, `failed`, `cancelled`. Start a new run with `ultraapp_new`.
|
|
714
750
|
|
|
715
751
|
(no params)
|
|
716
752
|
|
|
@@ -724,7 +760,7 @@ Full snapshot of a run: spec + chat + state.
|
|
|
724
760
|
|
|
725
761
|
### `ultraapp_status`
|
|
726
762
|
|
|
727
|
-
Lightweight status
|
|
763
|
+
Lightweight status: mode, timestamps, and the failure reason if any.
|
|
728
764
|
|
|
729
765
|
| Parameter | Type | Required |
|
|
730
766
|
| --------- | ------ | -------- |
|
|
@@ -782,7 +818,7 @@ Abort an active build. Council sessions are stopped and the worktrees are left a
|
|
|
782
818
|
|
|
783
819
|
### `ultraapp_feedback`
|
|
784
820
|
|
|
785
|
-
Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spec-delta` (focused interview + auto-rerun), or `structural` (suggest fresh run).
|
|
821
|
+
Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spec-delta` (focused interview + auto-rerun), or `structural` (suggest fresh run). Before the run reaches `done`, the text goes to the interview as a free-form answer instead.
|
|
786
822
|
|
|
787
823
|
| Parameter | Type | Required | Description |
|
|
788
824
|
| --------- | ------ | -------- | ----------------------- |
|
|
@@ -791,7 +827,7 @@ Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spe
|
|
|
791
827
|
|
|
792
828
|
### `ultraapp_promote_version`
|
|
793
829
|
|
|
794
|
-
|
|
830
|
+
Make a version the one serving the app. A version deployed before is swapped in: the live container/process is stopped, the target's is started, and the router map is updated; if the target does not start, the previous version is put back. A version never deployed (a patched one, typically) is built and deployed first, which replaces the live version.
|
|
795
831
|
|
|
796
832
|
| Parameter | Type | Required | Description |
|
|
797
833
|
| --------- | ------ | -------- | ------------------------------------ |
|
|
@@ -834,39 +870,52 @@ Full semantics in [`workflow.md`](./workflow.md) and
|
|
|
834
870
|
Start a durable run. Every state transition is checkpointed to disk, so a run
|
|
835
871
|
survives a process restart and can be resumed.
|
|
836
872
|
|
|
837
|
-
| Param | Type
|
|
838
|
-
| ------------- |
|
|
839
|
-
| `spec` | object
|
|
840
|
-
| `template` | `solve` \| `council` \| `fanout` | Build a built-in instead of supplying `spec`
|
|
841
|
-
| `task` | string
|
|
842
|
-
| `agents` | array
|
|
843
|
-
| `reviewers` | array
|
|
844
|
-
| `implementer` | object
|
|
845
|
-
| `humanGate` | boolean
|
|
846
|
-
| `
|
|
847
|
-
| `
|
|
848
|
-
| `
|
|
849
|
-
| `
|
|
850
|
-
|
|
851
|
-
|
|
873
|
+
| Param | Type | Notes |
|
|
874
|
+
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
|
|
875
|
+
| `spec` | object | `WorkflowSpec`: `{ name, nodes[], cwd?, contract?, maxNodeVisits? }` |
|
|
876
|
+
| `template` | `solve` \| `council` \| `fanout` \| `goal` | Build a built-in instead of supplying `spec` (default `solve` when `spec` is omitted) |
|
|
877
|
+
| `task` | string | Required with `template`; for `goal` it is the objective |
|
|
878
|
+
| `agents` | array | Up to 16 `{ name, engine?, model?, effort?, persona? }` (default one agent named `agent`); not used by `goal` |
|
|
879
|
+
| `reviewers` | array | `solve` only — up to 8, same agent binding, for final reviewers |
|
|
880
|
+
| `implementer` | object | `solve` only — `{ engine?, model?, acpAgent? }` for the agent that writes the change |
|
|
881
|
+
| `humanGate` | boolean | `solve` only — park for approval before anything is written |
|
|
882
|
+
| `maxRounds` | number | `council` only — max collaboration rounds, default 15 |
|
|
883
|
+
| `maxRepairs` | number | `solve` / `goal` — repair attempts, default 3 for `solve`, 1 for `goal` |
|
|
884
|
+
| `model` | string | `goal` only — Codex model (default: Codex's own) |
|
|
885
|
+
| `tokenBudget` | number | `goal` only — tokens the goal may spend |
|
|
886
|
+
| `launcher` | string[] | `goal` only — argv prefix Codex runs under (e.g. a sandbox wrapper); it runs with your authority |
|
|
887
|
+
| `cwd` | string | Working directory |
|
|
888
|
+
| `runId` | string | Explicit id |
|
|
889
|
+
| `contract` | object | Acceptance contract — see below |
|
|
890
|
+
|
|
891
|
+
Returns `{ runId, workflow, state, nodes }` and runs in the background. The `goal` template runs a
|
|
892
|
+
Codex `/goal` on one `codex-app` thread, then the contract, then repairs on the same thread; see
|
|
893
|
+
[workflow.md](./workflow.md#goal).
|
|
852
894
|
|
|
853
895
|
### `workflow_status`
|
|
854
896
|
|
|
855
|
-
`{ runId, events? }` → run state, per-node status, `outcome`, `
|
|
856
|
-
`costUsd`, `consensusVotes`, and the last N events when
|
|
897
|
+
`{ runId, events? }` → run state, per-node status, `outcome`, `outcomeReason`,
|
|
898
|
+
`verdict`, `evidenceId`, `costUsd`, `consensusVotes`, and the last N events when
|
|
899
|
+
`events` is given.
|
|
857
900
|
|
|
858
901
|
`outcome` is `verified` (a contract passed), `refuted` (it failed), or
|
|
859
|
-
`unverified` (**
|
|
860
|
-
|
|
902
|
+
`unverified` (**nothing checked the work**, which is not the same as a failure):
|
|
903
|
+
either no contract was declared, or a pass no longer stands because the tree
|
|
904
|
+
changed after it or an abandoned attempt was still running, in which case
|
|
905
|
+
`outcomeReason` says why. `verdict` is the most recent verifier result: its node,
|
|
906
|
+
`evidenceId` and the tree digest it was taken at.
|
|
861
907
|
|
|
862
908
|
### `workflow_list` / `workflow_resume` / `workflow_cancel` / `workflow_steer` / `workflow_approve`
|
|
863
909
|
|
|
864
|
-
- `workflow_list({ workflow?, state?, limit? })` — newest first, survives
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
-
|
|
869
|
-
|
|
910
|
+
- `workflow_list({ workflow?, state?, limit? })` — newest first (`limit` default 25), survives
|
|
911
|
+
restarts. `state` is one of `pending`, `running`, `awaiting_human`, `verifying`, `completed`,
|
|
912
|
+
`failed`, `cancelled`.
|
|
913
|
+
- `workflow_resume({ runId, agentCustomEngineRefs? })` — nodes already succeeded are not re-run;
|
|
914
|
+
the node that was in flight is retried, because a half-finished node left no result to trust.
|
|
915
|
+
A run whose agents used a custom engine needs `agentCustomEngineRefs`
|
|
916
|
+
(`{ "<agent>": "<REF>" }`, resolved from `CLAWO_CUSTOM_ENGINE_<REF>` on the orchestrator's host).
|
|
917
|
+
- `workflow_cancel({ runId })` → `{ cancelled }`.
|
|
918
|
+
- `workflow_steer({ runId, text })` → `{ steered }` — the text is **prepended** to the next agent
|
|
870
919
|
node's prompt. Steers not yet consumed are delivered after a restart too.
|
|
871
920
|
- `workflow_approve({ runId, approved })` — answers a `human_gate` node. A run
|
|
872
921
|
parked before the server restarted is resumed with the answer attached, so it
|
|
@@ -877,10 +926,12 @@ same as a failure).
|
|
|
877
926
|
|
|
878
927
|
Run an acceptance contract against a directory outside any workflow — for a plain
|
|
879
928
|
`session_send` that edited a repo, say. `{ cwd, contract, baseSha?, label? }` →
|
|
880
|
-
the evidence bundle
|
|
929
|
+
the evidence bundle, stored under `~/.claw-orchestrator/wf/<label>/evidence/`. A
|
|
930
|
+
`label` that is the id of an existing workflow run is refused.
|
|
881
931
|
|
|
882
932
|
Without `baseSha`, `diff_policy` sees untracked files only. `verify_run` has no record of
|
|
883
|
-
the tree before the work, so `protectTests` does not apply to it.
|
|
933
|
+
the tree before the work, so `protectTests` does not apply to it. It runs the checks once and
|
|
934
|
+
spawns no repair session, so `fixOnFailureRounds` does not apply either.
|
|
884
935
|
|
|
885
936
|
### The `contract` parameter
|
|
886
937
|
|