@enderfga/claw-orchestrator 5.0.0 → 6.0.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.
Files changed (158) hide show
  1. package/README.md +28 -28
  2. package/dist/bin/cli.js +107 -1
  3. package/dist/bin/cli.js.map +1 -1
  4. package/dist/src/acp-server.d.ts +5 -5
  5. package/dist/src/acp-server.js +3 -3
  6. package/dist/src/acp-server.js.map +1 -1
  7. package/dist/src/autoloop/dispatcher.d.ts +22 -0
  8. package/dist/src/autoloop/dispatcher.js +71 -13
  9. package/dist/src/autoloop/dispatcher.js.map +1 -1
  10. package/dist/src/autoloop/messages.d.ts +10 -0
  11. package/dist/src/autoloop/messages.js.map +1 -1
  12. package/dist/src/autoloop/runner.js +6 -0
  13. package/dist/src/autoloop/runner.js.map +1 -1
  14. package/dist/src/constants.d.ts +0 -6
  15. package/dist/src/constants.js +0 -6
  16. package/dist/src/constants.js.map +1 -1
  17. package/dist/src/council.d.ts +15 -0
  18. package/dist/src/council.js +48 -35
  19. package/dist/src/council.js.map +1 -1
  20. package/dist/src/dashboard/index.html +191 -6
  21. package/dist/src/embedded-server.js +132 -9
  22. package/dist/src/embedded-server.js.map +1 -1
  23. package/dist/src/fanout.d.ts +30 -1
  24. package/dist/src/fanout.js +32 -3
  25. package/dist/src/fanout.js.map +1 -1
  26. package/dist/src/index.d.ts +1 -0
  27. package/dist/src/index.js +360 -4
  28. package/dist/src/index.js.map +1 -1
  29. package/dist/src/kernel/agent-step.d.ts +59 -0
  30. package/dist/src/kernel/agent-step.js +100 -0
  31. package/dist/src/kernel/agent-step.js.map +1 -0
  32. package/dist/src/kernel/conditions.d.ts +11 -0
  33. package/dist/src/kernel/conditions.js +24 -0
  34. package/dist/src/kernel/conditions.js.map +1 -0
  35. package/dist/src/kernel/engine.d.ts +319 -0
  36. package/dist/src/kernel/engine.js +1047 -0
  37. package/dist/src/kernel/engine.js.map +1 -0
  38. package/dist/src/kernel/exec.d.ts +43 -0
  39. package/dist/src/kernel/exec.js +112 -0
  40. package/dist/src/kernel/exec.js.map +1 -0
  41. package/dist/src/kernel/file-lock.d.ts +50 -0
  42. package/dist/src/kernel/file-lock.js +135 -0
  43. package/dist/src/kernel/file-lock.js.map +1 -0
  44. package/dist/src/kernel/nodes/agent.d.ts +4 -0
  45. package/dist/src/kernel/nodes/agent.js +35 -0
  46. package/dist/src/kernel/nodes/agent.js.map +1 -0
  47. package/dist/src/kernel/nodes/autoloop.d.ts +78 -0
  48. package/dist/src/kernel/nodes/autoloop.js +75 -0
  49. package/dist/src/kernel/nodes/autoloop.js.map +1 -0
  50. package/dist/src/kernel/nodes/council.d.ts +12 -0
  51. package/dist/src/kernel/nodes/council.js +88 -0
  52. package/dist/src/kernel/nodes/council.js.map +1 -0
  53. package/dist/src/kernel/nodes/fanout.d.ts +11 -0
  54. package/dist/src/kernel/nodes/fanout.js +63 -0
  55. package/dist/src/kernel/nodes/fanout.js.map +1 -0
  56. package/dist/src/kernel/nodes/human-gate.d.ts +4 -0
  57. package/dist/src/kernel/nodes/human-gate.js +7 -0
  58. package/dist/src/kernel/nodes/human-gate.js.map +1 -0
  59. package/dist/src/kernel/nodes/index.d.ts +12 -0
  60. package/dist/src/kernel/nodes/index.js +21 -0
  61. package/dist/src/kernel/nodes/index.js.map +1 -0
  62. package/dist/src/kernel/nodes/router.d.ts +4 -0
  63. package/dist/src/kernel/nodes/router.js +12 -0
  64. package/dist/src/kernel/nodes/router.js.map +1 -0
  65. package/dist/src/kernel/nodes/subflow.d.ts +13 -0
  66. package/dist/src/kernel/nodes/subflow.js +38 -0
  67. package/dist/src/kernel/nodes/subflow.js.map +1 -0
  68. package/dist/src/kernel/nodes/ultraapp.d.ts +60 -0
  69. package/dist/src/kernel/nodes/ultraapp.js +62 -0
  70. package/dist/src/kernel/nodes/ultraapp.js.map +1 -0
  71. package/dist/src/kernel/nodes/verifier.d.ts +14 -0
  72. package/dist/src/kernel/nodes/verifier.js +84 -0
  73. package/dist/src/kernel/nodes/verifier.js.map +1 -0
  74. package/dist/src/kernel/projections.d.ts +42 -0
  75. package/dist/src/kernel/projections.js +133 -0
  76. package/dist/src/kernel/projections.js.map +1 -0
  77. package/dist/src/kernel/repo.d.ts +13 -0
  78. package/dist/src/kernel/repo.js +64 -0
  79. package/dist/src/kernel/repo.js.map +1 -0
  80. package/dist/src/kernel/secrets.d.ts +25 -0
  81. package/dist/src/kernel/secrets.js +48 -0
  82. package/dist/src/kernel/secrets.js.map +1 -0
  83. package/dist/src/kernel/store.d.ts +225 -0
  84. package/dist/src/kernel/store.js +838 -0
  85. package/dist/src/kernel/store.js.map +1 -0
  86. package/dist/src/kernel/templates/index.d.ts +140 -0
  87. package/dist/src/kernel/templates/index.js +266 -0
  88. package/dist/src/kernel/templates/index.js.map +1 -0
  89. package/dist/src/kernel/types.d.ts +326 -0
  90. package/dist/src/kernel/types.js +19 -0
  91. package/dist/src/kernel/types.js.map +1 -0
  92. package/dist/src/models.d.ts +1 -1
  93. package/dist/src/models.js +31 -3
  94. package/dist/src/models.js.map +1 -1
  95. package/dist/src/persistent-cursor-session.js +6 -1
  96. package/dist/src/persistent-cursor-session.js.map +1 -1
  97. package/dist/src/persistent-grok-session.d.ts +40 -0
  98. package/dist/src/persistent-grok-session.js +197 -0
  99. package/dist/src/persistent-grok-session.js.map +1 -0
  100. package/dist/src/run-ledger.d.ts +57 -3
  101. package/dist/src/run-ledger.js +45 -2
  102. package/dist/src/run-ledger.js.map +1 -1
  103. package/dist/src/session-manager.d.ts +176 -129
  104. package/dist/src/session-manager.js +657 -603
  105. package/dist/src/session-manager.js.map +1 -1
  106. package/dist/src/types.d.ts +37 -4
  107. package/dist/src/types.js +15 -1
  108. package/dist/src/types.js.map +1 -1
  109. package/dist/src/ultraapp/build.d.ts +117 -3
  110. package/dist/src/ultraapp/build.js +319 -3
  111. package/dist/src/ultraapp/build.js.map +1 -1
  112. package/dist/src/ultraapp/contract.d.ts +52 -0
  113. package/dist/src/ultraapp/contract.js +83 -0
  114. package/dist/src/ultraapp/contract.js.map +1 -0
  115. package/dist/src/ultraapp/conventions.js +9 -2
  116. package/dist/src/ultraapp/conventions.js.map +1 -1
  117. package/dist/src/ultraapp/fix-on-failure.d.ts +21 -2
  118. package/dist/src/ultraapp/fix-on-failure.js +46 -62
  119. package/dist/src/ultraapp/fix-on-failure.js.map +1 -1
  120. package/dist/src/ultraapp/manager.d.ts +107 -2
  121. package/dist/src/ultraapp/manager.js +305 -86
  122. package/dist/src/ultraapp/manager.js.map +1 -1
  123. package/dist/src/verify/baseline.d.ts +73 -0
  124. package/dist/src/verify/baseline.js +186 -0
  125. package/dist/src/verify/baseline.js.map +1 -0
  126. package/dist/src/verify/contract.d.ts +116 -0
  127. package/dist/src/verify/contract.js +142 -0
  128. package/dist/src/verify/contract.js.map +1 -0
  129. package/dist/src/verify/evidence.d.ts +61 -0
  130. package/dist/src/verify/evidence.js +133 -0
  131. package/dist/src/verify/evidence.js.map +1 -0
  132. package/dist/src/verify/runner.d.ts +63 -0
  133. package/dist/src/verify/runner.js +317 -0
  134. package/dist/src/verify/runner.js.map +1 -0
  135. package/openclaw.plugin.json +8 -0
  136. package/package.json +2 -2
  137. package/skills/SKILL.md +121 -80
  138. package/skills/references/acp.md +18 -18
  139. package/skills/references/autoloop.md +148 -72
  140. package/skills/references/claude-cli-tracking.md +4 -4
  141. package/skills/references/cli.md +103 -60
  142. package/skills/references/council.md +109 -37
  143. package/skills/references/dashboard.md +34 -6
  144. package/skills/references/getting-started.md +14 -14
  145. package/skills/references/inbox.md +4 -4
  146. package/skills/references/mcp.md +39 -34
  147. package/skills/references/multi-engine.md +109 -51
  148. package/skills/references/observability.md +88 -27
  149. package/skills/references/openai-compat.md +40 -40
  150. package/skills/references/sessions.md +44 -26
  151. package/skills/references/tools.md +402 -309
  152. package/skills/references/ultra.md +45 -45
  153. package/skills/references/ultraapp.md +126 -50
  154. package/skills/references/verification.md +187 -0
  155. package/skills/references/workflow.md +362 -0
  156. package/dist/src/ultraapp/fix-on-failure-session.d.ts +0 -23
  157. package/dist/src/ultraapp/fix-on-failure-session.js +0 -51
  158. package/dist/src/ultraapp/fix-on-failure-session.js.map +0 -1
package/skills/SKILL.md CHANGED
@@ -1,106 +1,111 @@
1
1
  ---
2
2
  name: claw-orchestrator
3
- description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Cursor, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 69 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "how much did it cost", "token usage", "spend cap", "budget limit", "maxBudgetUsd".
3
+ description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 77 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "grok", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "how much did it cost", "token usage", "spend cap", "budget limit", "maxBudgetUsd", "workflow", "durable workflow", "resume a run", "verify", "verification", "acceptance contract", "evidence", "evidence bundle", "did the tests actually pass", "prove it works", "human gate", "repair loop", "clawo workflow", "clawo verify".
4
4
  metadata:
5
5
  {
6
- "openclaw":
6
+ 'openclaw':
7
7
  {
8
- "emoji": "🤖",
9
- "requires": { "anyBins": ["claude", "codex", "agy", "agent"] },
10
- "install":
8
+ 'emoji': '🤖',
9
+ 'requires': { 'anyBins': ['claude', 'codex', 'agy', 'agent'] },
10
+ 'install':
11
11
  [
12
12
  {
13
- "id": "npm-plugin",
14
- "kind": "node",
15
- "package": "@enderfga/claw-orchestrator",
16
- "label": "Install plugin (npm)"
13
+ 'id': 'npm-plugin',
14
+ 'kind': 'node',
15
+ 'package': '@enderfga/claw-orchestrator',
16
+ 'label': 'Install plugin (npm)',
17
17
  },
18
18
  {
19
- "id": "node-claude",
20
- "kind": "node",
21
- "package": "@anthropic-ai/claude-code",
22
- "bins": ["claude"],
23
- "label": "Install Claude Code CLI"
19
+ 'id': 'node-claude',
20
+ 'kind': 'node',
21
+ 'package': '@anthropic-ai/claude-code',
22
+ 'bins': ['claude'],
23
+ 'label': 'Install Claude Code CLI',
24
24
  },
25
25
  {
26
- "id": "node-codex",
27
- "kind": "node",
28
- "package": "@openai/codex",
29
- "bins": ["codex"],
30
- "label": "Install Codex CLI"
31
- }
32
- ]
33
- }
26
+ 'id': 'node-codex',
27
+ 'kind': 'node',
28
+ 'package': '@openai/codex',
29
+ 'bins': ['codex'],
30
+ 'label': 'Install Codex CLI',
31
+ },
32
+ ],
33
+ },
34
34
  }
35
35
  ---
36
36
 
37
37
  # Claw Orchestrator Skill
38
38
 
39
- Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Antigravity, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 69 tools.
39
+ Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Antigravity, Grok Build, OpenCode, and custom CLIs into headless agentic engines with 77 tools.
40
40
 
41
41
  ## Engine Quick Reference
42
42
 
43
- | Engine | CLI | Session Type | Best For |
44
- |--------|-----|-------------|----------|
45
- | `claude` | `claude` | Persistent subprocess | Multi-turn, complex tasks |
46
- | `codex` | `codex exec` | Per-message spawn | One-shot execution |
47
- | `agy` | `agy -p` | Per-message spawn | Google Antigravity; plain-text, auto conversation resume |
48
- | `cursor` | `agent -p` | Per-message spawn | One-shot execution |
49
- | `opencode` | `opencode run` | Per-message spawn | Provider-agnostic (`provider/model`) |
43
+ | Engine | CLI | Session Type | Best For |
44
+ | ---------- | -------------- | --------------------- | -------------------------------------------------------- |
45
+ | `claude` | `claude` | Persistent subprocess | Multi-turn, complex tasks |
46
+ | `codex` | `codex exec` | Per-message spawn | One-shot execution |
47
+ | `agy` | `agy -p` | Per-message spawn | Google Antigravity; plain-text, auto conversation resume |
48
+ | `grok` | `grok -p` | Per-message spawn | xAI Grok Build; engine-reported cost, resumable session |
49
+ | `opencode` | `opencode run` | Per-message spawn | Provider-agnostic (`provider/model`) |
50
50
 
51
51
  ## Core Workflow
52
52
 
53
53
  ```javascript
54
54
  // 1. Start session (any engine)
55
- session_start({ name: "myproject", cwd: "/path/to/project", engine: "claude" })
56
- session_start({ name: "codex-task", cwd: "/path/to/project", engine: "codex" })
57
- session_start({ name: "agy-task", cwd: "/path/to/project", engine: "agy" })
58
- session_start({ name: "cursor-task", cwd: "/path/to/project", engine: "cursor" })
59
- session_start({ name: "opencode-task", cwd: "/path/to/project", engine: "opencode", model: "anthropic/claude-sonnet-4" })
55
+ session_start({ name: 'myproject', cwd: '/path/to/project', engine: 'claude' });
56
+ session_start({ name: 'codex-task', cwd: '/path/to/project', engine: 'codex' });
57
+ session_start({ name: 'agy-task', cwd: '/path/to/project', engine: 'agy' });
58
+ session_start({ name: 'grok-task', cwd: '/path/to/project', engine: 'grok' });
59
+ session_start({
60
+ name: 'opencode-task',
61
+ cwd: '/path/to/project',
62
+ engine: 'opencode',
63
+ model: 'anthropic/claude-sonnet-4',
64
+ });
60
65
 
61
66
  // 2. Send messages
62
- session_send({ name: "myproject", message: "Fix the auth bug" })
67
+ session_send({ name: 'myproject', message: 'Fix the auth bug' });
63
68
 
64
69
  // 3. Check status / search history
65
- coding_session_status({ name: "myproject" })
66
- session_grep({ name: "myproject", pattern: "error" })
70
+ coding_session_status({ name: 'myproject' });
71
+ session_grep({ name: 'myproject', pattern: 'error' });
67
72
 
68
73
  // 4. Stop when done
69
- session_stop({ name: "myproject" })
74
+ session_stop({ name: 'myproject' });
70
75
  ```
71
76
 
72
77
  ## Session Options
73
78
 
74
- | Parameter | Description |
75
- |-----------|-------------|
76
- | `engine` | `claude` (default), `codex`, `agy`, `cursor`, `opencode` |
77
- | `model` | Model name or alias (`fable`, `opus`, `sonnet`, `haiku`, `gpt-5.5`, `agy-pro`, `composer-2`) |
79
+ | Parameter | Description |
80
+ | ---------------- | --------------------------------------------------------------------------------------------------------------- |
81
+ | `engine` | `claude` (default), `codex`, `agy`, `cursor`, `opencode` |
82
+ | `model` | Model name or alias (`fable`, `opus`, `sonnet`, `haiku`, `gpt-5.5`, `agy-pro`, `composer-2`) |
78
83
  | `permissionMode` | `acceptEdits`, `auto`, `plan`, `bypassPermissions`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
79
- | `effort` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (`xhigh` is Opus 4.7-only, between `high` and `max`) |
80
- | `maxBudgetUsd` | Cost limit in USD |
81
- | `allowedTools` | List of allowed tool names |
84
+ | `effort` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (`xhigh` is Opus 4.7-only, between `high` and `max`) |
85
+ | `maxBudgetUsd` | Cost limit in USD |
86
+ | `allowedTools` | List of allowed tool names |
82
87
 
83
88
  ### CLI 2.1.111 options
84
89
 
85
- | Parameter | Description |
86
- |-----------|-------------|
87
- | `bare` | Minimal mode — no CLAUDE.md, hooks, LSP, auto-memory. Auto-enables prompt cache optimizations (see below). |
88
- | `includeHookEvents` | Stream hook lifecycle events (PreToolUse/PostToolUse). |
89
- | `forwardSubagentText` | Forward subagent text and thinking into the output stream, so sessions that fan out surface intermediate output instead of going quiet. |
90
- | `permissionPromptTool` | Delegate permission prompts to an MCP tool for non-interactive use. |
91
- | `excludeDynamicSystemPromptSections` | Move cwd/env/git from system prompt to user message for better prompt cache hits. Auto-enabled with `bare: true`. |
92
- | `enablePromptCaching1H` | Enable 1-hour prompt cache TTL (vs default 5-min). Auto-enabled with `bare: true`. |
93
- | `debug` / `debugFile` | Targeted debug output by category (e.g. `"api,mcp"`) and optional file path. |
94
- | `fromPr` | Resume a session linked to a GitHub PR number or URL. |
95
- | `channels` / `dangerouslyLoadDevelopmentChannels` | MCP channel subscriptions (research preview). |
90
+ | Parameter | Description |
91
+ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
92
+ | `bare` | Minimal mode — no CLAUDE.md, hooks, LSP, auto-memory. Auto-enables prompt cache optimizations (see below). |
93
+ | `includeHookEvents` | Stream hook lifecycle events (PreToolUse/PostToolUse). |
94
+ | `forwardSubagentText` | Forward subagent text and thinking into the output stream, so sessions that fan out surface intermediate output instead of going quiet. |
95
+ | `permissionPromptTool` | Delegate permission prompts to an MCP tool for non-interactive use. |
96
+ | `excludeDynamicSystemPromptSections` | Move cwd/env/git from system prompt to user message for better prompt cache hits. Auto-enabled with `bare: true`. |
97
+ | `enablePromptCaching1H` | Enable 1-hour prompt cache TTL (vs default 5-min). Auto-enabled with `bare: true`. |
98
+ | `debug` / `debugFile` | Targeted debug output by category (e.g. `"api,mcp"`) and optional file path. |
99
+ | `fromPr` | Resume a session linked to a GitHub PR number or URL. |
100
+ | `channels` / `dangerouslyLoadDevelopmentChannels` | MCP channel subscriptions (research preview). |
96
101
 
97
102
  ### CLI 2.1.121 options
98
103
 
99
- | Parameter | Description |
100
- |-----------|-------------|
101
- | `forkSubagent` | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`). |
102
- | `enableToolSearch` | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`). |
103
- | `otelLogUserPrompts` | OpenTelemetry: include user prompts in logs (sets `OTEL_LOG_USER_PROMPTS=1`). |
104
+ | Parameter | Description |
105
+ | --------------------- | --------------------------------------------------------------------------------------------- |
106
+ | `forkSubagent` | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`). |
107
+ | `enableToolSearch` | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`). |
108
+ | `otelLogUserPrompts` | OpenTelemetry: include user prompts in logs (sets `OTEL_LOG_USER_PROMPTS=1`). |
104
109
  | `otelLogRawApiBodies` | OpenTelemetry: include raw API bodies in logs (sets `OTEL_LOG_RAW_API_BODIES=1`). Debug only. |
105
110
 
106
111
  `stats.pluginErrors` is now populated from the `system/init` event when CLI plugins fail to load due to unmet dependencies.
@@ -135,10 +140,10 @@ For details: see [references/council.md](references/council.md)
135
140
  Sessions can communicate. Idle sessions receive immediately; busy sessions queue.
136
141
 
137
142
  ```javascript
138
- session_send_to({ from: "sender", to: "receiver", message: "Auth module needs rate limiting" })
139
- session_send_to({ from: "monitor", to: "*", message: "Build failed!" }) // broadcast
140
- session_inbox({ name: "receiver" })
141
- session_deliver_inbox({ name: "receiver" })
143
+ session_send_to({ from: 'sender', to: 'receiver', message: 'Auth module needs rate limiting' });
144
+ session_send_to({ from: 'monitor', to: '*', message: 'Build failed!' }); // broadcast
145
+ session_inbox({ name: 'receiver' });
146
+ session_deliver_inbox({ name: 'receiver' });
142
147
  ```
143
148
 
144
149
  ## Team Tools (All Engines)
@@ -146,8 +151,8 @@ session_deliver_inbox({ name: "receiver" })
146
151
  All engines use the same virtual-team layer: cross-session inbox routing across active SessionManager sessions. (Claude Code's native experimental Agent Teams is in-process TUI only and not reachable from a subprocess wrapper.)
147
152
 
148
153
  ```javascript
149
- team_list({ name: "myproject" })
150
- team_send({ name: "myproject", teammate: "teammate", message: "Review this" })
154
+ team_list({ name: 'myproject' });
155
+ team_send({ name: 'myproject', teammate: 'teammate', message: 'Review this' });
151
156
  ```
152
157
 
153
158
  ## Ultraplan & Ultrareview
@@ -181,17 +186,17 @@ For the full control protocol, registry/resume behavior, and ledger layout, see
181
186
 
182
187
  ## Tools Overview
183
188
 
184
- | Category | Tools |
185
- |----------|-------|
186
- | Session Lifecycle | `session_start`, `session_send`, `session_stop`, `session_list`, `sessions_overview` |
187
- | Session Ops | `coding_session_status`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model` |
188
- | Inbox | `session_send_to`, `session_inbox`, `session_deliver_inbox` |
189
- | Teams | `coding_agents_list`, `team_list`, `team_send` |
190
- | Codex | `codex_resume`, `codex_review`, `codex_goal_*`, `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_threads` |
191
- | Claude CLI | `claude_goal_*`, `claude_agents_list`, `plugin_details` |
192
- | Fan-out | `fanout_start`, `fanout_status`, `fanout_abort` |
193
- | Council | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject` |
194
- | Ultra | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status` |
189
+ | Category | Tools |
190
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
191
+ | Session Lifecycle | `session_start`, `session_send`, `session_stop`, `session_list`, `sessions_overview` |
192
+ | Session Ops | `coding_session_status`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model` |
193
+ | Inbox | `session_send_to`, `session_inbox`, `session_deliver_inbox` |
194
+ | Teams | `coding_agents_list`, `team_list`, `team_send` |
195
+ | Codex | `codex_resume`, `codex_review`, `codex_goal_*`, `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_threads` |
196
+ | Claude CLI | `claude_goal_*`, `claude_agents_list`, `plugin_details` |
197
+ | Fan-out | `fanout_start`, `fanout_status`, `fanout_abort` |
198
+ | Council | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject` |
199
+ | Ultra | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status` |
195
200
 
196
201
  `ultracode` (Claude dynamic workflows) is a `session_start` option, not a separate tool: set
197
202
  `ultracode: true` to have Claude orchestrate a JS workflow and fan out to subagents per task.
@@ -208,6 +213,37 @@ engine mid-session.
208
213
 
209
214
  For setup, the dsh YAML block, and the cancellation/permission limits: see [references/acp.md](references/acp.md)
210
215
 
216
+ ## Durable workflows
217
+
218
+ `workflow_start` runs a declarative graph of `agent` / `fanout` / `council` / `verifier` /
219
+ `human_gate` / `router` / `subflow` nodes. Every state transition is checkpointed to
220
+ `~/.claw-orchestrator/wf/<runId>/`, so a run survives a process restart and `workflow_resume`
221
+ picks it up at the node boundary — nodes already succeeded are not re-run, and the one that
222
+ was in flight is retried because a half-finished node left no result to trust.
223
+
224
+ Three built-in templates: `solve` (triage → implement → verify → repair-until-green →
225
+ review), `council`, and `fanout`. Retry, per-node timeout, cancel, steer, human gates, and
226
+ bounded loops come from the kernel rather than from each mode's own state machine.
227
+
228
+ For node shapes, routing conditions, and the control surfaces:
229
+ see [references/workflow.md](references/workflow.md)
230
+
231
+ ## Verification — does the work actually pass?
232
+
233
+ Hand a run an **acceptance contract** and the runtime checks the result itself: shell commands
234
+ gated on exit code, HTTP probes, headless-Chrome screenshots, diff policy, file assertions. A
235
+ run carrying a contract cannot reach `completed` unless every required check passes; a run
236
+ without one completes as `unverified`, which says nothing checked it rather than claiming
237
+ success. Every attempt writes an evidence bundle — verdict, per-check output tails, the patch
238
+ (created files included), screenshots — readable later with `clawo verify <runId>`.
239
+
240
+ Contracts come from the caller or a mode default, never from agent output: an agent that
241
+ writes its own acceptance criteria is grading itself. UltraApp ships one on by default;
242
+ `verify_run` checks work that did not come through a workflow at all.
243
+
244
+ For the check types, per-mode defaults, and what the screenshot gate does and does not claim:
245
+ see [references/verification.md](references/verification.md)
246
+
211
247
  ## Cost & spend caps
212
248
 
213
249
  Every turn on every engine is appended to a durable ledger at
@@ -221,6 +257,11 @@ sessions are gone.
221
257
  holds on Codex, Cursor, agy, OpenCode and custom engines too — not just Claude Code. Once
222
258
  cumulative spend reaches the cap, further sends are refused before the engine is spawned.
223
259
 
260
+ Rows carry two different judgements and keep them apart: `ok` is the engine's terminal verdict
261
+ on its own turn, `verified` is whether an acceptance contract passed. A row with no `verified`
262
+ at all means no contract was declared — not that it failed. `clawo runs --verified` /
263
+ `--refuted` filter on it.
264
+
224
265
  For the row schema, the query surfaces, and which engines report real token usage versus
225
266
  estimating it: see [references/observability.md](references/observability.md)
226
267
 
@@ -231,5 +272,5 @@ Each engine requires its own auth before use:
231
272
  - **Claude**: `claude /login` or `ANTHROPIC_API_KEY`
232
273
  - **Codex**: `codex login` or `OPENAI_API_KEY`
233
274
  - **Antigravity**: run `agy` once and complete the Google OAuth login
234
- - **Cursor**: `agent login` or `CURSOR_API_KEY`
275
+ - **Grok**: run `grok` once and sign in (grok.com account or `XAI_API_KEY`)
235
276
  - **OpenCode**: `opencode auth login` (provider-agnostic; use `provider/model` form for `model`)
@@ -28,11 +28,11 @@ Implemented: `initialize`, `authenticate`, `session/new`, `session/prompt`,
28
28
 
29
29
  ## Configuration
30
30
 
31
- | Env var | Default | Meaning |
32
- |---|---|---|
33
- | `CLAWO_ACP_MODEL` | `claude-sonnet-4-6` | Model (and therefore engine) for a new session |
34
- | `CLAWO_ACP_PERMISSION` | `acceptEdits` | `plan` \| `acceptEdits` \| `bypassPermissions`; an unrecognised value is ignored with a warning |
35
- | `OPENCLAW_LOG_LEVEL` | `info` | Set `warn` to quieten the stderr channel |
31
+ | Env var | Default | Meaning |
32
+ | ---------------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
33
+ | `CLAWO_ACP_MODEL` | `claude-sonnet-4-6` | Model (and therefore engine) for a new session |
34
+ | `CLAWO_ACP_PERMISSION` | `acceptEdits` | `plan` \| `acceptEdits` \| `bypassPermissions`; an unrecognised value is ignored with a warning |
35
+ | `OPENCLAW_LOG_LEVEL` | `info` | Set `warn` to quieten the stderr channel |
36
36
 
37
37
  ## Session modes
38
38
 
@@ -41,24 +41,24 @@ a client surfaces a mode picker is up to the client** — the VS Code ACP extens
41
41
  (0.2.0, measured) renders config options and not modes. So every mode also has a
42
42
  slash command, advertised through `available_commands_update` when the session opens:
43
43
 
44
- | Command | Effect |
45
- |---|---|
44
+ | Command | Effect |
45
+ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
46
46
  | `/single` · `/council` · `/ultraplan` · `/ultrareview` | Switch mode. Text after the command runs in that mode straight away — `/council fix the failing test` is one step, not three. |
47
47
 
48
48
  That is the only way to reach a mode in a client that does not draw the picker.
49
49
 
50
- | Mode | What a turn does |
51
- |---|---|
52
- | `single` | One engine answers. Text streams as `agent_message_chunk`; tool use becomes `tool_call`. |
53
- | `council` | Several engines debate in isolated git worktrees. Each agent becomes a `tool_call` the client can collapse, each round emits a `plan`, and the synthesis arrives as text. |
54
- | `ultraplan` | Long-horizon planning pass. Result arrives as a `plan` update and as text. |
55
- | `ultrareview` | Parallel reviewers sweep the working tree; findings arrive the same way. |
50
+ | Mode | What a turn does |
51
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | `single` | One engine answers. Text streams as `agent_message_chunk`; tool use becomes `tool_call`. |
53
+ | `council` | Several engines debate in isolated git worktrees. Each agent becomes a `tool_call` the client can collapse, each round emits a `plan`, and the synthesis arrives as text. |
54
+ | `ultraplan` | Long-horizon planning pass. Result arrives as a `plan` update and as text. |
55
+ | `ultrareview` | Parallel reviewers sweep the working tree; findings arrive the same way. |
56
56
 
57
57
  ### Council
58
58
 
59
59
  Council defaults here are deliberately far below the library's own — that config is
60
60
  tuned for a long unattended run (three agents, fifteen rounds, one session per agent
61
- *per round*), which is the wrong shape behind an editor turn. The ACP path uses **two
61
+ _per round_), which is the wrong shape behind an editor turn. The ACP path uses **two
62
62
  agents on distinct engines (Claude and Codex) and three rounds**.
63
63
 
64
64
  It still is not fast: a measured two-round run on a one-line bug took **~9 minutes**.
@@ -76,9 +76,9 @@ surface as an `invalid params` error naming the reason.
76
76
  **Consensus parks the run rather than finishing it.** The turn ends at the gate, and
77
77
  the decision becomes a slash command, advertised through `available_commands_update`:
78
78
 
79
- | Command | Effect |
80
- |---|---|
81
- | `/council_accept` | Merge the winning agent's worktree. |
79
+ | Command | Effect |
80
+ | ---------------------------- | ----------------------------------------------------------- |
81
+ | `/council_accept` | Merge the winning agent's worktree. |
82
82
  | `/council_reject <feedback>` | Discard the result; the text is passed through as feedback. |
83
83
 
84
84
  Any other prompt while a council is parked is refused, so a second run cannot start
@@ -94,7 +94,7 @@ cancelling one abandons the poll rather than stopping the work.
94
94
 
95
95
  `session/new` also returns a `category: "model"` config option whose values are
96
96
  **grouped by engine**, built from the shared registry in `src/models.ts`. One
97
- dropdown holds Claude, Codex and Cursor models at once. Changing it restarts the
97
+ dropdown holds Claude, Codex and Grok models at once. Changing it restarts the
98
98
  underlying session on the new engine; the ACP session id is unaffected.
99
99
 
100
100
  Two engines are absent for different reasons: