@zeroroot-ai/zerocool 0.2.0

package/dist/opencode-run.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Drive opencode headless — the external driver half of the `kind=agent`
+ * dispatched shape (zerocool-plugins#33, owner decision 2026-08-15: Option B).
+ *
+ * `opencode run --format json` emits NDJSON on stdout, one event per line. The
+ * shape below is not inferred from docs; it is what opencode 1.18.13 actually
+ * printed:
+ *
+ *   {"type":"step_start","timestamp":…,"sessionID":"ses_…","part":{…}}
+ *   {"type":"text","timestamp":…,"sessionID":"ses_…","part":{"type":"text","text":"Hi there!…"}}
+ *   {"type":"step_finish","timestamp":…,"sessionID":"ses_…",
+ *    "part":{"reason":"stop","tokens":{"total":9787,"input":8740,"output":23,…},"cost":0}}
+ *
+ * Parsing is split from spawning on purpose: {@link parseOpencodeEvents} is pure
+ * and is tested against those exact bytes, so a change in opencode's output
+ * fails a unit test instead of a dispatched mission.
+ *
+ * The parser is deliberately tolerant. A line that is not JSON, or an event type
+ * this version does not know, is skipped rather than fatal — opencode is free to
+ * add event types, and a mission node must not fail because it did.
+ */
+/** Token accounting for one run, as reported by `step_finish`. */
+export interface OpencodeTokens {
+    total: number;
+    input: number;
+    output: number;
+    reasoning: number;
+}
+/** What one headless opencode run produced. */
+export interface OpencodeRunResult {
+    /** opencode's session id — pass it back as `sessionId` to continue this session. */
+    sessionId: string;
+    /** Every `text` part, concatenated in order. The agent's answer. */
+    text: string;
+    /** `step_finish.reason`, e.g. "stop". Empty when the run produced no finish event. */
+    finishReason: string;
+    tokens: OpencodeTokens;
+    cost: number;
+    /** How many NDJSON events parsed. Useful to tell "no output" from "not JSON". */
+    events: number;
+}
+/** Parse the NDJSON `opencode run --format json` writes to stdout. */
+export declare function parseOpencodeEvents(stdout: string): OpencodeRunResult;
+export interface OpencodeRunOptions {
+    /** The natural-language objective — the mission node's Task.goal. */
+    goal: string;
+    /** Working directory. opencode edits files here, so it is the run's workspace. */
+    dir: string;
+    /** `provider/model`, e.g. `gibson/default`. Omitted lets opencode choose. */
+    model?: string;
+    /** Continue an earlier opencode session instead of starting a new one. */
+    sessionId?: string;
+    /** Hard deadline. The child is killed when it elapses. */
+    timeoutMs?: number;
+    /** Extra environment for the child, merged over the parent's. */
+    env?: NodeJS.ProcessEnv;
+    /** Binary to run. Overridable for tests and for a pinned install. */
+    bin?: string;
+}
+/** Build the argv for a headless run. Exported so a test can assert it. */
+export declare function opencodeArgs(opts: OpencodeRunOptions): string[];
+/**
+ * Run opencode headless once and return what it produced.
+ *
+ * Throws on a non-zero exit or a timeout. The caller is
+ * {@link ../serve-agent.ts}'s handler, and `startAgentWorker` turns a throw into
+ * an in-band `ExecuteResponse.error` — so a crashed run fails its mission node
+ * with a reason instead of stalling it until the dispatch times out.
+ */
+export declare function runOpencode(opts: OpencodeRunOptions): Promise<OpencodeRunResult>;

package/dist/opencode-run.js

@@ -0,0 +1,102 @@
+import { spawn } from "node:child_process";
+/** Parse the NDJSON `opencode run --format json` writes to stdout. */
+export function parseOpencodeEvents(stdout) {
+    const result = {
+        sessionId: "",
+        text: "",
+        finishReason: "",
+        tokens: { total: 0, input: 0, output: 0, reasoning: 0 },
+        cost: 0,
+        events: 0,
+    };
+    const chunks = [];
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // not an event line (a stray log, a partial write) — not fatal
+        }
+        result.events += 1;
+        if (event.sessionID)
+            result.sessionId = event.sessionID;
+        if (event.type === "text" && typeof event.part?.text === "string") {
+            chunks.push(event.part.text);
+        }
+        else if (event.type === "step_finish") {
+            if (event.part?.reason)
+                result.finishReason = event.part.reason;
+            if (typeof event.part?.cost === "number")
+                result.cost += event.part.cost;
+            const t = event.part?.tokens;
+            if (t) {
+                // Summed, not replaced: a multi-step run emits one step_finish per step
+                // and the mission's cost is all of them, not the last one.
+                result.tokens.total += t.total ?? 0;
+                result.tokens.input += t.input ?? 0;
+                result.tokens.output += t.output ?? 0;
+                result.tokens.reasoning += t.reasoning ?? 0;
+            }
+        }
+    }
+    result.text = chunks.join("");
+    return result;
+}
+/** Build the argv for a headless run. Exported so a test can assert it. */
+export function opencodeArgs(opts) {
+    const args = ["run", "--format", "json", "--dir", opts.dir];
+    // Unattended by definition: there is no human to answer a permission prompt,
+    // and a run that blocks on one burns its whole timeout and then fails.
+    args.push("--auto");
+    if (opts.model)
+        args.push("--model", opts.model);
+    if (opts.sessionId)
+        args.push("--session", opts.sessionId);
+    // The goal goes last: `message..` is a variadic positional, so anything after
+    // it would be swallowed as more message.
+    args.push(opts.goal);
+    return args;
+}
+/**
+ * Run opencode headless once and return what it produced.
+ *
+ * Throws on a non-zero exit or a timeout. The caller is
+ * {@link ../serve-agent.ts}'s handler, and `startAgentWorker` turns a throw into
+ * an in-band `ExecuteResponse.error` — so a crashed run fails its mission node
+ * with a reason instead of stalling it until the dispatch times out.
+ */
+export async function runOpencode(opts) {
+    const bin = opts.bin ?? process.env.ZEROCOOL_OPENCODE_BIN ?? "opencode";
+    const args = opencodeArgs(opts);
+    return await new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            cwd: opts.dir,
+            env: { ...process.env, ...opts.env },
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(opts.timeoutMs && opts.timeoutMs > 0 ? { timeout: opts.timeoutMs, killSignal: "SIGTERM" } : {}),
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (e) => reject(new Error(`could not run ${bin}: ${e.message}`)));
+        child.on("close", (code, signal) => {
+            if (signal) {
+                // Killed by the timeout. Say so with the deadline, because "terminated"
+                // alone sends whoever reads the mission looking for a crash.
+                reject(new Error(`opencode timed out after ${opts.timeoutMs}ms (killed with ${signal})`));
+                return;
+            }
+            if (code !== 0) {
+                const tail = stderr.trim().split("\n").slice(-5).join("; ");
+                reject(new Error(`opencode exited ${code}${tail ? `: ${tail}` : ""}`));
+                return;
+            }
+            resolve(parseOpencodeEvents(stdout));
+        });
+    });
+}

package/dist/serve-agent.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * zerocool-agent — run zerocool headless as a daemon-driven `kind=agent`.
+ *
+ * The sibling of `zerocool-serve`, and the other half of dispatched mode. Where
+ * `zerocool-serve` registers a TOOL — one named capability with declared
+ * parameters — this registers an AGENT: a goal-driven executor. A mission node
+ * hands over a Task, and this process pursues it by driving opencode headless
+ * for as long as the dispatch allows.
+ *
+ * This is zerocool-plugins#33, Option B, per the owner decision of 2026-08-15.
+ * It does not reopen ADR-0005: the driver is a bin in this package, not a fork
+ * of opencode, which is exactly the carve-out ADR-0005 wrote. See
+ * `docs/adr/0006-kind-agent-dispatched-shape.md`.
+ *
+ * Usage (after `gibson agent enroll --kind agent --name zerocool`):
+ *
+ *   GIBSON_PLATFORM_URL=https://api.example:30443 \
+ *   GIBSON_BOOTSTRAP_TOKEN=<one-time token> \
+ *   ZEROCOOL_AGENT_NAME=zerocool \
+ *   ZEROCOOL_WORKSPACE=/srv/work \
+ *     zerocool-agent
+ *
+ * The token is needed for the first check-in only; afterwards the persisted host
+ * key re-registers this host without human involvement (ADR-0045).
+ */
+import { type AgentInvocation, type AgentOutcome } from "@zeroroot-ai/sdk";
+/**
+ * Turn one dispatched Task into one headless opencode run.
+ *
+ * Exported for tests: the loop around it is `startAgentWorker`'s, and the value
+ * of this function is entirely in what it maps onto and off the wire.
+ */
+export declare function agentHandler(item: AgentInvocation, opts: {
+    workspace: string;
+    model?: string;
+}): Promise<AgentOutcome>;

package/dist/serve-agent.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * zerocool-agent — run zerocool headless as a daemon-driven `kind=agent`.
+ *
+ * The sibling of `zerocool-serve`, and the other half of dispatched mode. Where
+ * `zerocool-serve` registers a TOOL — one named capability with declared
+ * parameters — this registers an AGENT: a goal-driven executor. A mission node
+ * hands over a Task, and this process pursues it by driving opencode headless
+ * for as long as the dispatch allows.
+ *
+ * This is zerocool-plugins#33, Option B, per the owner decision of 2026-08-15.
+ * It does not reopen ADR-0005: the driver is a bin in this package, not a fork
+ * of opencode, which is exactly the carve-out ADR-0005 wrote. See
+ * `docs/adr/0006-kind-agent-dispatched-shape.md`.
+ *
+ * Usage (after `gibson agent enroll --kind agent --name zerocool`):
+ *
+ *   GIBSON_PLATFORM_URL=https://api.example:30443 \
+ *   GIBSON_BOOTSTRAP_TOKEN=<one-time token> \
+ *   ZEROCOOL_AGENT_NAME=zerocool \
+ *   ZEROCOOL_WORKSPACE=/srv/work \
+ *     zerocool-agent
+ *
+ * The token is needed for the first check-in only; afterwards the persisted host
+ * key re-registers this host without human involvement (ADR-0045).
+ */
+import { connectGibson, registerInstance, startAgentWorker, startHeartbeat, } from "@zeroroot-ai/sdk";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runOpencode } from "./opencode-run.js";
+/** Version reported to the daemon on registration. */
+const VERSION = "0.1.0";
+/**
+ * Turn one dispatched Task into one headless opencode run.
+ *
+ * Exported for tests: the loop around it is `startAgentWorker`'s, and the value
+ * of this function is entirely in what it maps onto and off the wire.
+ */
+export async function agentHandler(item, opts) {
+    if (!item.goal.trim()) {
+        // A dispatch with no goal is a defect upstream, not something to guess at.
+        // Failing loudly beats running opencode against an empty prompt and
+        // reporting whatever it says back as a mission result.
+        throw new Error(`work ${item.workId} carried no task goal`);
+    }
+    const run = await runOpencode({
+        goal: item.goal,
+        dir: opts.workspace,
+        model: opts.model,
+        // Continuity across dispatches: the daemon's agent_run_id is stable for a
+        // retried node, but opencode's own session id is what carries the
+        // conversation. It is returned in metadata below so a follow-up dispatch can
+        // pass it back — see the ADR on why this is not yet automatic.
+        sessionId: item.context.opencode_session_id,
+        timeoutMs: item.timeoutMs,
+        env: {
+            // The task-scoped callback seam. gibson mints these per dispatch
+            // (`internal/engine/harness/implementation.go:1205-1210`) so a dispatched
+            // run reaches the harness as the TASK rather than as this component.
+            // Passed through to the child now; the plugin consuming them in
+            // preference to the host-key grant is tracked in the ADR as the next
+            // slice — today the child still authenticates as the component, which is
+            // broader authority than the dispatch intends.
+            ...(item.callbackEndpoint ? { GIBSON_CALLBACK_ENDPOINT: item.callbackEndpoint } : {}),
+            ...(item.callbackToken ? { GIBSON_CALLBACK_TOKEN: item.callbackToken } : {}),
+            // Provenance, so anything the child emits can be correlated to this run.
+            ...(item.missionRunId ? { GIBSON_MISSION_RUN_ID: item.missionRunId } : {}),
+            ...(item.agentRunId ? { GIBSON_AGENT_RUN_ID: item.agentRunId } : {}),
+            ...(item.traceId ? { GIBSON_TRACE_ID: item.traceId } : {}),
+        },
+    });
+    return {
+        output: run.text,
+        metadata: {
+            opencode_session_id: run.sessionId,
+            finish_reason: run.finishReason,
+            tokens_total: String(run.tokens.total),
+            tokens_output: String(run.tokens.output),
+            cost: String(run.cost),
+        },
+    };
+}
+async function main() {
+    const platformURL = process.env.GIBSON_PLATFORM_URL;
+    if (!platformURL) {
+        console.error("[zerocool-agent] GIBSON_PLATFORM_URL is required");
+        process.exit(2);
+    }
+    const agentName = process.env.ZEROCOOL_AGENT_NAME ?? "zerocool";
+    const workspace = process.env.ZEROCOOL_WORKSPACE ?? process.cwd();
+    const model = process.env.ZEROCOOL_MODEL;
+    const hostKeyPath = process.env.GIBSON_HOST_KEY_PATH ?? join(homedir(), ".zerocool", "host.key");
+    const checkedIn = existsSync(hostKeyPath);
+    const session = await connectGibson({
+        platformURL,
+        daemonURL: process.env.GIBSON_DAEMON_URL,
+        bootstrapToken: checkedIn ? undefined : process.env.GIBSON_BOOTSTRAP_TOKEN,
+        hostKeyPath,
+        agentName,
+        agentMode: "dispatched",
+        agent: { name: agentName, version: VERSION, capabilities: ["code"] },
+    });
+    // Register the AGENT identity the harness dispatches `agent_execute` to, and
+    // hold the ONE shared InstanceRef the heartbeat and work loop both use —
+    // renewal is single-flight inside the ref, so an expired instance is
+    // re-registered once and both loops adopt the new id (sdk-ts#6).
+    const ref = await registerInstance(session.clients.component, "agent", {
+        name: agentName,
+        version: VERSION,
+        capabilities: ["code"],
+        metadata: { served_by: "zerocool", workspace },
+    });
+    const stopHeartbeat = startHeartbeat(session.clients.component, ref, (e) => console.error(`[zerocool-agent] heartbeat: ${e.message}`));
+    console.error(`[zerocool-agent] registered agent "${agentName}" (instance=${ref.current()}) ` +
+        `workspace=${workspace}; polling for work`);
+    const stop = startAgentWorker(session.clients.component, ref, {
+        onWork: (item) => console.error(`[zerocool-agent] claimed work ${item.workId} run=${item.agentRunId || "-"} ` +
+            `timeout=${item.timeoutMs}ms goal=${JSON.stringify(item.goal.slice(0, 120))}`),
+        onError: (e) => console.error(`[zerocool-agent] ${e.message}`),
+        handler: async (item) => {
+            const outcome = await agentHandler(item, { workspace, model });
+            console.error(`[zerocool-agent] finished ${item.workId} reason=${outcome.metadata?.finish_reason ?? "-"} ` +
+                `tokens=${outcome.metadata?.tokens_total ?? "-"}`);
+            return outcome;
+        },
+    });
+    const shutdown = () => {
+        console.error("[zerocool-agent] stopping");
+        stop();
+        stopHeartbeat();
+        session.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+// Only run when executed as the bin, so the handler above stays importable.
+if (process.argv[1]?.endsWith("serve-agent.js")) {
+    main().catch((e) => {
+        console.error(`[zerocool-agent] fatal: ${e.message}`);
+        process.exit(1);
+    });
+}

package/dist/serve.d.ts

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

package/dist/serve.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * zerocool-serve — run zerocool headless as a dispatched fleet component.
+ *
+ * The inverse of the opencode plugin: instead of a human driving the agent, the
+ * daemon drives it. The process checks in with the Capability Grant handshake,
+ * registers as a TOOL, and then blocks on PollWork until a mission node sends
+ * it something to do.
+ *
+ * WHY kind=tool. Every kind receives dispatched work now — agent nodes included
+ * (gibson#1197 / ADR-0011) — so this is a choice, not a limitation. A tool is
+ * the honest description of what this process offers: one named capability with
+ * declared parameters, invoked by whoever needs it. Registering as an agent
+ * would promise a goal-driven executor with its own reasoning loop, which is
+ * what the opencode plugin does interactively, not what this server does.
+ *
+ * Usage (after `gibson agent enroll --kind tool --name <name>`):
+ *
+ *   GIBSON_PLATFORM_URL=https://api.example:30443 \
+ *   GIBSON_BOOTSTRAP_TOKEN=<one-time token> \
+ *   ZEROCOOL_TOOL_NAME=zerocool-http \
+ *     zerocool-serve            # the package's bin; node dist/serve.js works too
+ *
+ * The token is needed for the first check-in only; afterwards the persisted
+ * host key re-registers this host without human involvement (ADR-0045).
+ */
+import { connectGibson, registerInstance, startHeartbeat, startWorker, } from "@zeroroot-ai/sdk";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { httpProbeHandler } from "./http-probe.js";
+async function main() {
+    const platformURL = process.env.GIBSON_PLATFORM_URL;
+    if (!platformURL) {
+        console.error("[zerocool-serve] GIBSON_PLATFORM_URL is required");
+        process.exit(2);
+    }
+    const toolName = process.env.ZEROCOOL_TOOL_NAME ?? "zerocool-http";
+    const hostKeyPath = process.env.GIBSON_HOST_KEY_PATH ?? join(homedir(), ".zerocool", "host.key");
+    const checkedIn = existsSync(hostKeyPath);
+    const session = await connectGibson({
+        platformURL,
+        daemonURL: process.env.GIBSON_DAEMON_URL,
+        // One-time token on first check-in only; the host key carries every later start.
+        bootstrapToken: checkedIn ? undefined : process.env.GIBSON_BOOTSTRAP_TOKEN,
+        hostKeyPath,
+        agentName: toolName,
+        agentMode: "dispatched",
+        agent: { name: toolName, version: "0.1.0", capabilities: ["http_probe"] },
+    });
+    // Register under the kind that actually receives work. connectGibson has
+    // already registered an agent identity for the session; this adds the tool
+    // identity the harness dispatches to. registerInstance returns the ONE
+    // shared InstanceRef the heartbeat and the work loop both use — renewal is
+    // single-flight inside the ref, so an expired instance is re-registered
+    // once and both loops adopt the new id (sdk-ts#6).
+    const ref = await registerInstance(session.clients.component, "tool", {
+        name: toolName,
+        version: "0.1.0",
+        capabilities: ["http_probe"],
+        metadata: { served_by: "zerocool" },
+    });
+    // Heartbeat the TOOL identity, not just the session's agent identity. The
+    // daemon expires an instance that stops heartbeating and PollWork then answers
+    // NotFound forever — a process that looks healthy while being invisible to the
+    // fleet.
+    const stopHeartbeat = startHeartbeat(session.clients.component, ref, (e) => console.error(`[zerocool-serve] heartbeat: ${e.message}`));
+    console.error(`[zerocool-serve] registered tool "${toolName}" (instance=${ref.current()}); polling for work`);
+    const stop = startWorker(session.clients.component, ref, {
+        onWork: (item) => console.error(`[zerocool-serve] claimed work ${item.workId} (${item.workType}) input=${JSON.stringify(item.input)}`),
+        onError: (e) => console.error(`[zerocool-serve] ${e.message}`),
+        // Handlers get the session's clients: the callback-harness seam for
+        // LLM/tools/findings/knowledge during a dispatched run.
+        handler: async (item) => {
+            const result = await httpProbeHandler(item, session.clients);
+            console.error(`[zerocool-serve] ${result.url} -> ${result.status} ${result.statusText}, ` +
+                `server=${result.server ?? "-"}, ${result.bytes} bytes in ${result.elapsedMs}ms`);
+            return result;
+        },
+    });
+    const shutdown = () => {
+        console.error("[zerocool-serve] stopping");
+        stop();
+        stopHeartbeat();
+        session.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((e) => {
+    console.error(`[zerocool-serve] fatal: ${e.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@zeroroot-ai/zerocool",
+  "version": "0.2.0",
+  "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@zeroroot-ai/sdk": "git+https://github.com/zeroroot-ai/sdk-ts.git#v0.4.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.11"
+  },
+  "bin": {
+    "zerocool-serve": "dist/serve.js",
+    "zerocool-agent": "dist/serve-agent.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\""
+  }
+}