@zeroroot-ai/zerocool-claude 0.2.1 → 0.3.0

package/dist/build.js

@@ -12,7 +12,7 @@ import { openGibson } from "./session.js";
 import { stateDir, writeAmbient, writeLive } from "./state.js";
 import { registerComponentizeTool, registerEnrollTool } from "./tools/componentize.js";
 import { registerDelegationTools } from "./tools/delegate.js";
-import { gibsonFindingsBackend, localFindingsBackend, registerFindingTools } from "./tools/findings.js";
+import { gibsonFindingsBackend, localFindingsBackend, registerFindingTools, taskFindingsBackend } from "./tools/findings.js";
 import { registerGibsonTools } from "./tools/gibson-tools.js";
 import { registerMemoryTools } from "./tools/memory.js";
 import { failure, text } from "./tools/result.js";
@@ -49,7 +49,7 @@ function toolTable(server) {
 }
 export async function buildServer(env, cwd, deps = {}) {
     const settings = await loadSettings(env);
-    let gibson = await openGibson({ settings, log, ...deps.open });
+    let gibson = await openGibson({ settings, log, env, ...deps.open });
     const server = new McpServer({ name: "zerocool", version: "0.0.0" });
     let posture = [];
     const surface = {
@@ -64,12 +64,23 @@ export async function buildServer(env, cwd, deps = {}) {
     };
     registerStatusTool(server, () => gibson);
     registerComponentizeTool(server, cwd);
-    registerConnectTools(server, surface, env, cwd, deps);
+    // A sandboxed dispatch is fully decided by its launch; there is nothing to
+    // log in to or connect, and no host key to write.
+    if (gibson.mode !== "task")
+        registerConnectTools(server, surface, env, cwd, deps);
     posture = await collect(server, () => registerPosture(server, gibson, env, cwd));
     return surface;
 }
 /** The tools a posture carries, plus the handoff files for the hooks. */
 async function registerPosture(server, gibson, env, cwd) {
+    if (gibson.mode === "task" && gibson.live) {
+        // A sandboxed dispatch holds one grant and nothing else: the tools that
+        // run under it, and no component-side surface (enroll, delegation,
+        // tool discovery) because there is no component client.
+        registerFindingTools(server, gibson, taskFindingsBackend(gibson.live.harness));
+        registerMemoryTools(server, gibson);
+        return;
+    }
     if (!gibson.session) {
         registerFindingTools(server, gibson, localFindingsBackend(env.ZEROCOOL_FINDINGS_LOG ?? join(homedir(), ".zerocool", "findings.jsonl")));
         return;
@@ -186,7 +197,7 @@ function registerConnectTools(server, surface, env, cwd, deps) {
         });
         const previous = surface.current();
         await previous.close().catch(() => { });
-        const next = await openGibson({ settings: s, log, ...deps.open });
+        const next = await openGibson({ settings: s, log, env, ...deps.open });
         await surface.upgrade(next);
         const body = describeGibson(next);
         return next.mode === "live" ? text("connected", body) : failure("connected, but not live", body);

package/dist/claude-run.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Run Claude Code headless and read what it reports.
+ *
+ * `claude -p --output-format stream-json --verbose` writes one JSON event per
+ * line: a `system/init` first (tools, MCP servers, plugin errors), then
+ * `assistant` and `user` messages, and a final `result` with the text, the
+ * cost estimate, the turn count and the session id. The API key comes from
+ * `ANTHROPIC_API_KEY` in the environment: headless mode never reads a
+ * subscription login (code.claude.com/docs/en/headless).
+ */
+export interface ClaudeRunOptions {
+    goal: string;
+    cwd: string;
+    model?: string;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    appendSystemPrompt?: string;
+    /** MCP servers as `--mcp-config` JSON. */
+    mcpServers?: Record<string, {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    }>;
+    /** Tool patterns that run without a prompt, e.g. "mcp__gibson__*". */
+    allowedTools?: string[];
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    bin?: string;
+    onEvent?: (line: string) => void;
+}
+export interface ClaudeRunResult {
+    text: string;
+    sessionId: string;
+    isError: boolean;
+    numTurns: number;
+    costUsd: number;
+    /** MCP servers the session refused or failed to start, from system/init. */
+    mcpServerErrors: string[];
+    events: number;
+}
+/** Build the argv for one headless run. */
+export declare function claudeArgs(opts: ClaudeRunOptions): string[];
+/** Parse the NDJSON stream into the run result. */
+export declare function parseClaudeEvents(stdout: string): ClaudeRunResult;
+/** Spawn claude and collect its stream. Rejects on a non-zero exit or timeout. */
+export declare function runClaude(opts: ClaudeRunOptions): Promise<ClaudeRunResult>;

package/dist/claude-run.js

@@ -0,0 +1,118 @@
+import { spawn } from "node:child_process";
+/** Build the argv for one headless run. */
+export function claudeArgs(opts) {
+    const args = ["-p", opts.goal, "--output-format", "stream-json", "--verbose", "--no-session-persistence"];
+    // The sandbox is the permission boundary (gibson ADR-0016). Claude Code
+    // refuses this mode as root, so the image runs as an unprivileged user.
+    args.push("--permission-mode", "bypassPermissions");
+    if (opts.model)
+        args.push("--model", opts.model);
+    if (opts.maxTurns)
+        args.push("--max-turns", String(opts.maxTurns));
+    if (opts.maxBudgetUsd)
+        args.push("--max-budget-usd", String(opts.maxBudgetUsd));
+    if (opts.appendSystemPrompt)
+        args.push("--append-system-prompt", opts.appendSystemPrompt);
+    if (opts.mcpServers && Object.keys(opts.mcpServers).length > 0) {
+        args.push("--mcp-config", JSON.stringify({ mcpServers: opts.mcpServers }), "--strict-mcp-config");
+    }
+    if (opts.allowedTools && opts.allowedTools.length > 0)
+        args.push("--allowedTools", opts.allowedTools.join(","));
+    return args;
+}
+/** Parse the NDJSON stream into the run result. */
+export function parseClaudeEvents(stdout) {
+    const out = { text: "", sessionId: "", isError: false, numTurns: 0, costUsd: 0, mcpServerErrors: [], events: 0 };
+    const chunks = [];
+    let sawResult = false;
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // a stray log line, not an event
+        }
+        out.events += 1;
+        if (ev.session_id)
+            out.sessionId = ev.session_id;
+        if (ev.type === "system" && ev.subtype === "init") {
+            for (const e of ev.mcp_server_errors ?? [])
+                out.mcpServerErrors.push(`${e.name ?? "?"}: ${e.type ?? ""} ${e.message ?? ""}`.trim());
+            for (const s of ev.mcp_servers ?? [])
+                if (s.status && s.status !== "connected")
+                    out.mcpServerErrors.push(`${s.name ?? "?"}: ${s.status}`);
+        }
+        else if (ev.type === "assistant") {
+            for (const c of ev.message?.content ?? [])
+                if (c.type === "text" && c.text)
+                    chunks.push(c.text);
+        }
+        else if (ev.type === "result") {
+            sawResult = true;
+            out.isError = !!ev.is_error;
+            out.numTurns = ev.num_turns ?? 0;
+            out.costUsd = ev.total_cost_usd ?? 0;
+            if (typeof ev.result === "string" && ev.result)
+                out.text = ev.result;
+        }
+    }
+    if (!out.text)
+        out.text = chunks.join("");
+    if (!sawResult && out.events > 0)
+        out.isError = true;
+    return out;
+}
+/** Spawn claude and collect its stream. Rejects on a non-zero exit or timeout. */
+export async function runClaude(opts) {
+    const bin = opts.bin ?? opts.env?.ZEROCOOL_CLAUDE_BIN ?? process.env.ZEROCOOL_CLAUDE_BIN ?? "claude";
+    const args = claudeArgs(opts);
+    return await new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { cwd: opts.cwd, env: { ...process.env, ...opts.env }, stdio: ["ignore", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        let buf = "";
+        let timer;
+        if (opts.timeoutMs && opts.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                child.kill("SIGTERM");
+                reject(new Error(`claude run timed out after ${opts.timeoutMs}ms`));
+            }, opts.timeoutMs);
+        }
+        child.stdout.on("data", (d) => {
+            const s = d.toString();
+            out.push(s);
+            if (opts.onEvent) {
+                buf += s;
+                let i;
+                while ((i = buf.indexOf("\n")) >= 0) {
+                    const line = buf.slice(0, i);
+                    buf = buf.slice(i + 1);
+                    if (line.trim())
+                        opts.onEvent(line);
+                }
+            }
+        });
+        child.stderr.on("data", (d) => err.push(d.toString()));
+        child.on("error", (e) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(new Error(`cannot run ${bin}: ${e.message}`));
+        });
+        child.on("exit", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            if (buf.trim() && opts.onEvent)
+                opts.onEvent(buf);
+            const result = parseClaudeEvents(out.join(""));
+            if (code !== 0) {
+                reject(new Error(`claude exited ${code}: ${(err.join("").trim() || result.text || "no output").slice(0, 2000)}`));
+                return;
+            }
+            resolve(result);
+        });
+    });
+}

package/dist/mode.d.ts

@@ -8,12 +8,16 @@
  *    component grant. No memory writes: a memory is a World observation and
  *    the World is written under a mission (gibson ADR-0012).
  *  - `live`: checked in, and this session is a mission (gibson#1593, decision 9).
+ *  - `task`: a sandboxed dispatch (gibson ADR-0016). The launch injected the
+ *    per-dispatch grant and the task; there is no check-in and no live
+ *    mission to create, the mission already exists and this run is one of
+ *    its nodes. Reads and writes use that grant.
  *
  * The postures are one path with fewer tools at each step down, the same
  * fail-open shape as the opencode plugin: a coding agent that cannot reach its
  * platform is still a working coding agent.
  */
-export type Mode = "standalone" | "component" | "live";
+export type Mode = "standalone" | "component" | "live" | "task";
 export interface ModeDecision {
     mode: Mode;
     /** One line a person can act on. Empty when nothing is missing. */

package/dist/sandbox-run.d.ts

@@ -0,0 +1,26 @@
+import { type SandboxDispatch } from "@zeroroot-ai/sdk";
+import { runClaude, type ClaudeRunResult } from "./claude-run.js";
+/**
+ * The sandboxed-dispatch bin (gibson ADR-0016, #1621). gibson launches this
+ * image once per mission run with the task, the per-dispatch grant and the
+ * callback endpoint in the environment, and the tenant's own Anthropic key
+ * as ANTHROPIC_API_KEY (the manifest's `credentials`). It runs Claude Code
+ * headless with the Gibson MCP server attached in its task posture, streams
+ * the NDJSON events to stdout for the live console, and exits 0 when the
+ * run completed. Findings and memories reach the World through the
+ * callbacks; there is no result blob.
+ */
+export interface SandboxRunOptions {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    run?: typeof runClaude;
+    onEvent?: (line: string) => void;
+}
+/** Everything the child claude and its MCP server need from the launch. */
+export declare function sandboxEnv(d: SandboxDispatch, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** A `.js` path runs under node; anything else is a bin on PATH. */
+export declare function mcpServerSpec(bin: string): {
+    command: string;
+    args?: string[];
+};
+export declare function runSandbox(opts: SandboxRunOptions): Promise<ClaudeRunResult>;

package/dist/sandbox-run.js

@@ -0,0 +1,42 @@
+import { readSandboxDispatch, SANDBOX_ENV } from "@zeroroot-ai/sdk";
+import { runClaude } from "./claude-run.js";
+/** Everything the child claude and its MCP server need from the launch. */
+export function sandboxEnv(d, env) {
+    return {
+        ...env,
+        [SANDBOX_ENV.grant]: d.grant,
+        [SANDBOX_ENV.callbackEndpoint]: d.callbackEndpoint,
+        [SANDBOX_ENV.missionId]: d.missionId,
+        [SANDBOX_ENV.missionRunId]: d.missionRunId,
+        [SANDBOX_ENV.agentRunId]: d.agentRunId,
+        ...(d.traceId ? { [SANDBOX_ENV.traceId]: d.traceId } : {}),
+    };
+}
+/** A `.js` path runs under node; anything else is a bin on PATH. */
+export function mcpServerSpec(bin) {
+    return bin.endsWith(".js") ? { command: "node", args: [bin] } : { command: bin };
+}
+export async function runSandbox(opts) {
+    const d = readSandboxDispatch(opts.env);
+    if (!opts.env.ANTHROPIC_API_KEY) {
+        throw new Error("ANTHROPIC_API_KEY is not set. Headless Claude Code runs on an API key only; the catalog manifest " +
+            "declares it under credentials and the launch injects the tenant's own (gibson#1621, decision 12).");
+    }
+    const env = sandboxEnv(d, opts.env);
+    const run = opts.run ?? runClaude;
+    return await run({
+        goal: d.goal,
+        cwd: opts.cwd,
+        ...(opts.env.ZEROCOOL_CLAUDE_MODEL ? { model: opts.env.ZEROCOOL_CLAUDE_MODEL } : {}),
+        maxTurns: Number(opts.env.ZEROCOOL_CLAUDE_MAX_TURNS ?? 200),
+        ...(opts.env.ZEROCOOL_CLAUDE_MAX_BUDGET_USD ? { maxBudgetUsd: Number(opts.env.ZEROCOOL_CLAUDE_MAX_BUDGET_USD) } : {}),
+        appendSystemPrompt: "You run inside a Gibson mission sandbox. Record every real security finding with submit_finding, " +
+            "keep facts worth carrying to later runs with remember, and read prior context with recall. " +
+            "Work until the goal is met or clearly unreachable, then state the outcome.",
+        mcpServers: { gibson: mcpServerSpec(opts.env.ZEROCOOL_CLAUDE_MCP_BIN ?? "zerocool-claude-mcp") },
+        allowedTools: ["mcp__gibson__*"],
+        timeoutMs: Number(opts.env.ZEROCOOL_CLAUDE_TIMEOUT_MS ?? 0),
+        env,
+        ...(opts.onEvent ? { onEvent: opts.onEvent } : {}),
+    });
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/sandbox.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { runSandbox } from "./sandbox-run.js";
+/**
+ * The sandboxed-dispatch bin. Runs unconditionally: npm installs it as a
+ * symlink named zerocool-claude-dispatch. Library code lives in sandbox-run.ts.
+ */
+async function main() {
+    const log = (l) => process.stderr.write(`[zerocool-claude-dispatch] ${l}\n`);
+    let result;
+    try {
+        result = await runSandbox({
+            env: process.env,
+            cwd: process.env.ZEROCOOL_WORKSPACE ?? process.cwd(),
+            onEvent: (line) => process.stdout.write(`${line}\n`),
+        });
+    }
+    catch (e) {
+        log(`run failed: ${e.message}`);
+        process.exit(1);
+        return;
+    }
+    if (result.mcpServerErrors.length > 0)
+        log(`MCP: ${result.mcpServerErrors.join("; ")}`);
+    log(`done turns=${result.numTurns} cost_usd=${result.costUsd.toFixed(4)} session=${result.sessionId || "-"} error=${result.isError}`);
+    process.exit(result.isError ? 1 : 0);
+}
+main().catch((e) => {
+    process.stderr.write(`[zerocool-claude-dispatch] fatal: ${e.message}\n`);
+    process.exit(1);
+});

package/dist/session.d.ts

@@ -18,6 +18,8 @@ export interface Gibson {
 export interface OpenGibsonOptions {
     settings: Settings;
     log: (line: string) => void;
+    /** The process environment, for the sandboxed-dispatch contract. */
+    env?: NodeJS.ProcessEnv;
     /** Test seams. */
     connect?: typeof connectGibson;
     start?: typeof startLiveMission;

package/dist/session.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { componentKnowledge, connectGibson, startLiveMission, taskKnowledge, } from "@zeroroot-ai/sdk";
+import { componentKnowledge, connectGibson, readSandboxDispatch, sandboxHarness, SANDBOX_ENV, startLiveMission, taskKnowledge, } from "@zeroroot-ai/sdk";
 import { decideMode } from "./mode.js";
 import { trustCA } from "./tls.js";
 export { DEFAULT_AGENT_NAME } from "./config.js";
@@ -9,6 +9,10 @@ export { DEFAULT_AGENT_NAME } from "./config.js";
  */
 export async function openGibson(opts) {
     const { settings, log } = opts;
+    const env = opts.env ?? {};
+    if (env[SANDBOX_ENV.grant] && env[SANDBOX_ENV.callbackEndpoint]) {
+        return openSandboxTask(env, settings, log, opts.trust);
+    }
     const { hostKeyPath, agentName } = settings;
     const hostKeyExists = (opts.hostKeyExists ?? existsSync)(hostKeyPath);
     const decision = decideMode({ platformURL: settings.platformURL, bootstrapToken: settings.bootstrapToken, hostKeyExists, targetId: settings.targetId }, hostKeyPath);
@@ -101,3 +105,34 @@ export async function openGibson(opts) {
         },
     };
 }
+/**
+ * The task posture: this process is a sandboxed dispatch. The launch already
+ * decided everything; the plugin only opens the task harness from the grant
+ * and serves the tools that run under it. No host key, no check-in, no
+ * mission creation, and nothing to fail open to: a sandbox without a
+ * usable grant has no reason to exist, so this throws.
+ */
+async function openSandboxTask(env, settings, log, trust) {
+    const d = readSandboxDispatch(env);
+    if (settings.caCertPath)
+        await (trust ?? trustCA)(settings.caCertPath).catch((e) => log(`[zerocool-claude] CA not loaded: ${e.message}`));
+    const harness = sandboxHarness(d, { insecure: settings.callbackInsecure });
+    const live = {
+        missionId: d.missionId,
+        workId: d.missionRunId,
+        harness,
+        // The sandbox reports completion by exiting; the launcher owns the node.
+        end: async () => harness.stop(),
+    };
+    log(`[zerocool-claude] task posture: mission ${d.missionId} run ${d.missionRunId}; reads and writes use the dispatch grant`);
+    return {
+        mode: "task",
+        reason: "",
+        agentName: settings.agentName,
+        hostKeyPath: settings.hostKeyPath,
+        settings,
+        live,
+        knowledge: taskKnowledge(harness),
+        close: async () => harness.stop(),
+    };
+}

package/dist/tools/findings.d.ts

@@ -1,5 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type Finding } from "@zeroroot-ai/sdk";
+import { type Finding, type TaskHarness } from "@zeroroot-ai/sdk";
 import type { Gibson } from "../session.js";
 export interface FindingsBackend {
     submit(f: Finding): Promise<string>;
@@ -7,6 +7,12 @@ export interface FindingsBackend {
 }
 /** Platform backend: the finding lands in the tenant knowledge graph. */
 export declare function gibsonFindingsBackend(g: Gibson): FindingsBackend;
+/**
+ * Task backend: the callback service's typed SubmitFinding, under the
+ * dispatch grant. Fields map from the SDK's JSON finding onto
+ * gibson.types.v1.Finding; the daemon assigns the id and the mission.
+ */
+export declare function taskFindingsBackend(harness: TaskHarness): FindingsBackend;
 /** Standalone backend: an append-only JSONL log. */
 export declare function localFindingsBackend(path: string): FindingsBackend;
 /**

package/dist/tools/findings.js

@@ -9,6 +9,41 @@ export function gibsonFindingsBackend(g) {
     const component = g.session.clients.component;
     return { submit: (f) => submitFinding(component, f), describe: () => "the tenant Gibson graph" };
 }
+/**
+ * Task backend: the callback service's typed SubmitFinding, under the
+ * dispatch grant. Fields map from the SDK's JSON finding onto
+ * gibson.types.v1.Finding; the daemon assigns the id and the mission.
+ */
+export function taskFindingsBackend(harness) {
+    const severity = (s) => ({ critical: 1, high: 2, medium: 3, low: 4, info: 5 })[s] ?? 0;
+    return {
+        submit: async (f) => {
+            const res = await harness.client.submitFinding({
+                context: harness.context,
+                finding: {
+                    id: f.id,
+                    missionId: f.mission_id,
+                    agentName: f.agent_name,
+                    title: f.title,
+                    description: f.description,
+                    category: f.category,
+                    severity: severity(f.severity),
+                    confidence: f.confidence,
+                    remediation: f.remediation ?? "",
+                    targetId: f.target_id ?? "",
+                    tags: f.tags ?? [],
+                    evidence: (f.evidence ?? []).map((e) => ({ type: e.type, title: e.title, content: e.content })),
+                },
+            });
+            if (res.error)
+                throw new Error(`SubmitFinding refused: ${res.error.message}`);
+            // The callback acknowledges without an id; the finding keeps the one
+            // newFinding minted, which is what the daemon stored.
+            return f.id;
+        },
+        describe: () => "the tenant Gibson graph (dispatch grant)",
+    };
+}
 /** Standalone backend: an append-only JSONL log. */
 export function localFindingsBackend(path) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool-claude",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Claude Code plugin: Gibson platform integration (zerocool). The session is a live mission. Memory, knowledge, findings, tools, delegation. The model stays on your Claude subscription.",
   "license": "MIT",
   "repository": {
@@ -26,12 +26,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@zeroroot-ai/sdk": "^0.6.1",
+    "@zeroroot-ai/sdk": "^0.7.0",
     "zod": "^4.4.3"
   },
   "bin": {
     "zerocool-claude-mcp": "dist/server.js",
-    "zerocool-claude-hook": "dist/hook.js"
+    "zerocool-claude-hook": "dist/hook.js",
+    "zerocool-claude-dispatch": "dist/sandbox.js"
   },
   "publishConfig": {
     "access": "public"