@zeroroot-ai/zerocool 0.2.1 → 0.3.0

package/dist/dispatch.d.ts

@@ -0,0 +1,128 @@
+#!/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_CALLBACK_TOKEN`. 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):
+ *
+ *   GIBSON_CALLBACK_ENDPOINT   per-dispatch harness callback dial target (required)
+ *   GIBSON_CALLBACK_TOKEN      per-dispatch capability grant             (required)
+ *   GIBSON_TASK_GOAL           the task to pursue                        (required)
+ *   GIBSON_CALLBACK_INSECURE   "1" to dial the callback listener without TLS (kind)
+ *   GIBSON_MISSION_RUN_ID / GIBSON_AGENT_RUN_ID / GIBSON_TRACE_ID   provenance
+ *   ZEROCOOL_WORKSPACE         working directory (defaults to the cwd)
+ *   ZEROCOOL_MODEL             provider/model for opencode
+ *   GIBSON_OPENCODE_SESSION_ID continue an earlier opencode session
+ *   GIBSON_TIMEOUT_MS          hard deadline for the run, in ms
+ */
+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;
+/**
+ * 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,154 @@
+#!/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 } : {}),
+    };
+}
+/**
+ * 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_CALLBACK_TOKEN;
+    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 token.");
+    }
+    if (!token) {
+        throw new Error("GIBSON_CALLBACK_ENDPOINT is set but GIBSON_CALLBACK_TOKEN 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 = env.GIBSON_TASK_GOAL?.trim();
+    if (!goal) {
+        throw new Error("GIBSON_TASK_GOAL is empty. The sandbox launch injects the task to pursue; running " +
+            "opencode against an empty prompt would report whatever it says back as a mission result.");
+    }
+    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.ZEROCOOL_MODEL ? { model: env.ZEROCOOL_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,14 +1,26 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zeroroot-ai/zerocool-plugins.git",
+    "directory": "packages/opencode-gibson"
+  },
+  "homepage": "https://github.com/zeroroot-ai/zerocool-plugins",
+  "bugs": "https://github.com/zeroroot-ai/zerocool-plugins/issues",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\""
+  },
   "dependencies": {
     "@zeroroot-ai/sdk": "^0.4.0"
   },
@@ -20,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"
@@ -30,10 +43,5 @@
       "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\""
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 ZeroRoot
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.