@enderfga/claw-orchestrator 7.6.2 → 7.8.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 (33) hide show
  1. package/README.md +4 -4
  2. package/dist/src/acp-server.d.ts +28 -6
  3. package/dist/src/acp-server.js +108 -19
  4. package/dist/src/acp-server.js.map +1 -1
  5. package/dist/src/index.js +10 -0
  6. package/dist/src/index.js.map +1 -1
  7. package/dist/src/kernel/nodes/autoloop.d.ts +2 -0
  8. package/dist/src/kernel/nodes/autoloop.js +5 -0
  9. package/dist/src/kernel/nodes/autoloop.js.map +1 -1
  10. package/dist/src/persistent-codex-app-session.d.ts +2 -0
  11. package/dist/src/persistent-codex-app-session.js +11 -0
  12. package/dist/src/persistent-codex-app-session.js.map +1 -1
  13. package/dist/src/persistent-codex-session.d.ts +9 -0
  14. package/dist/src/persistent-codex-session.js +24 -0
  15. package/dist/src/persistent-codex-session.js.map +1 -1
  16. package/dist/src/persistent-session.d.ts +2 -0
  17. package/dist/src/persistent-session.js +26 -1
  18. package/dist/src/persistent-session.js.map +1 -1
  19. package/dist/src/run-ledger.d.ts +6 -0
  20. package/dist/src/run-ledger.js.map +1 -1
  21. package/dist/src/session-manager.d.ts +13 -0
  22. package/dist/src/session-manager.js +164 -47
  23. package/dist/src/session-manager.js.map +1 -1
  24. package/dist/src/types.d.ts +37 -0
  25. package/package.json +1 -1
  26. package/skills/references/acp.md +36 -11
  27. package/skills/references/autoloop.md +7 -1
  28. package/skills/references/claude-cli-tracking.md +3 -1
  29. package/skills/references/mcp.md +19 -0
  30. package/skills/references/multi-engine.md +8 -3
  31. package/skills/references/observability.md +2 -1
  32. package/skills/references/sessions.md +11 -0
  33. package/skills/references/tools.md +6 -2
package/skills/references/acp.md CHANGED
@@ -27,8 +27,9 @@ Built against **stable ACP v1** (`@agentclientprotocol/sdk`, pinned `1.3.0`).
27
27
  ACP v2 exists but is a published draft whose README warns the wire protocol "may
28
28
  change incompatibly in any SDK release", so it is deliberately not used.
29
29
 
30
- Implemented: `initialize`, `authenticate`, `session/new`, `session/prompt`,
31
- `session/set_mode`, `session/set_config_option`, `session/cancel`.
30
+ Implemented: `initialize`, `authenticate`, `session/new`, `session/resume`,
31
+ `session/list`, `session/prompt`, `session/set_mode`, `session/set_config_option`,
32
+ `session/cancel`.
32
33
 
33
34
  ## Configuration
34
35
 
@@ -99,8 +100,9 @@ cancelling one abandons the poll rather than stopping the work.
99
100
  `session/new` also returns a `category: "model"` config option whose values are
100
101
  **grouped by engine**, built from the shared registry in `src/models.ts`. One
101
102
  dropdown holds four engine groups at once: Claude Code, Codex, Antigravity and
102
- Grok Build. Changing it restarts the underlying session on the new engine; the
103
- ACP session id is unaffected.
103
+ Grok Build. Changing it restarts the underlying session; the ACP session id is
104
+ unaffected. A model on the same engine continues the conversation; a model on
105
+ another engine starts a new one, since one engine cannot read another's.
104
106
 
105
107
  Other engines are absent for different reasons:
106
108
 
@@ -112,6 +114,31 @@ Other engines are absent for different reasons:
112
114
  straight through, so there is nothing in the registry to enumerate. An opencode
113
115
  session is reachable by naming the model, just not by picking it from this list.
114
116
 
117
+ ## Generated images
118
+
119
+ When the engine generates an image in a turn (Codex does, when asked for one), the agent names the
120
+ file's path in a text chunk and then sends the image itself as an `image` content block, so a client
121
+ that renders images shows it and one that does not still gets the path. Files over 8 MB are named
122
+ only.
123
+
124
+ ## Resuming sessions
125
+
126
+ Sessions outlive the agent process. `initialize` advertises
127
+ `sessionCapabilities.resume` and `sessionCapabilities.list`:
128
+
129
+ - **`session/list`** returns the sessions this agent created, newest first, with
130
+ `sessionId`, `cwd` and `updatedAt`; pass `cwd` to see one project's.
131
+ - **`session/resume`** reattaches a session by id after the editor or the agent
132
+ restarts, on the engine and model it was using, and the next prompt continues
133
+ its conversation. The `cwd` must be the one the session was created in — the
134
+ engines keep conversations per directory.
135
+
136
+ `session/load` is not offered (`loadSession: false`): it requires replaying the
137
+ earlier conversation to the client, and no engine returns its history in a form
138
+ that can be replayed. A resumed session therefore opens with an empty view in the
139
+ client while the engine still remembers it. Sessions are kept for 7 days after
140
+ their last use.
141
+
115
142
  ## Permission
116
143
 
117
144
  ACP can ask the user mid-turn through `session/request_permission`. This agent does
@@ -125,13 +152,11 @@ saying so, so the choice is a session config option instead — which also suits
125
152
  ## Cancellation
126
153
 
127
154
  `session/cancel` settles the in-flight prompt as `cancelled` immediately, then tears
128
- the underlying session down and recreates it.
129
-
130
- A cancel with **nothing in flight does nothing**. The teardown drops the engine's
131
- native conversation id — codex, codex-app, agy, cursor and opencode all capture
132
- theirs mid-turn — so running it on an idle session would fork the history
133
- silently: the client keeps the same ACP session id while the next prompt opens a
134
- fresh engine thread.
155
+ the underlying session down and recreates it. The recreated session resumes the
156
+ engine's conversation from the saved resume handle. Codex, codex-app, agy, cursor and
157
+ opencode report theirs during a turn, so a cancel in the very first turn of a session
158
+ can still start a fresh conversation. A cancel with **nothing in flight does
159
+ nothing**.
135
160
 
136
161
  The session layer has **no mid-turn cancel** — `stopSession()` is the only lever and
137
162
  it destroys the session rather than pausing the turn. So the ACP turn returns
package/skills/references/autoloop.md CHANGED
@@ -124,6 +124,8 @@ A genuine per-agent send timeout is recoverable but is never retried
124
124
  automatically: the underlying agent may still complete and cause side effects.
125
125
  The runner pauses with an `awaiting_resume` reason and records the immutable
126
126
  logical dispatch as `pending_dispatch`, including its stable `dispatch_id`.
127
+ Live runner state transitions are checkpointed, so a non-owning
128
+ `autoloop_status` shows both a recoverable send-timeout pause and an operator pause.
127
129
  Resume may supply only a finite, in-range `send_timeout_ms` that is strictly
128
130
  larger than the latest effective value, together with the matching
129
131
  `pending_dispatch_id` when a dispatch is pending. Legacy runs start comparison
@@ -456,7 +458,11 @@ Resume is explicit. `POST /autoloop/<id>/resume` (or
456
458
  `SessionManager.autoloopResume()`) restarts a run from its stored spec.
457
459
  Custom-engine configs are the one thing the spec does not carry (they can hold
458
460
  secrets), so a resume must be given them again. Cancelling a run stops all three
459
- agents, the same as `autoloop_stop`.
461
+ agents, the same as `autoloop_stop`. If the highest committed Coder iteration
462
+ has ledger artifacts and no `verdict.json`, and `HEAD` still names that iter,
463
+ resume delivers one `review_request` for it and the dispatcher persists the
464
+ Reviewer verdict; it does not send a new Coder directive. An in-flight send is
465
+ still not retried, and there is no message outbox.
460
466
 
461
467
  ## Known limitations
462
468
 
package/skills/references/claude-cli-tracking.md CHANGED
@@ -2,12 +2,14 @@
2
2
 
3
3
  This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated. Recent rows also record the other engines' versions checked in the same sync.
4
4
 
5
- ## Currently tracked: **Claude Code CLI 2.1.289** (as of 2026-10-05, plugin v7.6.2)
5
+ ## Currently tracked: **Claude Code CLI 2.1.292** (as of 2026-10-07, plugin v7.8.0)
6
6
 
7
7
  ## Sync history
8
8
 
9
9
  | Plugin Version | Claude CLI Version | Date | Notable integrations |
10
10
  | ------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | v7.8.0 | 2.1.292 | 2026-10-07 | CC 2.1.291→2.1.292, agy 1.3.0→1.3.1, OpenCode 1.18.34→1.18.35; Codex 0.160.1 and grok 1.0.46 unchanged. No flag surface changed. Integrated: Codex image generation surfaced as `images` on the send result (`codex exec` from `$CODEX_HOME/generated_images/<thread>/`, `codex-app` from the `imageGeneration` item). Read, no change needed: CC 2.1.292 negotiates MCP protocol 2026-07-28 with local stdio servers by default — `clawo-mcp` answers with 2025-11-25 and connects with no delay (measured against `MCP_PROTOCOL_NEGOTIATION=legacy`). |
12
+ | v7.7.0 | 2.1.291 | 2026-10-07 | CC 2.1.289→2.1.291, Codex 0.160.0→0.160.1, agy 1.2.17→1.3.0; grok 1.0.46 and OpenCode 1.18.34 unchanged. No flag surface changed. Integrated: `--chrome` behind a `chrome` session option (2.1.290 stopped project settings from turning Claude in Chrome on, so the flag is the way in); `system/model_refusal_fallback` recorded per turn in the ledger. Read, no change needed: Codex's `computer_use` feature is the ChatGPT desktop app's Computer Use plugin, not a tool in `codex exec`, which reports none; agy 1.3.0 is interactive-view changes. |
11
13
  | v7.6.2 | 2.1.289 | 2026-10-05 | CC 2.1.286→2.1.289, Codex 0.159.3→0.160.0, agy 1.2.14→1.2.17, grok 1.0.44→1.0.46; OpenCode 1.18.34 unchanged. No flag surface changed, no wrapper change. Read, no change needed: CC 2.1.288 limits background-command time only in unattended (`-p`) sessions, which these already are; agy 1.2.16 fixes `-p` runs exiting before the agent answers a finished background command, consistent with the 7.5.6 deadline handling. |
12
14
  | v7.6.1 | 2.1.286 | 2026-10-01 | CC 2.1.284→2.1.286, Codex 0.159.0→0.159.3, agy 1.2.13→1.2.14, OpenCode 1.18.33→1.18.34; grok 1.0.44 unchanged. No flag surface changed. Integrated: `gpt-6.1-sol` registered ($2/$10, cache reads at 5% of input); a Codex session with no model is priced as the model Codex reports it ran rather than `gpt-5.5`. Read, no change needed: CC 2.1.285 starts `-p` sessions on third-party providers or with telemetry off in auto mode when no permission mode is set (this wrapper always passes `--permission-mode`); CC 2.1.286 resume fixes after parallel tool calls. Gemini 4 is not yet released: no API id, price or `agy models` entry. |
13
15
  | v7.6.0 | 2.1.284 | 2026-09-29 | CC 2.1.283→2.1.284, Codex 0.157.1→0.159.0, agy 1.2.11→1.2.13, grok 1.0.41→1.0.44, OpenCode 1.18.32→1.18.33. No flag surface changed. Integrated: Claude Sonnet 5.5 registered and the `sonnet` alias moved to `claude-sonnet-5-5` (the CLI resolves `--model sonnet` to it); priced at $2/$10 per Mtok with $0.20 cache reads, the same as Sonnet 5. Read, no change needed: CC 2.1.284 makes Ultracode its own `/effort` toggle that no longer forces xhigh (the `ultracode` settings key this wrapper passes already composes with a separate effort) and starts interactive sessions in auto mode (headless sessions are unaffected); Codex 0.158–0.159 TUI, sandbox and approval changes; agy 1.2.12–1.2.13 rate-limit handling; OpenCode 1.18.33 Gemini effort defaults. |
package/skills/references/mcp.md CHANGED
@@ -8,6 +8,7 @@ This document covers:
8
8
  - [Host configuration](#host-configuration)
9
9
  - [Hermes Agent](#hermes-agent)
10
10
  - [Claude Desktop / Claude Code](#claude-desktop--claude-code)
11
+ - [Codex CLI](#codex-cli)
11
12
  - [Cursor](#cursor)
12
13
  - [Cline (VS Code)](#cline-vs-code)
13
14
  - [Continue](#continue)
@@ -116,6 +117,24 @@ Hermes prefixes tool names with `mcp_<server>_`. The model sees the prefixed nam
116
117
 
117
118
  For Claude Code (`~/.claude.json` or per-project `.mcp.json`), use the same shape under `mcpServers`.
118
119
 
120
+ ### Codex CLI
121
+
122
+ ```bash
123
+ codex mcp add clawo -- clawo-mcp
124
+ ```
125
+
126
+ or in `~/.codex/config.toml`:
127
+
128
+ ```toml
129
+ [mcp_servers.clawo]
130
+ command = "clawo-mcp"
131
+ ```
132
+
133
+ Codex then offers the tools in every local session — `codex exec`, the TUI and `codex app-server`. For a
134
+ one-off run without touching the config, pass `-c 'mcp_servers.clawo.command="clawo-mcp"'`. Each Codex
135
+ session starts its own `clawo-mcp` process, so the sessions one Codex session starts through it are not
136
+ visible from another.
137
+
119
138
  ### Cursor
120
139
 
121
140
  In Cursor settings → MCP, add a server. The config file is `~/.cursor/mcp.json`:
package/skills/references/multi-engine.md CHANGED
@@ -28,7 +28,7 @@ SessionManager
28
28
 
29
29
  ### Claude Code (`engine: 'claude'`)
30
30
 
31
- Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.289**.
31
+ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.292**.
32
32
 
33
33
  - Persistent multi-turn conversations
34
34
  - Real-time streaming (text, tool_use, tool_result, system events)
@@ -62,7 +62,7 @@ await manager.startSession({
62
62
 
63
63
  ### OpenAI Codex (`engine: 'codex'`)
64
64
 
65
- Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.160.0**.
65
+ Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.160.1**.
66
66
 
67
67
  - Non-interactive execution via `codex exec --sandbox workspace-write --skip-git-repo-check --json`
68
68
  - Real `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens). **These are cumulative over the thread, not per turn**, so they replace the session totals rather than being added to them; subtracting consecutive values gives one turn's prompt
@@ -83,6 +83,11 @@ Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested wi
83
83
  - Requires `codex` CLI >= 0.119 (for `exec resume`): `npm install -g @openai/codex`
84
84
  - The prompt is sent on stdin (`codex exec … -`), never on the command line.
85
85
  - **Windows:** the npm `.cmd` shim launches through `src/engine-spawn.ts` (cross-spawn), which escapes the remaining arguments for `cmd.exe`. Because the prompt is on stdin it arrives unchanged, newlines and quotes included. A timed-out turn ends the whole process tree (`taskkill /T /F`), not only `cmd.exe`.
86
+ - **Image generation**: ask for an image and Codex generates it with its built-in tool and saves it under
87
+ `$CODEX_HOME/generated_images/<thread_id>/`. `codex exec --json` reports no event for it, so the
88
+ adapter lists the files the turn added there and returns them as `images` on the send result
89
+ (`codex-app` reads them from the `imageGeneration` item, with the revised prompt). It uses the
90
+ account's image-generation allowance.
86
91
  - **Does not support `/goal`** — for that, use `engine: 'codex-app'` below
87
92
 
88
93
  ```typescript
@@ -128,7 +133,7 @@ await manager.startSession({
128
133
 
129
134
  Wraps Google's **Antigravity CLI** (`agy`) — the successor to Gemini CLI (consumer
130
135
  Gemini CLI tiers stopped serving 2026-06-18). Each `send()` spawns a new process
131
- in print mode. Tested with `agy` **1.2.17**.
136
+ in print mode. Tested with `agy` **1.3.1**.
132
137
 
133
138
  - One-shot execution per message (no persistent subprocess)
134
139
  - **Structured output and real usage** — `--output-format stream-json` emits an
package/skills/references/observability.md CHANGED
@@ -30,7 +30,7 @@ every engine passes through, not only through Claude Code's `--max-budget-usd`.
30
30
  | `ts` | ISO timestamp of turn completion |
31
31
  | `session` | SessionManager session name |
32
32
  | `engine` | `claude` / `codex` / `codex-app` / `grok` / `opencode` / `agy` / `cursor` (legacy) / `custom` |
33
- | `model` | Configured model, or the engine's own reported model when none was set (Claude Code: the model named in its `init` event). Absent when neither is known |
33
+ | `model` | Configured model, or the engine's own reported model when none was set (Claude Code: the model named in its `init` event). A configured alias such as `opus[1m]` is recorded as the model the engine reports it resolved to. Absent when neither is known |
34
34
  | `cwd` | Working directory the turn ran in |
35
35
  | `turn` | 1-based index of the send within the session, counted by the process that recorded it |
36
36
  | `tokensIn` / `tokensOut` / `cachedTokens` | **Per-turn deltas**, not session totals |
@@ -40,6 +40,7 @@ every engine passes through, not only through Claude Code's `--max-budget-usd`.
40
40
  | `toolCalls` / `toolErrors` | Per-turn deltas |
41
41
  | `ok` | `false` for a turn that threw, or that the session's own `turnsSucceeded` counter did not count (see `sessions.md`). Falls back to "nothing was thrown" when the counter cannot be read |
42
42
  | `error` | Failure text, truncated to 500 chars. Absent when the turn resolved but the engine did not count it as succeeded (an interrupted or non-SUCCESS turn), so a failed row does not always carry one |
43
+ | `refusalFallback` | `{ from, to, category? }` when the model refused and the engine re-ran the turn on another model (Claude Code’s refusal fallback, for example Opus 5.5 to an older Opus on a `cyber` refusal). Absent otherwise |
43
44
  | `parent` | council / fanout / autoloop / workflow run id, when the turn belongs to one |
44
45
 
45
46
  Deltas rather than totals means summing a query window gives that window's spend
package/skills/references/sessions.md CHANGED
@@ -190,6 +190,17 @@ tokens the session has been billed for in total, which only ever grows.
190
190
  (`codex`, `agy`, `grok`, `opencode`); those sessions log a warning the first
191
191
  time it is called.
192
192
 
193
+ A long-lived session can compact itself: start it with `autoCompactPercent`
194
+ (1–99, off by default) and, before each send, the session is compacted first
195
+ if `contextPercent` has reached that value. Every call in a turn re-reads the
196
+ whole context from cache, so cost grows with context size; compacting earlier
197
+ trades detail of older turns for cheaper ones. The setting survives a restart
198
+ of the server, and a failed compaction never costs the send.
199
+
200
+ ```typescript
201
+ await manager.startSession({ name: 'assistant', cwd: '/srv/bot', autoCompactPercent: 85 });
202
+ ```
203
+
193
204
  `stats.turns` and `stats.turnsSucceeded` are the same kind of distinction.
194
205
  `turns` counts turns that reached the engine, whatever their outcome, including
195
206
  the ones that then failed. `turnsSucceeded` counts only the ones the engine
package/skills/references/tools.md CHANGED
@@ -20,6 +20,7 @@ Start a persistent coding session with full CLI flag support.
20
20
  | `disallowedTools` | string[] | Tools to deny |
21
21
  | `maxTurns` | number | Max agent loop turns |
22
22
  | `maxBudgetUsd` | number | Max API spend (USD). Enforced by the runtime on every engine: once the session's cumulative cost reaches the cap, further sends are refused before the engine is spawned. See [observability.md](observability.md) for the accuracy caveat on engines that estimate token counts. |
23
+ | `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. |
23
24
  | `systemPrompt` | string | Replace system prompt |
24
25
  | `appendSystemPrompt` | string | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
25
26
  | `agents` | object | Custom sub-agents JSON |
@@ -43,6 +44,7 @@ Start a persistent coding session with full CLI flag support.
43
44
  | `crossSessionInbound` | string | `accept` / `hold` / `refuse` — policy for peer messages from other Claude Code sessions on this machine (Claude engine). Delivered as a settings key; there is no CLI flag. Without it the CLI holds messages whose two sides run different permission modes, which is the usual orchestrated-session-to-human-terminal case |
44
45
  | `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
45
46
  | `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 |
47
+ | `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 |
46
48
  | `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use). When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout. |
47
49
  | `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
48
50
  | `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
@@ -71,11 +73,13 @@ Send a message and get the response.
71
73
  | `timeout` | number | | Timeout in ms (default 300000) |
72
74
  | `stream` | boolean | | Collect streaming chunks in result |
73
75
 
74
- Returns `{ ok, output, sessionId, error?, permissionDenials? }`. `permissionDenials` lists the tool
76
+ Returns `{ ok, output, sessionId, error?, permissionDenials?, images? }`. `permissionDenials` lists the tool
75
77
  calls the engine refused during the turn — `[{ toolName, toolUseId?, input? }]` — and is present only
76
78
  when there was at least one. Check it even when `error` is absent: a turn whose tool calls were all
77
79
  denied still ends as a success. See [sessions.md](./sessions.md) on what "succeeded" does and does
78
- not mean.
80
+ not mean. `images` lists the images the engine generated in this turn as `{ path, revisedPrompt? }`,
81
+ with `path` a file on the machine running the orchestrator; Codex (`codex` and `codex-app`) generates
82
+ them when asked for an image.
79
83
 
80
84
  ### `session_handoff`
81
85