@enderfga/claw-orchestrator 5.0.0 → 6.0.0

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)
@@ -37,6 +39,7 @@ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Cla
 - Fork subagent (`forkSubagent`), tool search (`enableToolSearch`), OpenTelemetry logging toggles (`otelLogUserPrompts`, `otelLogRawApiBodies`), `xhigh` effort tier (Opus 4.7), and `stats.pluginErrors` capture — see [CLI 2.1.121 options in SKILL.md](../SKILL.md) and [tools.md](./tools.md)
 
 > **Behavior changes from upstream Claude CLI 2.1.121** (worth knowing if you set permission rules):
+>
 > - `--agent` / `--print` now enforce agent frontmatter `permissionMode`, `tools`, `disallowedTools` (was advisory). Affects `council` agent personas.
 > - `Bash(find:*)` permission rule no longer auto-approves `find -exec` or `find -delete`. Add explicit rules if you depend on these.
 > - `--dangerously-skip-permissions` also skips prompts for `.claude/skills/` directory. Treat with care.
@@ -45,7 +48,7 @@ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Cla
 ```typescript
 await manager.startSession({
   name: 'claude-task',
-  engine: 'claude',       // default, can omit
+  engine: 'claude', // default, can omit
   model: 'opus',
   cwd: '/project',
 });
@@ -138,6 +141,7 @@ in print mode. Verified against `agy` **1.1.13**.
   `gemini-3.1-pro has no "medium" effort (available: low, high)`. The adapter
   passes the requested effort through rather than substituting a tier the caller
   did not ask for; run `agy models` to see the tiers a slug actually exposes.
+
 - Permission modes: `bypassPermissions` → `--dangerously-skip-permissions`,
   `default` → `--sandbox` (terminal-restricted), and
   `sandboxMode: 'read-only'` → `--mode plan` (takes precedence). Other modes
@@ -173,9 +177,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 +239,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({
@@ -271,12 +327,12 @@ is not the answer on every engine. See "Stats & Monitoring" in `sessions.md`.
 
 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.
 
-| Engine | `team_list` | `team_send` |
-|--------|------------|-------------|
-| Claude | Lists other active SessionManager sessions | Routes via cross-session inbox |
-| Codex | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Engine      | `team_list`                                | `team_send`                    |
+| ----------- | ------------------------------------------ | ------------------------------ |
+| Claude      | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Codex       | Lists other active SessionManager sessions | Routes via cross-session inbox |
 | Antigravity | Lists other active SessionManager sessions | Routes via cross-session inbox |
-| Cursor | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Cursor      | Lists other active SessionManager sessions | Routes via cross-session inbox |
 
 Messages are delivered via the inbox system — idle sessions receive immediately, busy sessions queue for later delivery.
 
@@ -295,12 +351,13 @@ If OpenClaw gateway is running, everything is automatic:
 await manager.startSession({
   name: 'task',
   engine: 'claude',
-  model: 'openclaw',        // gateway routes to your configured model
+  model: 'openclaw', // gateway routes to your configured model
   cwd: '/project',
 });
 ```
 
 What happens behind the scenes:
+
 1. Plugin reads `~/.openclaw/openclaw.json` for gateway port + auth
 2. Starts a local proxy server (random port, auto-managed)
 3. Claude Code CLI sends Anthropic-format requests → proxy converts to OpenAI → gateway → any model
@@ -309,12 +366,12 @@ What happens behind the scenes:
 
 Override with environment variables if needed:
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `GATEWAY_URL` | Auto-detected from openclaw.json | Gateway endpoint (e.g. `http://127.0.0.1:18789/v1`) |
-| `GATEWAY_KEY` | Auto-detected from openclaw.json | Gateway auth password/token |
-| `GEMINI_API_KEY` | - | Direct Gemini API access (bypasses gateway) |
-| `OPENAI_API_KEY` | - | Direct OpenAI API access (bypasses gateway) |
+| Variable         | Default                          | Description                                         |
+| ---------------- | -------------------------------- | --------------------------------------------------- |
+| `GATEWAY_URL`    | Auto-detected from openclaw.json | Gateway endpoint (e.g. `http://127.0.0.1:18789/v1`) |
+| `GATEWAY_KEY`    | Auto-detected from openclaw.json | Gateway auth password/token                         |
+| `GEMINI_API_KEY` | -                                | Direct Gemini API access (bypasses gateway)         |
+| `OPENAI_API_KEY` | -                                | Direct OpenAI API access (bypasses gateway)         |
 
 ### Architecture
 
@@ -330,46 +387,47 @@ Claude Code CLI (Anthropic format)
 Integrate **any** coding agent CLI without writing engine-specific code. You provide a `CustomEngineConfig` that maps your CLI's flags to OpenClaw session concepts.
 
 Two protocol modes:
+
 - **Persistent** (`persistent: true`) — long-running subprocess with stream-json I/O over stdin/stdout (like Claude Code)
 - **One-shot** (`persistent: false`, default) — new process spawned per `send()` (like Codex/Antigravity)
 
 ### CustomEngineConfig
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | yes | Display name (used in logs, session IDs) |
-| `bin` | string | yes | Binary path or command name |
-| `binEnv` | string | | Env var name that overrides `bin` at runtime |
-| `persistent` | boolean | | `true` = persistent subprocess, `false` = one-shot (default) |
-| `args` | object | yes | CLI flag mappings (see below) |
-| `permissionModes` | object | | Maps OpenClaw mode names to CLI-specific values |
-| `pricing` | object | | `{ input, output, cached? }` per 1M tokens |
-| `contextWindow` | number | | Context window size (default: 200,000) |
-| `env` | object | | Extra environment variables for the CLI process |
-| `sanitizePatterns` | string[] | | Regex patterns to redact from stderr |
+| Field              | Type     | Required | Description                                                  |
+| ------------------ | -------- | -------- | ------------------------------------------------------------ |
+| `name`             | string   | yes      | Display name (used in logs, session IDs)                     |
+| `bin`              | string   | yes      | Binary path or command name                                  |
+| `binEnv`           | string   |          | Env var name that overrides `bin` at runtime                 |
+| `persistent`       | boolean  |          | `true` = persistent subprocess, `false` = one-shot (default) |
+| `args`             | object   | yes      | CLI flag mappings (see below)                                |
+| `permissionModes`  | object   |          | Maps OpenClaw mode names to CLI-specific values              |
+| `pricing`          | object   |          | `{ input, output, cached? }` per 1M tokens                   |
+| `contextWindow`    | number   |          | Context window size (default: 200,000)                       |
+| `env`              | object   |          | Extra environment variables for the CLI process              |
+| `sanitizePatterns` | string[] |          | Regex patterns to redact from stderr                         |
 
 ### args field
 
-| Key | Example | Description |
-|-----|---------|-------------|
-| `print` | `"-p"` | Non-interactive/print mode flag |
-| `outputFormat` | `"--output-format"` | Output format flag |
-| `outputFormatValue` | `"stream-json"` | Value for stream-json output |
-| `inputFormat` | `"--input-format"` | Input format flag (persistent only) |
-| `inputFormatValue` | `"stream-json"` | Value for stream-json input |
-| `skipPermissions` | `"-y"` | Skip all permissions flag |
-| `permissionMode` | `"--permission-mode"` | Permission mode flag |
-| `model` | `"--model"` | Model selection flag |
-| `systemPrompt` | `"--system-prompt"` | System prompt override flag |
-| `appendSystemPrompt` | `"--append-system-prompt"` | Append system prompt flag |
-| `maxTurns` | `"--max-turns"` | Max agent turns flag |
-| `resume` | `"--resume"` | Session resume flag (persistent only) |
-| `verbose` | `"--verbose"` | Verbose output flag |
-| `replayUserMessages` | `"--replay-user-messages"` | Replay user messages (persistent only) |
+| Key                      | Example                        | Description                                |
+| ------------------------ | ------------------------------ | ------------------------------------------ |
+| `print`                  | `"-p"`                         | Non-interactive/print mode flag            |
+| `outputFormat`           | `"--output-format"`            | Output format flag                         |
+| `outputFormatValue`      | `"stream-json"`                | Value for stream-json output               |
+| `inputFormat`            | `"--input-format"`             | Input format flag (persistent only)        |
+| `inputFormatValue`       | `"stream-json"`                | Value for stream-json input                |
+| `skipPermissions`        | `"-y"`                         | Skip all permissions flag                  |
+| `permissionMode`         | `"--permission-mode"`          | Permission mode flag                       |
+| `model`                  | `"--model"`                    | Model selection flag                       |
+| `systemPrompt`           | `"--system-prompt"`            | System prompt override flag                |
+| `appendSystemPrompt`     | `"--append-system-prompt"`     | Append system prompt flag                  |
+| `maxTurns`               | `"--max-turns"`                | Max agent turns flag                       |
+| `resume`                 | `"--resume"`                   | Session resume flag (persistent only)      |
+| `verbose`                | `"--verbose"`                  | Verbose output flag                        |
+| `replayUserMessages`     | `"--replay-user-messages"`     | Replay user messages (persistent only)     |
 | `includePartialMessages` | `"--include-partial-messages"` | Include partial messages (persistent only) |
-| `effort` | `"--effort"` | Effort level flag |
-| `workspace` | `"--workspace"` | Workspace/cwd flag (one-shot only) |
-| `extra` | `["--trust"]` | Additional static arguments |
+| `effort`                 | `"--effort"`                   | Effort level flag                          |
+| `workspace`              | `"--workspace"`                | Workspace/cwd flag (one-shot only)         |
+| `extra`                  | `["--trust"]`                  | Additional static arguments                |
 
 ### Example: Persistent mode (Claude Code-compatible CLI)
 
@@ -417,7 +475,7 @@ await manager.startSession({
   customEngine: {
     name: 'simple-agent',
     bin: '/usr/local/bin/simple-agent',
-    persistent: false,  // default
+    persistent: false, // default
     args: {
       print: '-p',
       outputFormat: '--output-format',
@@ -451,11 +509,11 @@ await manager.startSession({
   dangerouslySkipPermissions: true,
   customEngine: {
     name: 'antigravity',
-    bin: 'agy',           // install: curl -fsSL https://antigravity.google/cli/install.sh | bash
+    bin: 'agy', // install: curl -fsSL https://antigravity.google/cli/install.sh | bash
     binEnv: 'AGY_BIN',
     persistent: false,
     args: {
-      print: '-p',                                  // single-prompt headless mode
+      print: '-p', // single-prompt headless mode
       skipPermissions: '--dangerously-skip-permissions',
       workspace: '--add-dir',
       // NOTE: agy 1.0.2 has NO --output-format flag — output is plain text only.

package/skills/references/observability.md

@@ -30,22 +30,22 @@ every engine passes through.
 
 ### Row schema
 
-| Field | Meaning |
-|---|---|
-| `ts` | ISO timestamp of turn completion |
-| `session` | SessionManager session name |
-| `engine` | `claude` / `codex` / `codex-app` / `cursor` / `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 |
-| `tokensIn` / `tokensOut` / `cachedTokens` | **Per-turn deltas**, not session totals |
-| `costUsd` | Per-turn delta in USD |
-| `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 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 |
+| Field                                     | Meaning                                                                                                                                                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ts`                                      | ISO timestamp of turn completion                                                                                                                                                                 |
+| `session`                                 | SessionManager session name                                                                                                                                                                      |
+| `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                                                                                                                                                            |
+| `tokensIn` / `tokensOut` / `cachedTokens` | **Per-turn deltas**, not session totals                                                                                                                                                          |
+| `costUsd`                                 | Per-turn delta in USD                                                                                                                                                                            |
+| `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 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
 without double-counting.
@@ -98,11 +98,11 @@ Notes:
 - The check is "has the cap been reached", not "would this turn exceed it" — a
   turn's cost is unknown until it finishes, so the last allowed turn can overshoot.
   Size the cap accordingly.
-- A cap of `0` or a negative number means *unset*, not *refuse everything*.
+- A cap of `0` or a negative number means _unset_, not _refuse everything_.
 - Claude Code still receives `--max-budget-usd` as well: an in-CLI stop happens
   earlier and therefore costs less than an after-the-fact refusal.
 - `session_list` / `GET /session/list` expose `costUsd`, `budgetUsd` and
-  `budgetExhausted` so a stalled session shows *why* it stopped taking turns.
+  `budgetExhausted` so a stalled session shows _why_ it stopped taking turns.
 
 ## Accuracy: which engines report real usage
 
@@ -111,15 +111,16 @@ Where the engine reports usage, those counts are the engine's own. Where it does
 not, the wrapper falls back to `estimateTokens()` (characters ÷ 4) and the row is
 flagged `tokensEstimated: true`; the CLI marks those costs with a trailing `~`.
 
-| Engine | Token counts |
-|---|---|
-| `claude` | Engine-reported |
-| `codex` | Engine-reported |
-| `codex-app` | Engine-reported |
-| `cursor` | 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 |
+| Engine            | Token counts                                                                                                                                                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude`          | Engine-reported                                                                                                                                                                                          |
+| `codex`           | Engine-reported                                                                                                                                                                                          |
+| `codex-app`       | Engine-reported                                                                                                                                                                                          |
+| `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                                                                                                                                                     |
 
 So on an estimating engine the cap is best-effort. It will stop a runaway session;
 it is not an accounting guarantee, and it is not a substitute for the spend limits
@@ -129,3 +130,63 @@ Cost figures are also only as good as the pricing table: a model missing from
 `models.ts` prices at its family default, and subscription plans (Claude Max,
 ChatGPT Pro) bill nothing per token while the ledger still reports the API-rate
 equivalent. Read `costUsd` as "what this would cost at API rates".
+
+## `ok` vs `verified` (6.0.0)
+
+A row now carries two different judgements, and conflating them is the mistake
+this section exists to prevent.
+
+- **`ok`** — the engine's own terminal verdict for that turn. Codex fails a turn
+  that emits `turn.failed` while exiting 0; gemini succeeds on exit 53. It is a
+  careful signal, but it is the engine talking about itself.
+- **`verified`** — an acceptance contract ran against the work and every required
+  check passed. That is the runtime's own measurement.
+
+Three states, not two:
+
+| `verified` | Means                                               | CLI column |
+| ---------- | --------------------------------------------------- | ---------- |
+| `true`     | A contract ran and passed                           | `yes`      |
+| `false`    | A contract ran and a required check failed          | `NO`       |
+| absent     | **No contract was declared. Nothing checked this.** | `—`        |
+
+Absent is not false. An unchecked run is not a failed one, and reading it as
+either would make the ledger useless for the thing it is for.
+
+### Where the verdict comes from
+
+`verified` is **not written at turn time**, deliberately. The turns that produce
+the work all finish before the verifier that judges it, so stamping a verdict on
+them as they are written would be inventing one. It is joined in at read time
+from the run record via the row's `parent`, by `annotateVerdicts()`.
+
+Two consequences worth knowing:
+
+- A raw `runs/*.jsonl` line usually has no `verified` field. Read through
+  `clawo runs` / `GET /runs` / `getRunLedger()` to get the join.
+- Filtering on `--verified` happens _after_ the join. Pushing the filter into the
+  ledger read would match on a field no row carries yet and return nothing.
+
+### Other new row fields
+
+| Field                      | Source                                                                                                                                                          |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `evidenceId`, `contractId` | Joined from the run record                                                                                                                                      |
+| `nodeKind`                 | The kernel node the turn belonged to (`agent`, `council`, `verifier`, …)                                                                                        |
+| `repoLang`                 | Detected from a manifest (`package.json`, `pyproject.toml`, `go.mod`, …). Never guessed — a wrong label would corrupt the comparison the field exists to enable |
+| `taskKind`                 | Caller-declared only. Never inferred from the prompt                                                                                                            |
+
+All are optional and absent on rows written before 6.0.0. The reader already
+skips unknown and missing keys, so old shards stay readable; nothing backfills
+them, because we cannot know retroactively.
+
+```bash
+clawo runs --since 7d --verified     # only turns whose contract passed
+clawo runs --since 7d --refuted      # only turns whose contract failed
+clawo runs --parent wf-abc123        # every turn of one workflow run
+```
+
+## Related
+
+- [`verification.md`](./verification.md) — what a contract is and how a verdict is produced
+- [`workflow.md`](./workflow.md) — where run records live

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.
@@ -11,13 +11,13 @@ Both modes share the same wire protocol; the difference is how a "new conversati
 
 ## Endpoint
 
-| | |
-|---|---|
-| **URL** | `http://127.0.0.1:18796/v1/chat/completions` |
-| **Models endpoint** | `GET /v1/models` |
-| **Inspection endpoint** | `GET /v1/sessions` (lists active openai-compat sessions with caching stats) |
-| **Auth** | Bearer token via `Authorization: Bearer $OPENCLAW_SERVER_TOKEN` (set the env var to enable; otherwise no auth and the server is loopback-only) |
-| **Wire format** | OpenAI Chat Completions, both streaming (SSE) and non-streaming |
+|                         |                                                                                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **URL**                 | `http://127.0.0.1:18796/v1/chat/completions`                                                                                                   |
+| **Models endpoint**     | `GET /v1/models`                                                                                                                               |
+| **Inspection endpoint** | `GET /v1/sessions` (lists active openai-compat sessions with caching stats)                                                                    |
+| **Auth**                | Bearer token via `Authorization: Bearer $OPENCLAW_SERVER_TOKEN` (set the env var to enable; otherwise no auth and the server is loopback-only) |
+| **Wire format**         | OpenAI Chat Completions, both streaming (SSE) and non-streaming                                                                                |
 
 ## Session keying
 
@@ -56,20 +56,20 @@ Without this flag, those frontends would silently continue the previous CLI sess
 
 The env var is read on every request, so ops can flip it via `launchctl setenv` (or equivalent) without restarting the server.
 
-| Mode | Best for | New-conversation signals |
-|---|---|---|
-| **Default** | OpenClaw main agent, cron jobs, subagents, scripted clients | `X-Session-Reset: 1` only |
+| Mode              | Best for                                                    | New-conversation signals                            |
+| ----------------- | ----------------------------------------------------------- | --------------------------------------------------- |
+| **Default**       | OpenClaw main agent, cron jobs, subagents, scripted clients | `X-Session-Reset: 1` only                           |
 | **`HEURISTIC=1`** | ChatGPT-Next-Web, Open WebUI, LobeChat, data labeling tools | `X-Session-Reset: 1` **and** `[system, user]` shape |
 
 ## Status webhook
 
 When `OPENAI_COMPAT_STATUS_URL` is set (full HTTP URL), each chat completion sends best-effort `POST` requests with `Content-Type: application/json` and body:
 
-| Field | Type | Meaning |
-|---|---|---|
-| `state` | string | `thinking` (turn started), `working` (a tool is running), or `idle` (turn finished or stream closed). |
-| `activity` | string | Short human-readable line, e.g. `Processing request...`, `Reading: foo.ts`, `Running: npm test...`. |
-| `tool` | string \| null | Tool name when `state === working`, otherwise `null`. |
+| Field      | Type           | Meaning                                                                                               |
+| ---------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| `state`    | string         | `thinking` (turn started), `working` (a tool is running), or `idle` (turn finished or stream closed). |
+| `activity` | string         | Short human-readable line, e.g. `Processing request...`, `Reading: foo.ts`, `Running: npm test...`.   |
+| `tool`     | string \| null | Tool name when `state === working`, otherwise `null`.                                                 |
 
 Failures are ignored (no retries). Use this from a small local HTTP handler that forwards status into your webchat UI.
 
@@ -78,17 +78,17 @@ Failures are ignored (no retries). Use this from a small local HTTP handler that
 When the request carries `tools`, the schemas have to reach the CLI somehow. Which
 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 |
-| `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 |
+| 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`, `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
 everything injected stays in the transcript. Re-sending the full block each turn
 grows the prompt without bound — a 54-tool block runs to roughly 17k tokens, so a
 handful of turns is enough to overflow the context window mid-loop and fail the
-run outright. Sending *nothing* on resume turns is not the answer either: the
+run outright. Sending _nothing_ on resume turns is not the answer either: the
 block also carries the "emit a tool call, do not carry out the work yourself"
 framing, and without it the CLI starts doing the work directly.
 
@@ -116,16 +116,16 @@ does change mid-conversation.
 
 ## Environment variables
 
-| Variable | Default | Purpose |
-|---|---|---|
-| `OPENCLAW_SERVER_TOKEN` | (unset) | Bearer token for HTTP auth. Set to enable; written to `~/.openclaw/server-token` for the CLI. |
-| `OPENCLAW_RATE_LIMIT` | `300` | Max requests per IP per 60-second sliding window. |
-| `OPENCLAW_CORS_ORIGINS` | (loopback only) | Set to `*` to allow all origins (the `/v1/*` paths already do this). |
-| `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` | (unset) | Set to `1` to enable webchat mode (see above). |
-| `OPENAI_COMPAT_TOOLS_PER_MESSAGE` | (unset) | Set to `1` to re-send the full tool schemas on every turn (see [Tool definitions](#tool-definitions-and-where-they-live)). Needed only when the tool set changes mid-conversation; costs per-turn prompt growth. |
-| `OPENAI_COMPAT_STATUS_URL` | (unset) | If set, the bridge POSTs JSON status updates to this URL (fire-and-forget, 2s timeout). See [Status webhook](#status-webhook). |
-| `OPENCLAW_SERVE_MAX_SESSIONS` | `32` | Max concurrent OpenAI-compat sessions in serve mode. Bumped from the in-plugin default of 5 because each distinct caller now gets its own `sys-<hash>` session. |
-| `OPENCLAW_SERVE_TTL_MINUTES` | `60` | Idle TTL for OpenAI-compat sessions in serve mode. Idle sessions are reaped by a 60s background loop; persisted disk registry is kept for 7 days so a returning caller is auto-resumed. |
+| Variable                            | Default         | Purpose                                                                                                                                                                                                          |
+| ----------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENCLAW_SERVER_TOKEN`             | (unset)         | Bearer token for HTTP auth. Set to enable; written to `~/.openclaw/server-token` for the CLI.                                                                                                                    |
+| `OPENCLAW_RATE_LIMIT`               | `300`           | Max requests per IP per 60-second sliding window.                                                                                                                                                                |
+| `OPENCLAW_CORS_ORIGINS`             | (loopback only) | Set to `*` to allow all origins (the `/v1/*` paths already do this).                                                                                                                                             |
+| `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` | (unset)         | Set to `1` to enable webchat mode (see above).                                                                                                                                                                   |
+| `OPENAI_COMPAT_TOOLS_PER_MESSAGE`   | (unset)         | Set to `1` to re-send the full tool schemas on every turn (see [Tool definitions](#tool-definitions-and-where-they-live)). Needed only when the tool set changes mid-conversation; costs per-turn prompt growth. |
+| `OPENAI_COMPAT_STATUS_URL`          | (unset)         | If set, the bridge POSTs JSON status updates to this URL (fire-and-forget, 2s timeout). See [Status webhook](#status-webhook).                                                                                   |
+| `OPENCLAW_SERVE_MAX_SESSIONS`       | `32`            | Max concurrent OpenAI-compat sessions in serve mode. Bumped from the in-plugin default of 5 because each distinct caller now gets its own `sys-<hash>` session.                                                  |
+| `OPENCLAW_SERVE_TTL_MINUTES`        | `60`            | Idle TTL for OpenAI-compat sessions in serve mode. Idle sessions are reaped by a 60s background loop; persisted disk registry is kept for 7 days so a returning caller is auto-resumed.                          |
 
 ## Inspection: `GET /v1/sessions`
 
@@ -235,14 +235,14 @@ Errors use the OpenAI error envelope:
 { "error": { "message": "...", "type": "invalid_request_error" } }
 ```
 
-| Status | When |
-|---|---|
-| 400 | `messages` empty/missing, no user message, invalid `max_tokens` |
-| 401 | Missing or wrong bearer token (when auth enabled) |
-| 415 | POST without `Content-Type: application/json` |
-| 429 | Rate limited (`OPENCLAW_RATE_LIMIT` exceeded) |
-| 503 | Failed to start a new session (model unavailable, CLI crashed at boot) |
-| 500 | Mid-turn failure |
+| Status | When                                                                   |
+| ------ | ---------------------------------------------------------------------- |
+| 400    | `messages` empty/missing, no user message, invalid `max_tokens`        |
+| 401    | Missing or wrong bearer token (when auth enabled)                      |
+| 415    | POST without `Content-Type: application/json`                          |
+| 429    | Rate limited (`OPENCLAW_RATE_LIMIT` exceeded)                          |
+| 503    | Failed to start a new session (model unavailable, CLI crashed at boot) |
+| 500    | Mid-turn failure                                                       |
 
 ## Related