@enderfga/claw-orchestrator 4.13.1 → 4.14.0

package/dist/src/types.d.ts

@@ -293,6 +293,12 @@ export interface SessionStats {
     cursorChatId?: string;
     /** OpenCode session ID captured from the run's JSON output. Reused via `--session` for multi-turn context. */
     opencodeSessionId?: string;
+    /**
+     * True when the most recent turn's token counts came from estimateTokens()
+     * because the engine reported no usage. Cost derived from those counts is an
+     * estimate; the run ledger and budget docs surface it as such.
+     */
+    tokensEstimated?: boolean;
 }
 export interface HookConfig {
     onToolError?: string;
@@ -319,6 +325,11 @@ export interface SendOptions {
     stream?: boolean;
     onChunk?: (chunk: string) => void;
     onEvent?: (event: StreamEvent) => void;
+    /**
+     * council id / fanout id / autoloop run id. Stamped onto the run-ledger row
+     * so a multi-agent run can be reassembled from the ledger afterwards.
+     */
+    parentRunId?: string;
 }
 export interface StreamEvent {
     type: string;
@@ -349,6 +360,12 @@ export interface SessionInfo {
     model?: string;
     paused: boolean;
     stats: SessionStats;
+    /** Cumulative USD spent by this session, as reported by the engine's cost model. */
+    costUsd?: number;
+    /** The session's spend cap, when one was configured via `maxBudgetUsd`. */
+    budgetUsd?: number;
+    /** True once `costUsd` reached `budgetUsd` — further turns are refused. */
+    budgetExhausted?: boolean;
 }
 export interface SendResult {
     output: string;

package/openclaw.plugin.json

@@ -17,12 +17,26 @@
       },
       "defaultPermissionMode": {
         "type": "string",
-        "enum": ["acceptEdits", "bypassPermissions", "default", "delegate", "dontAsk", "plan", "auto"],
+        "enum": [
+          "acceptEdits",
+          "bypassPermissions",
+          "default",
+          "delegate",
+          "dontAsk",
+          "plan",
+          "auto"
+        ],
         "default": "acceptEdits"
       },
       "defaultEffort": {
         "type": "string",
-        "enum": ["low", "medium", "high", "max", "auto"],
+        "enum": [
+          "low",
+          "medium",
+          "high",
+          "max",
+          "auto"
+        ],
         "default": "auto"
       },
       "maxConcurrentSessions": {
@@ -60,7 +74,9 @@
   },
   "capabilities": {
     "childProcess": true,
-    "networkAccess": ["127.0.0.1"]
+    "networkAccess": [
+      "127.0.0.1"
+    ]
   },
   "contracts": {
     "tools": [
@@ -106,6 +122,12 @@
       "council_review",
       "council_accept",
       "council_reject",
+      "autoloop_start",
+      "autoloop_chat",
+      "autoloop_status",
+      "autoloop_list",
+      "autoloop_reset_agent",
+      "autoloop_stop",
       "session_send_to",
       "session_inbox",
       "session_deliver_inbox",
@@ -129,5 +151,7 @@
       "ultraapp_delete"
     ]
   },
-  "skills": ["skills/SKILL.md"]
+  "skills": [
+    "skills/SKILL.md"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "4.13.1",
+  "version": "4.14.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",
@@ -83,7 +83,8 @@
     "jetbrains",
     "neovim",
     "antigravity",
-    "coding-agent-protocol"
+    "coding-agent-protocol",
+    "deepseek-harness"
   ],
   "author": "enderfga",
   "repository": {

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 65 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".
+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".
 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 65 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, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 69 tools.
 
 ## Engine Quick Reference
 
@@ -208,6 +208,22 @@ engine mid-session.
 
 For setup, the dsh YAML block, and the cancellation/permission limits: see [references/acp.md](references/acp.md)
 
+## Cost & spend caps
+
+Every turn on every engine is appended to a durable ledger at
+`~/.claw-orchestrator/runs/YYYY-MM-DD.jsonl` — engine, model, per-turn tokens, cost, duration,
+and the council / fanout / autoloop it belonged to. Query it with `clawo runs [--since 24h]
+[--engine X] [--parent <run id>] [--json]`, `GET /runs`, or `manager.getRunLedger()`; it
+survives restarts, so it answers "what did we run today and what did it cost" after the
+sessions are gone.
+
+`maxBudgetUsd` on a session (or per council / fanout agent) is enforced by the runtime, so it
+holds on Codex, Cursor, agy, OpenCode and custom engines too — not just Claude Code. Once
+cumulative spend reaches the cap, further sends are refused before the engine is spawned.
+
+For the row schema, the query surfaces, and which engines report real token usage versus
+estimating it: see [references/observability.md](references/observability.md)
+
 ## Authentication Prerequisites
 
 Each engine requires its own auth before use:

package/skills/references/cli.md

@@ -134,6 +134,19 @@ clawo session-grep <name> <pattern> [-n, --limit <n>]
 clawo session-compact <name> [--summary <text>]
 ```
 
+## Run Ledger
+
+```bash
+clawo runs [--since <window>] [-n, --limit <n>] [--session <name>] [--engine <engine>] [--parent <id>] [--json]
+```
+
+Show the durable per-turn record kept at `~/.claw-orchestrator/runs/`. Unlike
+`session-status`, this survives restarts and covers sessions this process never
+owned. `--since` takes `30m` / `24h` / `7d` / `2w` or an ISO timestamp (default
+`24h`); `--parent` filters to one council / fanout / autoloop run. Costs marked
+with a trailing `~` came from estimated token counts. See
+[observability.md](observability.md).
+
 ## Agent Management
 
 ```bash

package/skills/references/observability.md

@@ -0,0 +1,131 @@
+# Observability — Run Ledger & Spend Caps
+
+Two related surfaces: a durable record of every turn this runtime executes, and a
+spend cap that is enforced by the runtime rather than by whichever CLI happens to
+support a budget flag.
+
+## Why
+
+`getStats()` / `getCost()` describe a **live** session. They live in memory, and
+per-session history is capped and evicted, so a restart erased everything except
+the resume-id registry — there was no way to answer "what did we run today, on
+which engine, for how much". The run ledger is that record.
+
+The same gap made `maxBudgetUsd` a promise the runtime did not keep: it was only
+ever translated into Claude Code's `--max-budget-usd` flag, so a council of Codex
+agents ran with no cap at all. The cap is now applied in `SessionManager`, which
+every engine passes through.
+
+## The ledger
+
+- Location: `~/.claw-orchestrator/runs/YYYY-MM-DD.jsonl` (override with
+  `CLAWO_RUNS_DIR`).
+- One JSON object per line, one line per completed turn — **successful or not**.
+- Shards are one file per UTC day. Queries always filter on the row timestamp, so
+  the shard boundary is a storage detail; `--since 24h` spans midnight correctly.
+- Writes are best-effort: a ledger failure is logged at `warn` and swallowed. It
+  can never break the turn it is describing.
+- Nothing prunes old shards. A row is roughly 250 bytes; delete shards yourself if
+  you want the history gone.
+
+### 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 reported `is_error` |
+| `error` | Failure text, truncated to 500 chars |
+| `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.
+
+Every path funnels through `SessionManager.sendMessage`, so council, fanout,
+autoloop, ACP, the OpenAI-compatible bridge, the MCP server and the CLI are all
+covered by the same hook. `parent` is what lets you reassemble a multi-agent run:
+
+```bash
+clawo runs --parent council-1a2b3c4d
+```
+
+### Reading it
+
+```bash
+clawo runs                                   # last 24h, table
+clawo runs --since 7d --engine codex         # one engine, one week
+clawo runs --session my-session --json       # raw rows + summary
+clawo runs --parent fanout-b5f7c886          # every agent turn of one fan-out
+```
+
+Over HTTP (GET query string or POST JSON body):
+
+```bash
+curl "http://127.0.0.1:18796/runs?since=24h&limit=200" -H "Authorization: Bearer $TOKEN"
+```
+
+Returns `{ ok, rows, summary }`, where `summary` carries `rows`, `costUsd`,
+`tokensIn`, `tokensOut`, `estimatedRows` and a per-engine breakdown. The dashboard
+header shows the 24-hour figure from the same endpoint.
+
+Programmatically: `manager.getRunLedger({ since, session, engine, parent, limit })`.
+
+## Spend caps
+
+Set `maxBudgetUsd` on a session (or on a council / fanout, which applies it per
+agent). Before each turn the runtime compares the session's cumulative
+`getCost().totalUsd` against the cap and refuses to send when it has been reached:
+
+```
+Budget exceeded for session "my-session" (codex): spent $1.2400 of $1.0000 cap.
+Raise maxBudgetUsd or start a new session to continue.
+```
+
+The refusal is a typed `BudgetExceededError` carrying `session`, `engine`,
+`spentUsd` and `capUsd`, and it happens **before** the engine is spawned.
+
+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*.
+- 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.
+
+## Accuracy: which engines report real usage
+
+`costUsd` is derived from token counts times the model's price in `models.ts`.
+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 |
+
+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
+your provider offers.
+
+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".

package/skills/references/tools.md

@@ -20,7 +20,7 @@ Start a persistent coding session with full CLI flag support.
 | `allowedTools` | string[] | Tools to auto-approve |
 | `disallowedTools` | string[] | Tools to deny |
 | `maxTurns` | number | Max agent loop turns |
-| `maxBudgetUsd` | number | Max API spend (USD) |
+| `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. |
 | `systemPrompt` | string | Replace system prompt |
 | `appendSystemPrompt` | string | Append to system prompt |
 | `agents` | object | Custom sub-agents JSON |