@enderfga/claw-orchestrator 4.14.1 → 5.1.0

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAA2B,UAAU,EAAE,CAAC;AAYlE,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAGvH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA8B,EAC9B,YAAiC;IAEjC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,WAAW,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,2EAA2E;YAC3E,gEAAgE;YAChE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,CAAC;QAC3C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAA2B,UAAU,EAAE,CAAC;AAYlE,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,WAAW;IACX,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,MAAM;IACN,UAAU;IACV,QAAQ;CACA,CAAC;AAGX;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA8B,EAC9B,YAAiC;IAEjC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,WAAW,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,2EAA2E;YAC3E,gEAAgE;YAChE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,CAAC;QAC3C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "4.14.1",
+  "version": "5.1.0",
   "description": "Claw Orchestrator — run Claude Code, Codex, Gemini, Cursor Agent, OpenCode and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
   "type": "module",
   "main": "./dist/src/index.js",

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-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".
+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 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", "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".
 metadata:
   {
     "openclaw":
@@ -36,7 +36,7 @@ metadata:
 
 # Claw Orchestrator Skill
 
-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.
+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 69 tools.
 
 ## Engine Quick Reference
 
@@ -45,7 +45,7 @@ Claw Orchestrator — persistent multi-engine coding session manager for claw-st
 | `claude` | `claude` | Persistent subprocess | Multi-turn, complex tasks |
 | `codex` | `codex exec` | Per-message spawn | One-shot execution |
 | `agy` | `agy -p` | Per-message spawn | Google Antigravity; plain-text, auto conversation resume |
-| `cursor` | `agent -p` | Per-message spawn | One-shot execution |
+| `grok` | `grok -p` | Per-message spawn | xAI Grok Build; engine-reported cost, resumable session |
 | `opencode` | `opencode run` | Per-message spawn | Provider-agnostic (`provider/model`) |
 
 ## Core Workflow
@@ -55,7 +55,7 @@ Claw Orchestrator — persistent multi-engine coding session manager for claw-st
 session_start({ name: "myproject", cwd: "/path/to/project", engine: "claude" })
 session_start({ name: "codex-task", cwd: "/path/to/project", engine: "codex" })
 session_start({ name: "agy-task", cwd: "/path/to/project", engine: "agy" })
-session_start({ name: "cursor-task", cwd: "/path/to/project", engine: "cursor" })
+session_start({ name: "grok-task", cwd: "/path/to/project", engine: "grok" })
 session_start({ name: "opencode-task", cwd: "/path/to/project", engine: "opencode", model: "anthropic/claude-sonnet-4" })
 
 // 2. Send messages
@@ -231,5 +231,5 @@ Each engine requires its own auth before use:
 - **Claude**: `claude /login` or `ANTHROPIC_API_KEY`
 - **Codex**: `codex login` or `OPENAI_API_KEY`
 - **Antigravity**: run `agy` once and complete the Google OAuth login
-- **Cursor**: `agent login` or `CURSOR_API_KEY`
+- **Grok**: run `grok` once and sign in (grok.com account or `XAI_API_KEY`)
 - **OpenCode**: `opencode auth login` (provider-agnostic; use `provider/model` form for `model`)

package/skills/references/acp.md

@@ -94,7 +94,7 @@ cancelling one abandons the poll rather than stopping the work.
 
 `session/new` also returns a `category: "model"` config option whose values are
 **grouped by engine**, built from the shared registry in `src/models.ts`. One
-dropdown holds Claude, Codex and Cursor models at once. Changing it restarts the
+dropdown holds Claude, Codex and Grok models at once. Changing it restarts the
 underlying session on the new engine; the ACP session id is unaffected.
 
 Two engines are absent for different reasons:

package/skills/references/autoloop.md

@@ -34,15 +34,17 @@ uses its own default model rather than receiving the Claude `opus` / `sonnet`
 defaults. Role instructions are included in-band for engines that do not expose a
 native system-prompt flag.
 
-Engines without native multi-turn conversation (Cursor, OpenCode, one-shot custom
-engines) spawn a fresh process per send, so the dispatcher replays that role's
-transcript in-band as a `<conversation_history>` block, oldest turns dropped past a
-character budget. Claude, Codex and Antigravity keep context themselves and get no
-replay.
+Engines without native multi-turn conversation (Gemini and one-shot custom engines)
+spawn a fresh process per send with nothing to resume, so the dispatcher replays that
+role's transcript in-band as a `<conversation_history>` block, oldest turns dropped
+past a character budget. Claude, Codex, Antigravity, Grok, OpenCode and Cursor each
+resume their own conversation by id and get no replay — see
+`engineHasNativeConversation` in `types.ts`, which is the single source of truth for
+this and is checked with a two-turn recall test per engine.
 
 The Planner runs read-only so strategy cannot turn into source edits, and that is
 enforced by the engine rather than requested politely: Claude uses plan mode,
-Antigravity and Cursor use their plan modes, and OpenCode gets a generated
+Antigravity uses its plan mode, and OpenCode gets a generated
 `clawo-readonly` agent that denies `edit`/`bash`/`external_directory` (its built-in
 `plan` agent is a user-overridable preset that denies neither, so a "read-only"
 session could otherwise still author files through a shell heredoc). A custom
@@ -176,7 +178,7 @@ Reviewer 70 %. Override per run via `compactThresholds`. A 30 s debounce
 prevents re-fire while post-compact stats settle. Events: `compact` is
 emitted on the dispatcher EventEmitter AND appended to `decisions.jsonl`.
 
-One-shot engines (`codex`, `agy`, `cursor`, `opencode`) cannot compact — their
+One-shot engines (`codex`, `agy`, `grok`, `opencode`) cannot compact — their
 CLIs expose no such command. The threshold is still meaningful there because
 `contextPercent` now tracks real occupancy, but crossing it cannot free space:
 the session emits a single warning on its log channel the first time compaction

package/skills/references/cli.md

@@ -42,7 +42,8 @@ The server exposes an OpenAI-compatible chat completions endpoint, enabling any
 **Model routing:** The `model` field auto-routes to the correct engine:
 - `claude-*`, `opus`, `sonnet`, `haiku` → Claude engine
 - `gpt-*` → Codex engine
-- `composer-*` → Cursor engine
+- `grok-*` → Grok engine
+- `composer-*` → Cursor engine (legacy)
 - `gemini-3.5-flash`, `gemini-3.1-pro`, `agy-*`, `agy/*` → Antigravity (`agy`) engine
 - other `gemini-*` → the legacy `gemini` engine (Gemini CLI is sunset; prefer `agy`)
 
@@ -61,7 +62,7 @@ clawo session-start [name] [options]
 | Flag | Description |
 |------|-------------|
 | `-d, --cwd <dir>` | Working directory |
-| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `cursor`, `opencode`, or `custom` |
+| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `grok`, `opencode`, or `custom` |
 | `-m, --model <model>` | Model name or alias |
 | `--permission-mode <mode>` | `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk` |
 | `--effort <level>` | `low`, `medium`, `high`, `max`, `auto` |

package/skills/references/getting-started.md

@@ -23,7 +23,7 @@ openclaw plugins install @enderfga/claw-orchestrator --dangerously-force-unsafe-
 openclaw gateway restart
 ```
 
-> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Antigravity / Cursor Agent / OpenCode CLI subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
+> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Antigravity / Grok Build / OpenCode CLI subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
 
 Agents automatically get access to all session, council, and management tools.
 

package/skills/references/multi-engine.md

@@ -14,7 +14,9 @@ SessionManager
 │   └── Wraps: codex app-server --listen stdio:// (long-running JSON-RPC; required for /goal)
 ├── engine: 'agy'       → PersistentAgySession
 │   └── Wraps: agy -p (Google Antigravity CLI, per-message spawning, stream-json output)
-├── engine: 'cursor'    → PersistentCursorSession
+├── engine: 'grok'      → PersistentGrokSession
+│   └── Wraps: grok -p --output-format json (xAI Grok Build, per-message spawning)
+├── engine: 'cursor'    → PersistentCursorSession (legacy)
 │   └── Wraps: agent -p --force --trust --output-format stream-json (per-message spawning)
 ├── engine: 'opencode'  → PersistentOpencodeSession
 │   └── Wraps: opencode run --format json (per-message spawning)
@@ -173,9 +175,59 @@ await manager.startSession({
 > multi-model **proxy** still talks to the Gemini **API**; that is a different
 > subsystem and is unaffected.)
 
-### Cursor Agent (`engine: 'cursor'`)
+### Grok Build (`engine: 'grok'`)
+
+Wraps xAI's **Grok Build** CLI. Each `send()` spawns `grok -p <msg> --output-format json`, which
+prints a single JSON object and exits. Verified against `grok` **1.0.5**.
+
+- **Cost comes from the engine, not from our price table.** The result object carries
+  `total_cost_usd`, and the wrapper writes it straight into the session's spend. Every other engine
+  here multiplies tokens by a rate in `models.ts` — the metadata most prone to going stale — so on
+  this engine the run ledger and the `maxBudgetUsd` gate both read what xAI actually charged.
+  `grok-4.6` is still registered, for its context window and an indicative breakdown; its two price
+  tiers ($2/$0.50/$6 under a 200K prompt, $4/$1/$12 at or above, charged across the whole request)
+  therefore never have to be modelled here.
+- **Real conversation continuity**: the `sessionId` from turn 1 is replayed as `--resume <id>`.
+  `--continue` is deliberately not used — it means "the most recent session for this cwd", which
+  collides between concurrent sessions. Confirmed with a two-turn recall test, not inferred.
+- Real token counts from `usage` (`input_tokens`, `output_tokens`, `cache_read_input_tokens`).
+  These are **per-turn**, not cumulative over the thread — checked by resuming and reading turn 2,
+  because the same-looking field on codex is a running total.
+- Permission modes pass straight through: grok's `--permission-mode` takes the same vocabulary we
+  use. The one exception is our `manual`, which grok spells `default`.
+- Reasoning effort maps to `--effort`; grok accepts `low|medium|high`, so `max` and `xhigh` clamp.
+- **`sandboxMode: 'read-only'` is refused, not approximated.** grok has `--permission-mode plan` and
+  `--deny` rules, but plan mode alone is model-cooperative — the shape that let an adversarial
+  prompt write through Cursor's plan mode — and the deny rules have not been through the
+  write × shell × subagent × resumed-turn matrix this project requires before claiming a boundary.
+  A read-only grok session throws rather than running writable under a read-only label.
+- Binary: `grok` (set `GROK_BIN` to override). Not `agent`: xAI's installer claims that name too,
+  and so did Cursor's.
+- Requires Grok Build: see `x.ai/cli`.
 
-Wraps the Cursor Agent CLI (`agent`) with `--print --output-format stream-json`. Write-enabled sessions use `--force`. Each `send()` spawns a new process.
+```typescript
+await manager.startSession({
+  name: 'grok-task',
+  engine: 'grok',
+  model: 'grok-4.6',
+  cwd: '/project',
+});
+```
+
+### Cursor Agent (`engine: 'cursor'`) — legacy
+
+> **Legacy: `engine: 'cursor'`.** Superseded in this lineup by Grok Build (`engine: 'grok'`).
+> The `cursor` engine still exists and still works — existing callers are not broken — but it is
+> no longer a documented option, is not version-tracked, and gets no new work.
+>
+> Note what this is and is not: Cursor itself is **not** discontinued. Anysphere was acquired by
+> SpaceX (closed 2026-08-15) and folded into the SpaceXAI team, and the CLI has shipped since. Two
+> practical things pushed it out of the tracked set. Cursor never reports which model actually ran
+> — its `system` init event says `"model": "Auto"` — so a router that spans Claude, GPT and Grok
+> leaves every cost row attributed to a hardcoded proxy rate. And xAI's Grok installer now claims
+> the bare `agent` name, so the binary that name resolves to depends on install order.
+
+Wraps the Cursor Agent CLI with `--print --output-format stream-json`. Write-enabled sessions use `--force`. Each `send()` spawns a new process.
 
 - Conversation continuity: the chat id from the first turn's `system` event is captured and passed back as `--resume <chatId>` on later sends, so the model sees prior turns. `--continue` is deliberately not used: it resumes "the latest chat", which collides between concurrent sessions.
 - One-shot execution per message (no persistent subprocess)
@@ -185,7 +237,9 @@ Wraps the Cursor Agent CLI (`agent`) with `--print --output-format stream-json`.
 - `--trust` auto-trusts the workspace without prompting
 - Cursor uses its own model routing (e.g., `sonnet-4`, `gpt-5`, `auto`)
 - Requires Cursor Agent CLI: `curl https://cursor.com/install -fsSL | bash`
-- Binary: `agent` (set `CURSOR_BIN` env var to override)
+- Binary: `cursor-agent` (set `CURSOR_BIN` env var to override). The generic `agent` name is
+  deliberately not used: xAI's Grok installer symlinks `agent` to its own binary, which rejects
+  `--force`/`--trust`/`--workspace` and fails the turn with "unexpected argument"
 
 ```typescript
 await manager.startSession({
@@ -263,6 +317,10 @@ interface ISession {
 }
 ```
 
+`SessionStats` requires `turnsSucceeded` as well as `turns`, so an engine that
+implements this interface has to say which of its turns succeeded — the exit code
+is not the answer on every engine. See "Stats & Monitoring" in `sessions.md`.
+
 ## Team Tools Across Engines
 
 Team tools (`team_list`, `team_send`) operate on the same virtual-team layer for **every** engine: the "team" is the set of all active sessions managed by SessionManager.

package/skills/references/observability.md

@@ -34,7 +34,7 @@ every engine passes through.
 |---|---|
 | `ts` | ISO timestamp of turn completion |
 | `session` | SessionManager session name |
-| `engine` | `claude` / `codex` / `codex-app` / `cursor` / `opencode` / `agy` / `custom` |
+| `engine` | `claude` / `codex` / `codex-app` / `grok` / `opencode` / `agy` / `custom` |
 | `model` | Configured model, or the engine's own reported model when none was set |
 | `cwd` | Working directory the turn ran in |
 | `turn` | 1-based turn index within the session |
@@ -43,8 +43,8 @@ every engine passes through.
 | `tokensEstimated` | `true` when the counts came from `estimateTokens()` (see below) |
 | `durationMs` | Wall-clock for the turn |
 | `toolCalls` / `toolErrors` | Per-turn deltas |
-| `ok` | `false` for a turn that threw or reported `is_error` |
-| `error` | Failure text, truncated to 500 chars |
+| `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 |
+| `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 |
 | `parent` | council id / fanout id / autoloop run id, when the turn belongs to one |
 
 Deltas rather than totals means summing a query window gives that window's spend
@@ -116,7 +116,8 @@ flagged `tokensEstimated: true`; the CLI marks those costs with a trailing `~`.
 | `claude` | Engine-reported |
 | `codex` | Engine-reported |
 | `codex-app` | Engine-reported |
-| `cursor` | Engine-reported when the stream carries `usage`, else estimated |
+| `grok` | Engine-reported — and so is the **cost**: this engine reports `total_cost_usd`, which the wrapper passes through instead of pricing tokens from the registry, so registry drift cannot affect a grok row |
+| `cursor` (legacy) | Engine-reported when the stream carries `usage`, else estimated |
 | `opencode` | Engine-reported when the run JSON carries `tokens`, else estimated |
 | `agy` | Engine-reported when the result event carries usage, else estimated |
 | `custom` | Depends on the CLI; estimated when it emits no usage |

package/skills/references/openai-compat.md

@@ -2,7 +2,7 @@
 
 > **Cost warning**: This bridge routes requests through the Claude Code CLI, which uses your Claude Max subscription's **extra usage** quota. When OpenClaw's agent loop sends its system prompt (with distinctive tool definitions and agent instructions), Anthropic's backend recognizes this as programmatic/agent traffic and bills it against extra usage — **not** the included allowance. This is by design: the bridge does NOT bypass Anthropic's billing or subscription enforcement. Using it as OpenClaw's primary model backend means every agent turn consumes extra usage credits at standard API rates ($15/M input, $75/M output for Opus). Monitor your usage at [claude.ai/settings/usage](https://claude.ai/settings/usage).
 
-The embedded server exposes a drop-in OpenAI-compatible endpoint so any client that speaks `/v1/chat/completions` can talk to a persistent Claude Code (or Codex / Antigravity / Cursor) session. The bridge is designed to serve **two kinds of clients as first-class citizens**:
+The embedded server exposes a drop-in OpenAI-compatible endpoint so any client that speaks `/v1/chat/completions` can talk to a persistent Claude Code (or Codex / Antigravity / Grok) session. The bridge is designed to serve **two kinds of clients as first-class citizens**:
 
 1. **Upstream agents** that maintain their own conversation state and forward only the latest user turn — OpenClaw's main agent loop, cron jobs, subagents, programmatic clients.
 2. **OpenAI-compatible webchat / labeling tools** that re-send the full transcript on every turn — ChatGPT-Next-Web, Open WebUI, LobeChat, data-labeling pipelines.
@@ -81,7 +81,7 @@ mechanism is used depends on whether the engine keeps the conversation itself.
 | Engine | Turn 1 | Later turns |
 |---|---|---|
 | `claude` | Schemas go into the session system prompt (`--system-prompt`) | Nothing injected — the system prompt persists |
-| `codex`, `codex-app`, `agy`, `opencode`, `cursor` | Full schema block prepended to the message | A short reminder of the calling convention, no schemas — but only once the conversation id has been captured; until then the full block is sent again |
+| `codex`, `codex-app`, `agy`, `opencode`, `grok` | Full schema block prepended to the message | A short reminder of the calling convention, no schemas — but only once the conversation id has been captured; until then the full block is sent again |
 | `gemini`, one-shot `custom` | Full schema block prepended to the message | Full schema block again — these have no resume surface, so nothing persists between sends |
 
 The middle row is the one worth understanding. Those engines resume a conversation by id, so
@@ -148,7 +148,8 @@ Sample response:
       "model": "claude-opus-4-6",
       "cwd": "/home/user/projects",
       "created": "2026-04-09T03:12:18.441Z",
-      "turns": 14,
+      "turns": 68,
+      "turns_succeeded": 14,
       "tokens_in": 248312,
       "tokens_out": 38201,
       "cached_tokens": 198104,
@@ -159,6 +160,11 @@ Sample response:
 }
 ```
 
+`turns_succeeded` is one per request; `turns` is not comparable to it on these
+sessions — the Claude CLI emits a `user` event per tool-result batch and `turns`
+counts those, so the gap above is tool use, not failures. Compare
+`turns_succeeded` against your own request count.
+
 The single most important field is **`cached_tokens`**. If it grows turn-over-turn, the persistent CLI is being reused and Anthropic prompt caching is warming. If it stays at 0, something is killing the session every turn — check that no client is sending `X-Session-Reset` unintentionally and that `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` is not set when it shouldn't be.
 
 ## Smoke tests

package/skills/references/sessions.md

@@ -29,7 +29,7 @@ Key options:
 
 | Option | Description |
 |--------|-------------|
-| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'cursor'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
+| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
 | `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name |
 | `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
 | `effort` | `low`, `medium`, `high`, `max`, `auto` |
@@ -135,9 +135,32 @@ prompt over the window the engine actually enforces — so it rises and falls wi
 the conversation. `stats.tokensIn` is the different question of how many input
 tokens the session has been billed for in total, which only ever grows.
 `compactSession()` is a no-op on engines whose CLI has no compaction command
-(`codex`, `agy`, `cursor`, `opencode`); those sessions log a warning the first
+(`codex`, `agy`, `grok`, `opencode`); those sessions log a warning the first
 time it is called.
 
+`stats.turns` and `stats.turnsSucceeded` are the same kind of distinction.
+`turns` counts turns that reached the engine, whatever their outcome, including
+the ones that then failed. `turnsSucceeded` counts only the ones the engine
+reported as successful, and it is one per send on every engine.
+
+**The two are only comparable on the one-shot engines.** There `turns` is also
+one per send, so the difference between them is the failure count. On `claude`
+and a persistent `custom`, `turns` counts `user` events — and the CLI emits one
+per tool-result batch as well as the prompt echo, so a send that used eight tools
+counts nine. Compare `turnsSucceeded` against the number of sends there, never
+against `turns`.
+
+Which outcome counts as a success is the engine's own verdict, not the exit
+code's: `codex` fails a turn that emits `turn.failed` while exiting 0, `agy`
+requires a `SUCCESS` status *and* a zero exit (it can report success and then die
+in cleanup), `gemini` succeeds on exit 53 because its turn limit resolves,
+`codex-app` requires `status: 'completed'` so a turn cancelled through
+`interrupt()` does not count, and `opencode` refuses a turn on purpose when
+read-only enforcement did not load.
+
+The run ledger's `ok` reads this same counter, so a turn cannot be a failure on
+`/v1/sessions` and a success in `clawo runs`.
+
 ### Cost Tracking
 
 ```typescript

package/skills/references/tools.md

@@ -12,10 +12,10 @@ Start a persistent coding session with full CLI flag support.
 |-----------|------|-------------|
 | `name` | string | Session name (auto-generated if omitted) |
 | `cwd` | string | Working directory |
-| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'cursor'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. (`'gemini'` is still accepted for existing callers, but Gemini CLI is sunset — use `agy` for Google.) |
+| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'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`). 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.) |
 | `model` | string | Model alias or full name |
 | `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
-| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values. `read-only` is enforced on every other built-in engine too: Claude → plan mode; Antigravity / Cursor → their plan modes; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
+| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values. `read-only` is enforced on every other built-in engine too: Claude → plan mode; Antigravity → its plan mode; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. **`grok` refuses a read-only session** rather than approximate one — its enforcement has not been adversarially verified. A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
 | `effort` | string | `low`, `medium`, `high`, `max`, `auto` |
 | `allowedTools` | string[] | Tools to auto-approve |
 | `disallowedTools` | string[] | Tools to deny |