@enderfga/claw-orchestrator 7.12.1 → 7.14.0

package/README.md

@@ -49,6 +49,7 @@ clawo runs --since 1h   # every turn on every engine: model, tokens, cost, verdi
 | Switch engines mid-task          | `session_handoff` replays a live conversation onto another engine in the same workspace. → [sessions](./skills/references/sessions.md)                                                                                                                                                                                        |
 | Know what it cost                | A durable per-turn ledger across engines (`clawo runs`) and a `maxBudgetUsd` cap the runtime enforces on every engine. → [observability](./skills/references/observability.md)                                                                                                                                                |
 | Runs that survive a crash        | Durable workflows: every transition is checkpointed; resume, retry, timeout, cancel and steer come from the kernel. → [workflow](./skills/references/workflow.md)                                                                                                                                                             |
+| Leave Codex on a goal for hours  | `clawo goal` runs a Codex `/goal` on one thread until it finishes, reattaches it after a crash, resumes it after usage limits within a bound, optionally inside your own sandbox, then judges it with your checks. → [workflow](./skills/references/workflow.md#goal)                                                         |
 | Call it from your own tools      | An MCP server (`clawo-mcp`), an ACP agent (`clawo acp`) for Zed, JetBrains and other ACP editors, an OpenAI-compatible endpoint, a TypeScript SDK, and the CLI. → [integrations](#integrations)                                                                                                                               |
 
 **How it relates to other tools.** claude-squad, Conductor and Vibe Kanban are interfaces for running agents side by side in worktrees; Claude Code subagents and Codex's parallel attempts stay within one vendor. Claw Orchestrator is a headless runtime: several vendors behind one API, durable workflows, and a verification step the agents cannot edit. They can be used together.
@@ -71,6 +72,7 @@ The server writes an access token to `~/.openclaw/server-token`; the CLI reads i
 ```bash
 clawo solve "Fix the failing tests" --engine claude --check "npm test" --wait
 clawo fanout "How would you speed up this test suite?" --engines claude,codex,grok --synthesize --wait
+clawo goal --objective-file GOAL.md --check "npm run bench:check" --check-timeout 120 --wait
 clawo workflow list
 ```
 
@@ -99,7 +101,7 @@ const result = await manager.sendMessage('fix-tests', 'Fix the failing tests');
 | Capability                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                              | Reference                                                  |
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
 | **Persistent Sessions**     | Long-lived coding agents kept alive across requests, with full context, tool, model, and worktree control.                                                                                                                                                                                                                                                                                                                                | [`sessions.md`](./skills/references/sessions.md)           |
-| **Multi-Engine Runtime**    | One interface over Claude Code, Codex, Antigravity (agy), Grok Build, OpenCode, and arbitrary custom CLIs.                                                                                                                                                                                                                                                                                                                                | [`multi-engine.md`](./skills/references/multi-engine.md)   |
+| **Multi-Engine Runtime**    | One interface over Claude Code, Codex, Antigravity (agy), Grok Build, OpenCode, any Agent Client Protocol agent (Kimi Code, dsh), and arbitrary custom CLIs.                                                                                                                                                                                                                                                                              | [`multi-engine.md`](./skills/references/multi-engine.md)   |
 | **Session Handoff**         | Move a live conversation to another engine or model — a stuck Claude session into Codex, an expensive model into a cheaper one. The new session picks up where the old one stopped, in the same workspace; the old one keeps running.                                                                                                                                                                                                     | [`sessions.md`](./skills/references/sessions.md)           |
 | **Multi-Agent Council**     | Parallel agents in isolated git worktrees, voting on consensus until they agree.                                                                                                                                                                                                                                                                                                                                                          | [`council.md`](./skills/references/council.md)             |
 | **Fan-out**                 | Run one task across N engine/model agents in parallel and collect their answers, with an optional synthesis pass — the cross-engine best-of-N / diverse-perspective primitive (no rounds or worktrees).                                                                                                                                                                                                                                   | [`tools.md`](./skills/references/tools.md)                 |
@@ -165,16 +167,17 @@ block, and the cancellation and permission limitations are in
 
 ## Engine Compatibility
 
-| Engine      | CLI        | Tested Version |
-| ----------- | ---------- | -------------- |
-| Claude Code | `claude`   | 2.1.307        |
-| Codex       | `codex`    | 0.163.0        |
-| Antigravity | `agy`      | 1.4.4          |
-| Grok Build  | `grok`     | 1.0.67         |
-| OpenCode    | `opencode` | 1.19.3         |
-| Custom CLI  | any        | —              |
-
-Any coding CLI that runs as a subprocess can be wired up as a custom engine — see [`multi-engine.md`](./skills/references/multi-engine.md#custom-engine-engine-custom).
+| Engine      | CLI        | Tested Version                  |
+| ----------- | ---------- | ------------------------------- |
+| Claude Code | `claude`   | 2.1.310                         |
+| Codex       | `codex`    | 0.164.0                         |
+| Antigravity | `agy`      | 1.4.6                           |
+| Grok Build  | `grok`     | 1.0.70                          |
+| OpenCode    | `opencode` | 1.19.4                          |
+| ACP agent   | any        | Kimi Code 2.3.1, dsh 0.2.1-rc.2 |
+| Custom CLI  | any        | —                               |
+
+An agent that serves the Agent Client Protocol on stdio runs as `engine: 'acp'` — see [`multi-engine.md`](./skills/references/multi-engine.md#acp-agents-engine-acp). Any other coding CLI that runs as a subprocess can be wired up as a custom engine — see [`multi-engine.md`](./skills/references/multi-engine.md#custom-engine-engine-custom).
 
 ---
 

package/configs/engines/README.md

@@ -47,3 +47,23 @@ Contribution steps, the smoke script, and the full field reference are in
 
 `engine.bin` must be a command name, not an absolute path — one machine's layout
 is not a preset. Use `binEnv` so people who installed it elsewhere can point at it.
+
+## ACP agents
+
+A preset can name an agent that serves the Agent Client Protocol on stdio instead
+of a `CustomEngineConfig`: it carries `acp` in place of `engine`, and is started
+with `engine: "acp"` (`clawo session-start <name> -e acp --acp-agent <id>`). No
+protocol mapping is needed, since every ACP agent speaks the same protocol.
+
+```json
+{
+  "id": "kimi-code",
+  "tier": "community",
+  "description": "…",
+  "provenance": { "maintainer": "…", "verifiedAgainst": "2.3.1", "verifiedOn": "2026-10-24" },
+  "acp": { "name": "kimi-code", "command": "kimi", "commandEnv": "KIMI_BIN", "args": ["acp"] }
+}
+```
+
+`acp.command` follows the same rule as `engine.bin`: a command name, with
+`commandEnv` for an install elsewhere.

package/configs/engines/dsh.json

@@ -0,0 +1,17 @@
+{
+  "id": "dsh",
+  "tier": "community",
+  "description": "DeepSeek Harness (`dsh`), served over the Agent Client Protocol (`dsh --profile acp`). Start with engine 'acp'.",
+  "provenance": {
+    "maintainer": "Enderfga",
+    "verifiedAgainst": "0.2.1-rc.2",
+    "verifiedOn": "2026-10-24",
+    "sourceUrl": "https://www.npmjs.com/package/@deepseek-ai/dsh"
+  },
+  "acp": {
+    "name": "dsh",
+    "command": "dsh",
+    "commandEnv": "DSH_BIN",
+    "args": ["--profile", "acp"]
+  }
+}

package/configs/engines/kimi-code.json

@@ -0,0 +1,17 @@
+{
+  "id": "kimi-code",
+  "tier": "community",
+  "description": "Moonshot AI's Kimi Code CLI, served over the Agent Client Protocol (`kimi acp`). Start with engine 'acp'.",
+  "provenance": {
+    "maintainer": "Enderfga",
+    "verifiedAgainst": "2.3.1",
+    "verifiedOn": "2026-10-24",
+    "sourceUrl": "https://www.kimi.com/code/docs/en/kimi-code-cli/reference/kimi-acp"
+  },
+  "acp": {
+    "name": "kimi-code",
+    "command": "kimi",
+    "commandEnv": "KIMI_BIN",
+    "args": ["acp"]
+  }
+}

package/dist/bin/cli.js

@@ -67,6 +67,15 @@ async function api(path, method = 'GET', body) {
     }
 }
 // ─── CLI ─────────────────────────────────────────────────────────────────────
+/**
+ * Print an API failure the same way every command does, and exit non-zero so a
+ * script can tell: a command that could not reach the server used to exit 0.
+ */
+function fail(r) {
+    const error = r && typeof r === 'object' && 'error' in r ? r.error : r;
+    console.error(`Failed: ${String(error)}`);
+    process.exitCode = 1;
+}
 const program = new Command();
 program.name('clawo').description('Claw Orchestrator CLI').version(getCliVersion());
 // Serve (standalone mode — no OpenClaw needed)
@@ -146,9 +155,9 @@ program
 // Session commands
 program
     .command('session-start [name]')
-    .description('Start a persistent coding session (Claude Code, Codex, Antigravity, Grok Build, OpenCode, or a custom engine preset)')
+    .description('Start a persistent coding session (Claude Code, Codex, Antigravity, Grok Build, OpenCode, an ACP agent, or a custom engine preset)')
     .option('-d, --cwd <dir>', 'Working directory')
-    .option('-e, --engine <engine>', 'Engine: claude (default), codex, codex-app, gemini, agy, cursor, grok, opencode, or custom')
+    .option('-e, --engine <engine>', 'Engine: claude (default), codex, codex-app, gemini, agy, cursor, grok, opencode, acp, or custom')
     .option('-m, --model <model>', 'Model to use')
     .option('--permission-mode <mode>', 'Permission mode', 'acceptEdits')
     .option('--effort <level>', 'Effort level')
@@ -174,6 +183,7 @@ program
     .option('--base-url <url>', 'Custom API endpoint (for proxy)')
     .option('--add-dir <dirs>', 'Comma-separated additional working directories')
     .option('--custom-engine <preset>', 'With -e custom: the id of a bundled engine preset (see `clawo engines`). Inline configs are not accepted here — that is what presets are for')
+    .option('--acp-agent <preset>', 'With -e acp: the id of a bundled ACP agent preset (see `clawo engines`)')
     .action(async (name, opts) => {
     const body = { name: name || `session-${Date.now()}` };
     if (opts.cwd)
@@ -185,6 +195,8 @@ program
     // refuses those — see `clawo engines` for what is available.
     if (opts.customEngine)
         body.customEngine = opts.customEngine;
+    if (opts.acpAgent)
+        body.acpAgent = opts.acpAgent;
     if (opts.model)
         body.model = opts.model;
     if (opts.permissionMode)
@@ -271,19 +283,26 @@ program
     if (result.ok) {
         console.log(`Session '${body.name}' started!`);
         if (result.claudeSessionId)
-            console.log(`Claude Session ID: ${result.claudeSessionId}`);
+            console.log(`Engine session ID: ${result.claudeSessionId}`);
     }
     else
-        console.error(`Failed: ${result.error}`);
+        fail(result.error);
 });
 program
-    .command('session-send <name> <message>')
+    .command('session-send <name> [message]')
     .description('Send a message to a session')
+    .option('--message-file <file>', 'Read the message from a file (for long or dash-leading text)')
     .option('--effort <level>', 'Effort level')
     .option('--plan', 'Plan mode')
     .option('-t, --timeout <ms>', 'Timeout', '300000')
     .option('-s, --stream', 'Collect streaming chunks and include in output')
-    .action(async (name, message, opts) => {
+    .option('--json', 'Print the whole result as JSON')
+    .action(async (name, messageArg, opts) => {
+    const message = opts.messageFile ? fs.readFileSync(opts.messageFile, 'utf-8') : messageArg;
+    if (!message) {
+        fail('give a message, or --message-file');
+        return;
+    }
     const result = await api('/session/send', 'POST', {
         name,
         message,
@@ -292,14 +311,19 @@ program
         timeout: parseInt(opts.timeout),
         stream: opts.stream || undefined,
     });
-    if (result.ok) {
+    if (opts.json) {
+        console.log(JSON.stringify(result));
+        if (!result.ok)
+            process.exitCode = 1;
+    }
+    else if (result.ok) {
         console.log(result.output);
         if (opts.stream && Array.isArray(result.chunks) && result.chunks.length > 0) {
             console.log(`\n[${result.chunks.length} streaming chunks collected]`);
         }
     }
     else
-        console.error(`Failed: ${result.error}`);
+        fail(result.error);
 });
 program
     .command('session-stop <name>')
@@ -309,7 +333,7 @@ program
     if (r.ok)
         console.log(`Session '${name}' stopped.`);
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 program
     .command('session-list')
@@ -317,7 +341,7 @@ program
     .action(async () => {
     const r = await api('/session/list');
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     const sessions = r.sessions;
@@ -331,10 +355,17 @@ program
 program
     .command('session-status <name>')
     .description('Get session status')
-    .action(async (name) => {
+    .option('--json', 'Print the whole status as JSON')
+    .action(async (name, opts) => {
     const r = await api('/session/status', 'POST', { name });
+    if (opts.json) {
+        console.log(JSON.stringify(r));
+        if (!r.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     const s = r.stats;
@@ -343,10 +374,6 @@ program
     console.log(`  Tokens: ${s.tokensIn} in / ${s.tokensOut} out`);
     console.log(`  Uptime: ${s.uptime}s`);
 });
-/** Print an API failure the same way every command does. */
-function fail(r) {
-    console.error(`Failed: ${r.error}`);
-}
 program
     .command('engines')
     .description('List the community engine presets bundled with this package')
@@ -372,7 +399,9 @@ program
         console.log(`    verified by ${p.provenance.maintainer} against ${p.provenance.verifiedAgainst} on ${p.provenance.verifiedOn}`);
         if (p.provenance.smokeUrl)
             console.log(`    smoke: ${p.provenance.smokeUrl}`);
-        console.log(`    use:   clawo session-start my-session -e custom --custom-engine ${p.id}`);
+        console.log(p.acp
+            ? `    use:   clawo session-start my-session -e acp --acp-agent ${p.id}`
+            : `    use:   clawo session-start my-session -e custom --custom-engine ${p.id}`);
         console.log('');
     }
 });
@@ -401,7 +430,7 @@ program
         params.set('verified', 'false');
     const r = await api(`/runs?${params.toString()}`);
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     if (opts.json) {
@@ -418,7 +447,7 @@ program
     .action(async (name, pattern, opts) => {
     const r = await api('/session/grep', 'POST', { name, pattern, limit: parseInt(opts.limit) });
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     console.log(`Found ${r.count} match(es)`);
@@ -434,7 +463,7 @@ program
     if (r.ok)
         console.log('Compacted.');
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 // Agent management
 program
@@ -445,7 +474,7 @@ program
     const q = opts.cwd ? `?cwd=${encodeURIComponent(opts.cwd)}` : '';
     const r = await api(`/agents${q}`);
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     const agents = r.agents;
@@ -472,7 +501,7 @@ program
     if (r.ok)
         console.log(`Agent '${name}' created at: ${r.path}`);
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 // Skills
 program
@@ -483,7 +512,7 @@ program
     const q = opts.cwd ? `?cwd=${encodeURIComponent(opts.cwd)}` : '';
     const r = await api(`/skills${q}`);
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     const skills = r.skills;
@@ -512,7 +541,7 @@ program
     if (r.ok)
         console.log(`Skill '${name}' created at: ${r.path}`);
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 // Rules
 program
@@ -523,7 +552,7 @@ program
     const q = opts.cwd ? `?cwd=${encodeURIComponent(opts.cwd)}` : '';
     const r = await api(`/rules${q}`);
     if (!r.ok) {
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
         return;
     }
     const rules = r.rules;
@@ -562,7 +591,7 @@ program
     if (r.ok)
         console.log(`Rule '${name}' created at: ${r.path}`);
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 // Agent teams
 program
@@ -573,7 +602,7 @@ program
     if (r.ok)
         console.log(r.response || 'No team info');
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 program
     .command('session-team-send <name> <teammate> <message>')
@@ -583,7 +612,7 @@ program
     if (r.ok)
         console.log(r.output || 'Sent');
     else
-        console.error(`Failed: ${r.error}`);
+        fail(r.error);
 });
 // ─── workflow / verify ──────────────────────────────────────────────────────
 program
@@ -635,7 +664,15 @@ program
         if (run.error)
             console.log(`error: ${String(run.error)}`);
         for (const node of Object.values(run.nodes)) {
-            console.log(`  ${String(node.id).padEnd(18)} ${String(node.kind).padEnd(11)} ${node.state}`);
+            console.log(`  ${String(node.id).padEnd(18)} ${String(node.kind).padEnd(11)} ${String(node.state)}`);
+            // A goal runs for hours; its checkpoint is the only progress there is.
+            const g = node.kind === 'goal' ? node.data : undefined;
+            if (g) {
+                const err = g.lastError;
+                console.log(`    goal ${String(g.status)}  ${String(g.tokensUsed)} tokens  ${String(g.timeUsedSeconds)}s  ` +
+                    `resumes ${String(g.resumes)}  thread ${String(g.threadId)}` +
+                    (err ? `\n    last error: ${err.code ?? err.message}` : ''));
+            }
         }
         return;
     }
@@ -716,19 +753,19 @@ function collect(value, previous) {
  * `--check "node --test"` → a command check. Split on whitespace and run as
  * argv, never through a shell; anything that needs quoting goes in `--contract`.
  */
-function buildContract(checks, contractFile) {
+function buildContract(checks, contractFile, timeoutMs) {
     if (contractFile) {
         const raw = JSON.parse(fs.readFileSync(contractFile, 'utf-8'));
         if (!checks.length)
             return raw;
-        return { ...raw, checks: [...(raw.checks ?? []), ...checksFromFlags(checks)] };
+        return { ...raw, checks: [...(raw.checks ?? []), ...checksFromFlags(checks, timeoutMs)] };
     }
-    return checks.length ? { checks: checksFromFlags(checks) } : undefined;
+    return checks.length ? { checks: checksFromFlags(checks, timeoutMs) } : undefined;
 }
-function checksFromFlags(checks) {
+function checksFromFlags(checks, timeoutMs) {
     return checks.map((c, i) => {
         const [cmd, ...args] = c.trim().split(/\s+/);
-        return { id: `check-${i + 1}`, type: 'command', cmd, args };
+        return { id: `check-${i + 1}`, type: 'command', cmd, args, ...(timeoutMs ? { timeoutMs } : {}) };
     });
 }
 const RUN_DONE = new Set(['completed', 'failed', 'cancelled']);
@@ -946,5 +983,57 @@ program
     if (node?.output)
         console.log(`\n${node.output}`);
 });
+program
+    .command('goal')
+    .description('Run a Codex /goal on one codex-app thread, then have the runtime check it: goal → verify → repair')
+    .argument('[objective]', 'What Codex should achieve (or use --objective-file)')
+    .option('--objective-file <file>', 'Read the objective from a file')
+    .option('-m, --model <model>', "Codex model (default: codex's own)")
+    .option('--effort <level>', 'Reasoning effort')
+    .option('--sandbox <mode>', "Codex's own sandbox: read-only | workspace-write | danger-full-access")
+    .option('--launcher <arg>', 'Run codex under this command, one argv element per flag, e.g. --launcher ./sandbox.sh --launcher task --launcher "0 1"', collect, [])
+    .option('--thread <id>', 'Start on this existing codex thread: its goal is replaced, its history kept')
+    .option('--token-budget <n>', 'Tokens the goal may spend before it stops as budgetLimited')
+    .option('--goal-timeout <minutes>', 'Wall-clock budget for one goal pass (default: none)')
+    .option('-c, --check <command>', 'Acceptance check the runtime runs after the goal (repeatable)', collect, [])
+    .option('--check-timeout <minutes>', 'Timeout for each --check (default 10)')
+    .option('--contract <file>', 'Acceptance contract JSON file (merged with --check)')
+    .option('--max-repairs <n>', 'Times a red verdict sends the goal back to the same thread', '1')
+    .option('--cwd <dir>', 'Project directory', process.cwd())
+    .option('-w, --wait', 'Follow the run until it ends; exit 1 unless it completes')
+    .option('--json', 'Machine-readable output')
+    .action(async (objectiveArg, opts) => {
+    const { goalWorkflow } = await import('../src/kernel/templates/index.js');
+    const { GOAL_OBJECTIVE_MAX_CHARS } = await import('../src/kernel/nodes/goal.js');
+    const objective = opts.objectiveFile ? fs.readFileSync(opts.objectiveFile, 'utf-8').trim() : objectiveArg?.trim();
+    if (!objective) {
+        console.error('Error: give an objective, or --objective-file');
+        process.exitCode = 1;
+        return;
+    }
+    if ([...objective].length > GOAL_OBJECTIVE_MAX_CHARS) {
+        console.error(`Error: the objective is ${[...objective].length} characters; Codex accepts at most ${GOAL_OBJECTIVE_MAX_CHARS}. ` +
+            'Put the full brief in a file in the working directory and name that file in the objective.');
+        process.exitCode = 1;
+        return;
+    }
+    const minutes = (v) => (v ? Math.max(1, parseFloat(v)) * 60_000 : undefined);
+    const cwd = path.resolve(opts.cwd);
+    const contract = buildContract(opts.check, opts.contract, minutes(opts.checkTimeout));
+    const spec = goalWorkflow({
+        task: objective,
+        cwd,
+        contract: contract,
+        model: opts.model,
+        effort: opts.effort,
+        sandboxMode: opts.sandbox,
+        launcher: opts.launcher.length ? opts.launcher : undefined,
+        threadId: opts.thread,
+        tokenBudget: opts.tokenBudget ? parseInt(opts.tokenBudget, 10) : undefined,
+        goalTimeoutMs: minutes(opts.goalTimeout),
+        maxRepairs: Math.max(0, parseInt(opts.maxRepairs, 10) || 0),
+    });
+    await startWorkflow(spec, cwd, contract, opts);
+});
 program.parse();
 //# sourceMappingURL=cli.js.map