@enderfga/claw-orchestrator 5.0.0 → 5.1.0

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({

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 |
@@ -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

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,7 +135,7 @@ 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.

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 |