@zeroroot-ai/zerocool 0.2.2 → 0.3.1

package/dist/dispatch.d.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * zerocool-dispatch — one sandboxed dispatched run, then exit.
+ *
+ * The third dispatched shape, and the one gibson launches (zerocool-plugins#57,
+ * gibson#1596, ADR-0016). `zerocool-agent` and `zerocool-serve` are long-lived
+ * hosts that enroll once, keep a host key, and POLL the daemon for work. This is
+ * the opposite: gibson runs an untrusted agent by launching an ephemeral setec
+ * sandbox per mission run and injecting the run's credentials as environment. So
+ * there is no enrollment, no host key, and no poll loop — the task and the grant
+ * are already in the environment when the process starts, and the process serves
+ * exactly one dispatch and exits so the sandbox is torn down.
+ *
+ * WHAT REPLACES THE BOOTSTRAP TOKEN. The poll-loop shapes authenticate as a
+ * long-lived COMPONENT: a human mints a one-time `GIBSON_BOOTSTRAP_TOKEN`, the
+ * first run trades it for a persistent host key, and every later run re-registers
+ * with that key (ADR-0045). A sandboxed run has neither. It authenticates with
+ * the PER-DISPATCH capability grant gibson mints for this run and injects as
+ * `GIBSON_CALLBACK_ENDPOINT` + `GIBSON_CG_JWT`. That grant carries exactly the
+ * authority of this dispatch, so this process never reads a bootstrap token and
+ * never touches a host key.
+ *
+ * THE CALLBACKS ARE GRANT-AUTHENTICATED. This process drives `opencode run`
+ * headless and passes the per-dispatch grant to the child (see
+ * {@link dispatchChildEnv}). The child's mission callbacks — findings, tool
+ * calls, knowledge reads — then reach the daemon's harness callback listener as
+ * the TASK, on the injected grant, not as some enrolled component (see
+ * `knowledge-source.ts`).
+ *
+ * THE OUTPUT IS A LIVE NDJSON STREAM. Every event opencode prints is forwarded
+ * to this process's stdout as it arrives, so the daemon can stream the run to the
+ * read-only console (a later slice consumes it). The last line is the terminal
+ * result. stdout is therefore a clean event stream — the driver's own logs go to
+ * stderr — and a clean exit lets the sandbox tear down.
+ *
+ * Environment (injected by the sandbox launch):
+ *
+ * These names are gibson's canonical dispatch contract — the constants in gibson
+ * `internal/engine/harness/sandboxed/agent.go` (envAgent*). This process conforms
+ * to them; it does not define its own.
+ *
+ *   GIBSON_CALLBACK_ENDPOINT   per-dispatch harness callback dial target (required)
+ *   GIBSON_CG_JWT              per-dispatch capability grant (CG-JWT)    (required)
+ *   GIBSON_AGENT_TASK_B64      base64 protojson gibson.types.v1.Task     (required)
+ *   GIBSON_MODEL               provider/model resolved for the tenant at dispatch
+ *   GIBSON_CALLBACK_INSECURE   "1" to dial the callback listener without TLS (kind)
+ *   GIBSON_MISSION_ID / GIBSON_MISSION_RUN_ID / GIBSON_AGENT_RUN_ID   provenance
+ *   ZEROCOOL_WORKSPACE         working directory (defaults to the cwd)
+ *   GIBSON_OPENCODE_SESSION_ID continue an earlier opencode session
+ *   GIBSON_TIMEOUT_MS          hard deadline for the run, in ms
+ *
+ * The child `opencode run` still receives the grant as GIBSON_CALLBACK_TOKEN via
+ * {@link dispatchChildEnv} — that is the opencode plugin's own contract, fed from
+ * the GIBSON_CG_JWT this process reads.
+ */
+import type { AgentOutcome } from "@zeroroot-ai/sdk";
+import { runOpencode } from "./opencode-run.js";
+/**
+ * The per-dispatch grant, as the sandbox injects it. The child authenticates its
+ * harness callbacks with this; {@link dispatchChildEnv} renders it back to env.
+ */
+export interface CallbackGrant {
+    /** `ExecuteRequest.callback_endpoint` — a bare `host:port` or an http(s) URL. */
+    callbackEndpoint: string;
+    /** `ExecuteRequest.callback_token` — the task-scoped capability grant. */
+    callbackToken: string;
+    /** Dial the callback listener without TLS. Only for a local or kind daemon. */
+    insecure?: boolean;
+    /** Provenance the platform correlates the run by. Empty when the caller set none. */
+    missionRunId?: string;
+    agentRunId?: string;
+    traceId?: string;
+}
+/** Everything one sandboxed dispatch needs, read from the environment. */
+export interface DispatchContext extends CallbackGrant {
+    /** `task.goal` — the natural-language objective the sandbox handed over. */
+    goal: string;
+    /** opencode edits files here; it is the run's workspace. */
+    workspace: 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 for the run, in ms. `0` when none was set. */
+    timeoutMs: number;
+}
+/**
+ * Render the per-dispatch grant back to environment for the opencode child, so
+ * the child's harness callbacks travel on the task grant rather than on any
+ * component identity. Empty fields are omitted rather than set blank.
+ *
+ * Shared with `serve-agent.ts`, which builds the same passthrough from a polled
+ * work item — one definition so the two dispatched shapes hand the child the
+ * same environment.
+ */
+export declare function dispatchChildEnv(g: CallbackGrant): NodeJS.ProcessEnv;
+/**
+ * Decode the base64 protojson `gibson.types.v1.Task` the sandbox launch injects
+ * as `GIBSON_AGENT_TASK_B64` (gibson agent.go `envAgentTaskB64`) and return its
+ * goal. gibson sends the full typed Task, not a plain goal string, so decode it
+ * here rather than run opencode against an empty or malformed prompt.
+ */
+export declare function decodeTaskGoal(taskB64: string | undefined): string;
+/**
+ * Read one sandboxed dispatch's context from the environment.
+ *
+ * Deliberately never reads `GIBSON_BOOTSTRAP_TOKEN` or a host key: a sandboxed
+ * run is authenticated by its per-dispatch grant alone, and reaching for a
+ * bootstrap token here would reintroduce the enrollment handshake this shape
+ * exists to avoid.
+ *
+ * The grant and the goal are required. A missing piece throws with the reason,
+ * because a sandbox that launched this process without them is a defect in the
+ * launch, not something to guess around by running opencode with no task or by
+ * making unauthenticated calls.
+ */
+export declare function readDispatchContext(env: NodeJS.ProcessEnv, opts?: {
+    cwd?: string;
+}): DispatchContext;
+/** Injectable seams, so a test drives a dispatch without spawning opencode. */
+export interface DispatchDeps {
+    /** Overridable opencode driver. */
+    run?: typeof runOpencode;
+    /** Live tap for each NDJSON event opencode prints. */
+    onEvent?: (line: string) => void;
+}
+/**
+ * Run one dispatched Task headless and map it to a terminal outcome.
+ *
+ * The opencode child inherits the per-dispatch grant, so its findings, tool
+ * calls and knowledge reads authenticate as the task. Events stream live through
+ * `deps.onEvent`. A crashed or timed-out run throws — {@link main} turns that
+ * into a failed terminal result and a non-zero exit.
+ */
+export declare function runDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * Render a terminal outcome as the last NDJSON line on stdout.
+ *
+ * `type: "result"` marks it apart from the streamed opencode events on the same
+ * stream, so the sandbox launcher reads the run's result from the one line that
+ * carries it.
+ */
+export declare function formatTerminalResult(outcome: AgentOutcome): string;

package/dist/dispatch.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { runOpencode } from "./opencode-run.js";
+/**
+ * Render the per-dispatch grant back to environment for the opencode child, so
+ * the child's harness callbacks travel on the task grant rather than on any
+ * component identity. Empty fields are omitted rather than set blank.
+ *
+ * Shared with `serve-agent.ts`, which builds the same passthrough from a polled
+ * work item — one definition so the two dispatched shapes hand the child the
+ * same environment.
+ */
+export function dispatchChildEnv(g) {
+    return {
+        ...(g.callbackEndpoint ? { GIBSON_CALLBACK_ENDPOINT: g.callbackEndpoint } : {}),
+        ...(g.callbackToken ? { GIBSON_CALLBACK_TOKEN: g.callbackToken } : {}),
+        ...(g.insecure ? { GIBSON_CALLBACK_INSECURE: "1" } : {}),
+        ...(g.missionRunId ? { GIBSON_MISSION_RUN_ID: g.missionRunId } : {}),
+        ...(g.agentRunId ? { GIBSON_AGENT_RUN_ID: g.agentRunId } : {}),
+        ...(g.traceId ? { GIBSON_TRACE_ID: g.traceId } : {}),
+    };
+}
+/**
+ * Decode the base64 protojson `gibson.types.v1.Task` the sandbox launch injects
+ * as `GIBSON_AGENT_TASK_B64` (gibson agent.go `envAgentTaskB64`) and return its
+ * goal. gibson sends the full typed Task, not a plain goal string, so decode it
+ * here rather than run opencode against an empty or malformed prompt.
+ */
+export function decodeTaskGoal(taskB64) {
+    if (!taskB64) {
+        throw new Error("GIBSON_AGENT_TASK_B64 is not set. The sandbox launch injects the task to pursue as the " +
+            "base64 protojson of a gibson.types.v1.Task; without it there is nothing to run.");
+    }
+    let task;
+    try {
+        task = JSON.parse(Buffer.from(taskB64, "base64").toString("utf8"));
+    }
+    catch (e) {
+        throw new Error("GIBSON_AGENT_TASK_B64 is not valid base64 protojson of a gibson.types.v1.Task: " +
+            (e instanceof Error ? e.message : String(e)));
+    }
+    const goal = typeof task.goal === "string" ? task.goal.trim() : "";
+    if (!goal) {
+        throw new Error("GIBSON_AGENT_TASK_B64 decoded to a Task with no goal. Running opencode against an empty " +
+            "prompt would report whatever it says back as a mission result.");
+    }
+    return goal;
+}
+/**
+ * Read one sandboxed dispatch's context from the environment.
+ *
+ * Deliberately never reads `GIBSON_BOOTSTRAP_TOKEN` or a host key: a sandboxed
+ * run is authenticated by its per-dispatch grant alone, and reaching for a
+ * bootstrap token here would reintroduce the enrollment handshake this shape
+ * exists to avoid.
+ *
+ * The grant and the goal are required. A missing piece throws with the reason,
+ * because a sandbox that launched this process without them is a defect in the
+ * launch, not something to guess around by running opencode with no task or by
+ * making unauthenticated calls.
+ */
+export function readDispatchContext(env, opts = {}) {
+    const endpoint = env.GIBSON_CALLBACK_ENDPOINT;
+    const token = env.GIBSON_CG_JWT;
+    if (!endpoint) {
+        throw new Error("GIBSON_CALLBACK_ENDPOINT is not set. A sandboxed dispatched run is authenticated by " +
+            "the per-dispatch grant the sandbox launch injects, not by a bootstrap token — the " +
+            "launch must supply the callback endpoint and the grant.");
+    }
+    if (!token) {
+        throw new Error("GIBSON_CALLBACK_ENDPOINT is set but GIBSON_CG_JWT is not. The callbacks would have no " +
+            "grant to authenticate with; a sandboxed run must not fall back to any other identity, " +
+            "so this fails instead.");
+    }
+    const goal = decodeTaskGoal(env.GIBSON_AGENT_TASK_B64);
+    const timeoutRaw = env.GIBSON_TIMEOUT_MS ? Number(env.GIBSON_TIMEOUT_MS) : 0;
+    return {
+        callbackEndpoint: endpoint,
+        callbackToken: token,
+        insecure: env.GIBSON_CALLBACK_INSECURE === "1",
+        missionRunId: env.GIBSON_MISSION_RUN_ID ?? "",
+        agentRunId: env.GIBSON_AGENT_RUN_ID ?? "",
+        traceId: env.GIBSON_TRACE_ID ?? "",
+        goal,
+        workspace: env.ZEROCOOL_WORKSPACE ?? opts.cwd ?? process.cwd(),
+        ...(env.GIBSON_MODEL ? { model: env.GIBSON_MODEL } : {}),
+        ...(env.GIBSON_OPENCODE_SESSION_ID ? { sessionId: env.GIBSON_OPENCODE_SESSION_ID } : {}),
+        timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 0,
+    };
+}
+/**
+ * Run one dispatched Task headless and map it to a terminal outcome.
+ *
+ * The opencode child inherits the per-dispatch grant, so its findings, tool
+ * calls and knowledge reads authenticate as the task. Events stream live through
+ * `deps.onEvent`. A crashed or timed-out run throws — {@link main} turns that
+ * into a failed terminal result and a non-zero exit.
+ */
+export async function runDispatch(ctx, deps = {}) {
+    const run = deps.run ?? runOpencode;
+    const result = await run({
+        goal: ctx.goal,
+        dir: ctx.workspace,
+        ...(ctx.model ? { model: ctx.model } : {}),
+        ...(ctx.sessionId ? { sessionId: ctx.sessionId } : {}),
+        ...(ctx.timeoutMs > 0 ? { timeoutMs: ctx.timeoutMs } : {}),
+        env: dispatchChildEnv(ctx),
+        ...(deps.onEvent ? { onEvent: deps.onEvent } : {}),
+    });
+    return {
+        output: result.text,
+        success: true,
+        metadata: {
+            opencode_session_id: result.sessionId,
+            finish_reason: result.finishReason,
+            tokens_total: String(result.tokens.total),
+            tokens_output: String(result.tokens.output),
+            cost: String(result.cost),
+        },
+    };
+}
+/**
+ * Render a terminal outcome as the last NDJSON line on stdout.
+ *
+ * `type: "result"` marks it apart from the streamed opencode events on the same
+ * stream, so the sandbox launcher reads the run's result from the one line that
+ * carries it.
+ */
+export function formatTerminalResult(outcome) {
+    return JSON.stringify({
+        type: "result",
+        success: outcome.success ?? true,
+        output: outcome.output ?? "",
+        ...(outcome.findingIds ? { finding_ids: outcome.findingIds } : {}),
+        metadata: outcome.metadata ?? {},
+    });
+}
+async function main() {
+    let ctx;
+    try {
+        ctx = readDispatchContext(process.env);
+    }
+    catch (e) {
+        // A launch defect, not a run failure. Say so on stderr and still emit a
+        // terminal result so the launcher never blocks waiting for one.
+        const message = e.message;
+        console.error(`[zerocool-dispatch] ${message}`);
+        process.stdout.write(`${formatTerminalResult({ success: false, output: message, metadata: { error: message } })}\n`);
+        process.exit(2);
+        return;
+    }
+    console.error(`[zerocool-dispatch] run mission=${ctx.missionRunId || "-"} agent=${ctx.agentRunId || "-"} ` +
+        `workspace=${ctx.workspace}; callbacks use the per-dispatch grant`);
+    try {
+        const outcome = await runDispatch(ctx, {
+            // Forward every opencode event to our stdout, live, for the console stream.
+            onEvent: (line) => process.stdout.write(`${line}\n`),
+        });
+        process.stdout.write(`${formatTerminalResult(outcome)}\n`);
+        console.error(`[zerocool-dispatch] done reason=${outcome.metadata?.finish_reason ?? "-"} ` +
+            `tokens=${outcome.metadata?.tokens_total ?? "-"}`);
+        process.exit(0);
+    }
+    catch (e) {
+        const message = e.message;
+        console.error(`[zerocool-dispatch] run failed: ${message}`);
+        process.stdout.write(`${formatTerminalResult({ success: false, output: message, metadata: { error: message } })}\n`);
+        process.exit(1);
+    }
+}
+// Only run when executed as the bin, so the functions above stay importable.
+if (process.argv[1]?.endsWith("dispatch.js")) {
+    main().catch((e) => {
+        console.error(`[zerocool-dispatch] fatal: ${e.message}`);
+        process.exit(1);
+    });
+}

package/dist/opencode-run.d.ts

@@ -56,7 +56,28 @@ export interface OpencodeRunOptions {
     env?: NodeJS.ProcessEnv;
     /** Binary to run. Overridable for tests and for a pinned install. */
     bin?: string;
+    /**
+     * Called with each complete NDJSON line as opencode prints it, live, before
+     * the run finishes. A dispatched sandbox forwards these to its own stdout so
+     * the daemon can stream the run to the read-only console. The same bytes are
+     * still buffered and parsed at close, so this is a tap, not a replacement —
+     * a slow or throwing sink never changes what the run returns.
+     */
+    onEvent?: (line: string) => void;
 }
+/**
+ * Split a byte stream into complete lines across chunk boundaries.
+ *
+ * `spawn`'s `data` events do not align to newlines: one event can carry half a
+ * line, or several lines and a fragment. This buffers the fragment and calls
+ * `onLine` once per complete, non-empty line, so a live tap sees whole NDJSON
+ * events and never half of one. `flush` emits a trailing line with no final
+ * newline. Exported so the boundary handling is tested directly.
+ */
+export declare function createLineStreamer(onLine: (line: string) => void): {
+    push: (chunk: string) => void;
+    flush: () => void;
+};
 /** Build the argv for a headless run. Exported so a test can assert it. */
 export declare function opencodeArgs(opts: OpencodeRunOptions): string[];
 /**

package/dist/opencode-run.js

@@ -46,6 +46,38 @@ export function parseOpencodeEvents(stdout) {
     result.text = chunks.join("");
     return result;
 }
+/**
+ * Split a byte stream into complete lines across chunk boundaries.
+ *
+ * `spawn`'s `data` events do not align to newlines: one event can carry half a
+ * line, or several lines and a fragment. This buffers the fragment and calls
+ * `onLine` once per complete, non-empty line, so a live tap sees whole NDJSON
+ * events and never half of one. `flush` emits a trailing line with no final
+ * newline. Exported so the boundary handling is tested directly.
+ */
+export function createLineStreamer(onLine) {
+    let pending = "";
+    const emit = (raw) => {
+        const line = raw.trim();
+        if (line)
+            onLine(line);
+    };
+    return {
+        push(chunk) {
+            pending += chunk;
+            let nl;
+            while ((nl = pending.indexOf("\n")) >= 0) {
+                emit(pending.slice(0, nl));
+                pending = pending.slice(nl + 1);
+            }
+        },
+        flush() {
+            const rest = pending;
+            pending = "";
+            emit(rest);
+        },
+    };
+}
 /** 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];
@@ -81,10 +113,28 @@ export async function runOpencode(opts) {
         });
         let stdout = "";
         let stderr = "";
-        child.stdout.on("data", (d) => (stdout += d.toString()));
+        // A live tap for the daemon console, only when the caller asked for one. The
+        // streamer is guarded so a throwing sink cannot fail the run — the buffered
+        // parse below is the source of truth for the result.
+        const streamer = opts.onEvent
+            ? createLineStreamer((line) => {
+                try {
+                    opts.onEvent?.(line);
+                }
+                catch {
+                    // A broken console tap must not cost a mission its result.
+                }
+            })
+            : undefined;
+        child.stdout.on("data", (d) => {
+            const s = d.toString();
+            stdout += s;
+            streamer?.push(s);
+        });
         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) => {
+            streamer?.flush();
             if (signal) {
                 // Killed by the timeout. Say so with the deadline, because "terminated"
                 // alone sends whoever reads the mission looking for a crash.

package/dist/serve-agent.js

@@ -28,6 +28,7 @@ import { connectGibson, registerInstance, startAgentWorker, startHeartbeat, } fr
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { dispatchChildEnv } from "./dispatch.js";
 import { runOpencode } from "./opencode-run.js";
 /** Version reported to the daemon on registration. */
 const VERSION = "0.1.0";
@@ -54,21 +55,18 @@ export async function agentHandler(item, opts) {
         // 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 } : {}),
-        },
+        // The task-scoped callback seam. gibson mints the grant per dispatch
+        // (`internal/engine/harness/implementation.go:1205-1210`) so a dispatched run
+        // reaches the harness as the TASK rather than as this component. The same
+        // passthrough the sandboxed shape uses (`dispatch.ts`), so the child sees one
+        // environment however it was launched.
+        env: dispatchChildEnv({
+            callbackEndpoint: item.callbackEndpoint,
+            callbackToken: item.callbackToken,
+            missionRunId: item.missionRunId,
+            agentRunId: item.agentRunId,
+            traceId: item.traceId,
+        }),
     });
     return {
         output: run.text,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,8 @@
   },
   "bin": {
     "zerocool-serve": "dist/serve.js",
-    "zerocool-agent": "dist/serve-agent.js"
+    "zerocool-agent": "dist/serve-agent.js",
+    "zerocool-dispatch": "dist/dispatch.js"
   },
   "publishConfig": {
     "access": "public"