@enderfga/claw-orchestrator 7.13.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 +163 -137
- package/configs/autoloop-reviewer-prompt.md +1 -1
- package/configs/engines/README.md +45 -5
- package/configs/engines/dsh.json +17 -0
- package/configs/engines/kimi-code.json +17 -0
- package/dist/bin/acp-server.js +7 -12
- package/dist/bin/acp-server.js.map +1 -1
- package/dist/bin/cli.js +127 -67
- 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 +151 -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 +34 -10
- package/dist/src/embedded-server.js.map +1 -1
- package/dist/src/engine-presets.d.ts +7 -3
- package/dist/src/engine-presets.js +39 -6
- package/dist/src/engine-presets.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 +136 -52
- 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 +83 -0
- package/dist/src/persistent-acp-session.js +433 -0
- package/dist/src/persistent-acp-session.js.map +1 -0
- 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 +169 -30
- package/dist/src/session-manager.js.map +1 -1
- package/dist/src/types.d.ts +63 -12
- package/dist/src/types.js +2 -0
- 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 -57
- package/skills/references/autoloop.md +141 -35
- package/skills/references/claude-cli-tracking.md +9 -6
- package/skills/references/cli.md +129 -91
- 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 +180 -144
- 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 -157
- 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,74 +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
|
-
| `
|
|
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. |
|
|
62
69
|
|
|
63
70
|
### `session_send`
|
|
64
71
|
|
|
65
72
|
Send a message and get the response.
|
|
66
73
|
|
|
67
|
-
| Parameter | Type | Required | Description
|
|
68
|
-
| --------- | ------- | -------- |
|
|
69
|
-
| `name` | string | yes | Session name
|
|
70
|
-
| `message` | string | yes | Message to send
|
|
71
|
-
| `effort` | string | |
|
|
72
|
-
| `plan` | boolean | |
|
|
73
|
-
| `timeout` | number | | Timeout in ms (default 300000)
|
|
74
|
-
| `stream` | boolean | | Collect
|
|
75
|
-
|
|
76
|
-
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
|
|
77
86
|
calls the engine refused during the turn — `[{ toolName, toolUseId?, input? }]` — and is present only
|
|
78
87
|
when there was at least one. Check it even when `error` is absent: a turn whose tool calls were all
|
|
79
88
|
denied still ends as a success. See [sessions.md](./sessions.md) on what "succeeded" does and does
|
|
@@ -87,15 +96,16 @@ Continue a session's conversation on another engine — or the same engine with
|
|
|
87
96
|
a new session in the source's working directory and carries the conversation into it; the source
|
|
88
97
|
keeps running untouched.
|
|
89
98
|
|
|
90
|
-
| Parameter | Type
|
|
91
|
-
| -------------- |
|
|
92
|
-
| `name` | string
|
|
93
|
-
| `engine` | string
|
|
94
|
-
| `model` | string
|
|
95
|
-
| `newName` | string
|
|
96
|
-
| `message` | string
|
|
97
|
-
| `maxChars` | number
|
|
98
|
-
| `
|
|
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` |
|
|
99
109
|
|
|
100
110
|
Returns `{ ok, name, engine, from: { name, engine }, carried: { turns, omitted, chars }, result? }`.
|
|
101
111
|
`result` is the send result of `message`, when one was given. See [sessions.md](./sessions.md) for
|
|
@@ -103,7 +113,9 @@ what carries across, what does not, and what is kept when the conversation is to
|
|
|
103
113
|
|
|
104
114
|
### `session_stop`
|
|
105
115
|
|
|
106
|
-
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.
|
|
107
119
|
|
|
108
120
|
| Parameter | Type | Required |
|
|
109
121
|
| --------- | ------ | -------- |
|
|
@@ -123,7 +135,7 @@ Dashboard view: all sessions with ready/busy/paused state, cost, context %, last
|
|
|
123
135
|
|
|
124
136
|
### `coding_session_status`
|
|
125
137
|
|
|
126
|
-
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`.)
|
|
127
139
|
|
|
128
140
|
| Parameter | Type | Required |
|
|
129
141
|
| --------- | ------ | -------- |
|
|
@@ -131,14 +143,15 @@ Detailed status: tokens, cost, context %, tool calls, uptime. (Prefixed to avoid
|
|
|
131
143
|
|
|
132
144
|
**Returned stats fields** (selected):
|
|
133
145
|
|
|
134
|
-
| Field | Type | Description
|
|
135
|
-
| ---------------- | ------------------- |
|
|
136
|
-
| `retries` | number |
|
|
137
|
-
| `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 |
|
|
138
150
|
|
|
139
151
|
### `session_grep`
|
|
140
152
|
|
|
141
|
-
|
|
153
|
+
Case-insensitive regex search over the session's in-memory event history, which keeps the 100 most
|
|
154
|
+
recent events.
|
|
142
155
|
|
|
143
156
|
| Parameter | Type | Required | Description |
|
|
144
157
|
| --------- | ------ | -------- | ------------------------ |
|
|
@@ -157,19 +170,20 @@ Reclaim context window via `/compact`.
|
|
|
157
170
|
|
|
158
171
|
### `session_update_tools`
|
|
159
172
|
|
|
160
|
-
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.
|
|
161
175
|
|
|
162
|
-
| Parameter | Type | Description
|
|
163
|
-
| ----------------- | -------- |
|
|
164
|
-
| `name` | string | Session name
|
|
165
|
-
| `allowedTools` | string[] | New allowed tools (replaces or merges)
|
|
166
|
-
| `disallowedTools` | string[] | New disallowed tools
|
|
167
|
-
| `removeTools` | string[] | Tools to remove from lists
|
|
168
|
-
| `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) |
|
|
169
183
|
|
|
170
184
|
### `session_switch_model`
|
|
171
185
|
|
|
172
|
-
Hot-swap model mid-conversation. Restarts with `--resume
|
|
186
|
+
Hot-swap model mid-conversation. Restarts with `--resume`; refused while a turn is in flight.
|
|
173
187
|
|
|
174
188
|
| Parameter | Type | Required |
|
|
175
189
|
| --------- | ------ | -------- |
|
|
@@ -259,7 +273,7 @@ Returns `{ ok, agents }`.
|
|
|
259
273
|
|
|
260
274
|
## Codex (13)
|
|
261
275
|
|
|
262
|
-
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.
|
|
263
277
|
|
|
264
278
|
### `codex_resume`
|
|
265
279
|
|
|
@@ -280,7 +294,9 @@ Returns `{ ok, text, threadId?, usage?, events }`.
|
|
|
280
294
|
|
|
281
295
|
### `codex_review`
|
|
282
296
|
|
|
283
|
-
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.
|
|
284
300
|
|
|
285
301
|
| Parameter | Type | Description |
|
|
286
302
|
| ------------- | ------- | ---------------------------------------------- |
|
|
@@ -354,22 +370,22 @@ Run one task across N engine/model agents **in parallel** and collect their answ
|
|
|
354
370
|
|
|
355
371
|
### `fanout_start`
|
|
356
372
|
|
|
357
|
-
| Parameter | Type | Required | Description
|
|
358
|
-
| ------------------------------------ | ------- | -------- |
|
|
359
|
-
| `task` | string | yes | Shared task sent to every agent, optionally after its `persona`.
|
|
360
|
-
| `projectDir` | string | yes | Working directory all agents run in.
|
|
361
|
-
| `agents` | array | yes |
|
|
362
|
-
| `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2).
|
|
363
|
-
| `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`).
|
|
364
|
-
| `
|
|
365
|
-
| `
|
|
366
|
-
| `
|
|
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. |
|
|
367
384
|
|
|
368
385
|
Runs in the background; returns `{ ok, id, status, ... }`. Poll with `fanout_status`.
|
|
369
386
|
Each agent's optional `effort` accepts `low`, `medium`, `high`, `xhigh`, `max`,
|
|
370
|
-
`ultra`, or `auto`. Omit it to keep the session default. The
|
|
371
|
-
|
|
372
|
-
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`.
|
|
373
389
|
|
|
374
390
|
Per-agent `persona` provides role instructions without replacing the shared
|
|
375
391
|
task. Fan-out sends `<persona>\n\n## Shared task\n\n<task>`. A non-empty
|
|
@@ -380,16 +396,23 @@ resume/recovery repeats the same message construction.
|
|
|
380
396
|
|
|
381
397
|
### `fanout_status`
|
|
382
398
|
|
|
383
|
-
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.
|
|
384
402
|
|
|
385
403
|
### `fanout_abort`
|
|
386
404
|
|
|
387
|
-
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.
|
|
388
407
|
|
|
389
408
|
---
|
|
390
409
|
|
|
391
410
|
## Agent Teams (3)
|
|
392
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
|
+
|
|
393
416
|
### `coding_agents_list`
|
|
394
417
|
|
|
395
418
|
List agent definitions from `.claude/agents/` (project + global). (Prefixed to avoid clashing with OpenClaw's built-in `agents_list`.)
|
|
@@ -400,7 +423,8 @@ List agent definitions from `.claude/agents/` (project + global). (Prefixed to a
|
|
|
400
423
|
|
|
401
424
|
### `team_list`
|
|
402
425
|
|
|
403
|
-
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.
|
|
404
428
|
|
|
405
429
|
| Parameter | Type | Required |
|
|
406
430
|
| --------- | ------ | -------- |
|
|
@@ -408,7 +432,8 @@ List teammates in an agent team session.
|
|
|
408
432
|
|
|
409
433
|
### `team_send`
|
|
410
434
|
|
|
411
|
-
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.
|
|
412
437
|
|
|
413
438
|
| Parameter | Type | Required |
|
|
414
439
|
| ---------- | ------ | -------- |
|
|
@@ -424,16 +449,16 @@ Send message to a specific teammate.
|
|
|
424
449
|
|
|
425
450
|
Start a multi-agent council. Runs in background, returns session ID immediately.
|
|
426
451
|
|
|
427
|
-
| Parameter | Type | Required | Description
|
|
428
|
-
| ----------------------- | -------------- | -------- |
|
|
429
|
-
| `task` | string | yes | Task description
|
|
430
|
-
| `projectDir` | string | yes | Working directory
|
|
431
|
-
| `agents` | AgentPersona[] | |
|
|
432
|
-
| `maxRounds` | number | | Max rounds (default 15)
|
|
433
|
-
| `agentTimeoutMs` | number | | Per-agent timeout (default 1800000)
|
|
434
|
-
| `maxTurnsPerAgent` | number | | Max tool turns per agent (default
|
|
435
|
-
| `maxBudgetUsd` | number | | Max API spend per agent
|
|
436
|
-
| `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` |
|
|
437
462
|
|
|
438
463
|
### `council_status`
|
|
439
464
|
|
|
@@ -445,15 +470,20 @@ Get status of a running or recently completed council.
|
|
|
445
470
|
|
|
446
471
|
### `council_abort`
|
|
447
472
|
|
|
448
|
-
Abort a running
|
|
473
|
+
Abort a council running in this process, stopping all agent sessions and removing the worktrees it created.
|
|
449
474
|
|
|
450
475
|
| Parameter | Type | Required |
|
|
451
476
|
| --------- | ------ | -------- |
|
|
452
477
|
| `id` | string | yes |
|
|
453
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
|
+
|
|
454
482
|
### `council_inject`
|
|
455
483
|
|
|
456
|
-
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.
|
|
457
487
|
|
|
458
488
|
| Parameter | Type | Required |
|
|
459
489
|
| --------- | ------ | -------- |
|
|
@@ -472,7 +502,7 @@ Review a completed council session. Returns a structured report of all changed f
|
|
|
472
502
|
|
|
473
503
|
### `council_accept`
|
|
474
504
|
|
|
475
|
-
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.
|
|
476
506
|
|
|
477
507
|
| Parameter | Type | Required |
|
|
478
508
|
| --------- | ------ | -------- |
|
|
@@ -482,7 +512,7 @@ Accept and finalize council work. Cleans up all council scaffolding: removes wor
|
|
|
482
512
|
|
|
483
513
|
### `council_reject`
|
|
484
514
|
|
|
485
|
-
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`.
|
|
486
516
|
|
|
487
517
|
| Parameter | Type | Required | Description |
|
|
488
518
|
| ---------- | ------ | -------- | ------------------------------------------- |
|
|
@@ -604,9 +634,10 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
|
|
|
604
634
|
> **Custom engines are local-only.** A `CustomEngineConfig` names an executable to
|
|
605
635
|
> spawn plus its argv and env, so it may only be supplied by a caller that already
|
|
606
636
|
> runs on the host (this MCP tool, or the `SessionManager` API). **Every** HTTP
|
|
607
|
-
> request body is checked, on every route, and one carrying
|
|
608
|
-
>
|
|
609
|
-
> 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
|
|
610
641
|
> often reverse-tunnelled and its token is a monitoring credential, not
|
|
611
642
|
> permission to choose what binary runs. Built-in engines stay fully selectable
|
|
612
643
|
> over HTTP.
|
|
@@ -669,7 +700,8 @@ history.
|
|
|
669
700
|
|
|
670
701
|
### `autoloop_status`
|
|
671
702
|
|
|
672
|
-
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 }`.
|
|
673
705
|
|
|
674
706
|
| Parameter | Type | Required |
|
|
675
707
|
| --------- | ------ | -------- |
|
|
@@ -677,7 +709,7 @@ Get the current state and push log.
|
|
|
677
709
|
|
|
678
710
|
### `autoloop_list`
|
|
679
711
|
|
|
680
|
-
List
|
|
712
|
+
List the Autoloop runs recorded on this machine, running and finished, newest first.
|
|
681
713
|
|
|
682
714
|
(no params)
|
|
683
715
|
|
|
@@ -707,9 +739,14 @@ Terminate the run and stop all role sessions.
|
|
|
707
739
|
|
|
708
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).
|
|
709
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
|
+
|
|
710
746
|
### `ultraapp_list`
|
|
711
747
|
|
|
712
|
-
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`.
|
|
713
750
|
|
|
714
751
|
(no params)
|
|
715
752
|
|
|
@@ -723,7 +760,7 @@ Full snapshot of a run: spec + chat + state.
|
|
|
723
760
|
|
|
724
761
|
### `ultraapp_status`
|
|
725
762
|
|
|
726
|
-
Lightweight status
|
|
763
|
+
Lightweight status: mode, timestamps, and the failure reason if any.
|
|
727
764
|
|
|
728
765
|
| Parameter | Type | Required |
|
|
729
766
|
| --------- | ------ | -------- |
|
|
@@ -781,7 +818,7 @@ Abort an active build. Council sessions are stopped and the worktrees are left a
|
|
|
781
818
|
|
|
782
819
|
### `ultraapp_feedback`
|
|
783
820
|
|
|
784
|
-
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.
|
|
785
822
|
|
|
786
823
|
| Parameter | Type | Required | Description |
|
|
787
824
|
| --------- | ------ | -------- | ----------------------- |
|
|
@@ -790,7 +827,7 @@ Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spe
|
|
|
790
827
|
|
|
791
828
|
### `ultraapp_promote_version`
|
|
792
829
|
|
|
793
|
-
|
|
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.
|
|
794
831
|
|
|
795
832
|
| Parameter | Type | Required | Description |
|
|
796
833
|
| --------- | ------ | -------- | ------------------------------------ |
|
|
@@ -833,39 +870,52 @@ Full semantics in [`workflow.md`](./workflow.md) and
|
|
|
833
870
|
Start a durable run. Every state transition is checkpointed to disk, so a run
|
|
834
871
|
survives a process restart and can be resumed.
|
|
835
872
|
|
|
836
|
-
| Param | Type
|
|
837
|
-
| ------------- |
|
|
838
|
-
| `spec` | object
|
|
839
|
-
| `template` | `solve` \| `council` \| `fanout` | Build a built-in instead of supplying `spec`
|
|
840
|
-
| `task` | string
|
|
841
|
-
| `agents` | array
|
|
842
|
-
| `reviewers` | array
|
|
843
|
-
| `implementer` | object
|
|
844
|
-
| `humanGate` | boolean
|
|
845
|
-
| `
|
|
846
|
-
| `
|
|
847
|
-
| `
|
|
848
|
-
| `
|
|
849
|
-
|
|
850
|
-
|
|
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).
|
|
851
894
|
|
|
852
895
|
### `workflow_status`
|
|
853
896
|
|
|
854
|
-
`{ runId, events? }` → run state, per-node status, `outcome`, `
|
|
855
|
-
`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.
|
|
856
900
|
|
|
857
901
|
`outcome` is `verified` (a contract passed), `refuted` (it failed), or
|
|
858
|
-
`unverified` (**
|
|
859
|
-
|
|
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.
|
|
860
907
|
|
|
861
908
|
### `workflow_list` / `workflow_resume` / `workflow_cancel` / `workflow_steer` / `workflow_approve`
|
|
862
909
|
|
|
863
|
-
- `workflow_list({ workflow?, state?, limit? })` — newest first, survives
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
-
|
|
868
|
-
|
|
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
|
|
869
919
|
node's prompt. Steers not yet consumed are delivered after a restart too.
|
|
870
920
|
- `workflow_approve({ runId, approved })` — answers a `human_gate` node. A run
|
|
871
921
|
parked before the server restarted is resumed with the answer attached, so it
|
|
@@ -876,10 +926,12 @@ same as a failure).
|
|
|
876
926
|
|
|
877
927
|
Run an acceptance contract against a directory outside any workflow — for a plain
|
|
878
928
|
`session_send` that edited a repo, say. `{ cwd, contract, baseSha?, label? }` →
|
|
879
|
-
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.
|
|
880
931
|
|
|
881
932
|
Without `baseSha`, `diff_policy` sees untracked files only. `verify_run` has no record of
|
|
882
|
-
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.
|
|
883
935
|
|
|
884
936
|
### The `contract` parameter
|
|
885
937
|
|