@zeroroot-ai/zerocool 0.2.0

package/dist/gibson-tools.js

@@ -0,0 +1,175 @@
+import { tool } from "@opencode-ai/plugin";
+import { callGibsonTool, listGibsonPlugins, listGibsonTools, queryGibsonPlugin, } from "@zeroroot-ai/sdk";
+/**
+ * Gibson tools and plugins as opencode tools (zerocool-plugins#9).
+ *
+ * Discovered tools are registered **individually** — one opencode tool per
+ * Gibson tool, named `gibson_<tool>` — so the model sees them in its tool list
+ * with their own descriptions, rather than having to know that a generic
+ * dispatcher exists and what to pass it.
+ *
+ * ON SCHEMAS — the catalog carries no JSON Schema. `ToolDescriptorProto` only
+ * names the proto message types of a tool's input and output
+ * (`gibson.tool.v1.ScanRequest`), and there is no RPC that resolves those to a
+ * schema. So a per-tool wrapper takes a single free-form `input` object and
+ * names the expected message type in its description. Inventing a Zod schema
+ * from a message type name would be a guess, and a wrong guess would reject
+ * valid input before it ever reached the tool.
+ *
+ * A generic `gibson_call_tool` is always registered as well: discovery is
+ * `Unimplemented` on the current daemon (gibson#1186), and without it there
+ * would be no way to reach a tool whose name the operator already knows.
+ */
+/** Sanitise a Gibson tool name into an opencode tool key. */
+export function toolKey(name) {
+    return `gibson_${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+}
+/** Wrap one discovered Gibson tool as an opencode tool. */
+export function wrapGibsonTool(session, t) {
+    const z = tool.schema;
+    const schemaNote = t.inputMessageType
+        ? ` Input must match the Gibson message type ${t.inputMessageType}.`
+        : "";
+    return tool({
+        description: `${t.description || `Gibson tool "${t.name}"`}${schemaNote} Runs through the Gibson harness (authorized and metered).`,
+        args: {
+            input: z
+                .record(z.string(), z.any())
+                .describe(`Input object for the ${t.name} tool${t.inputMessageType ? ` (${t.inputMessageType})` : ""}.`),
+            timeout_ms: z.number().optional().describe("Per-call timeout in milliseconds."),
+        },
+        async execute(args) {
+            const result = await callGibsonTool(session.clients.component, {
+                name: t.name,
+                input: args.input,
+                ...(args.timeout_ms ? { timeoutMs: args.timeout_ms } : {}),
+            });
+            return formatToolResult(t.name, result);
+        },
+    });
+}
+/** The always-present dispatcher for tools the catalog did not surface. */
+export function callToolTool(session) {
+    const z = tool.schema;
+    return tool({
+        description: "Invoke a Gibson tool by name through the harness. Use this when you know a " +
+            "tool's name but it is not in your tool list — Gibson tool discovery is not " +
+            "available on every daemon.",
+        args: {
+            name: z.string().describe("Registered Gibson tool name."),
+            input: z.record(z.string(), z.any()).describe("Input object matching the tool's input schema."),
+            timeout_ms: z.number().optional().describe("Per-call timeout in milliseconds."),
+        },
+        async execute(args) {
+            const result = await callGibsonTool(session.clients.component, {
+                name: args.name,
+                input: args.input,
+                ...(args.timeout_ms ? { timeoutMs: args.timeout_ms } : {}),
+            });
+            return formatToolResult(args.name, result);
+        },
+    });
+}
+/** List what Gibson exposes to this tenant — tools and enabled plugins. */
+export function listToolsTool(session) {
+    return tool({
+        description: "List the Gibson tools and plugins available to this tenant, with the input " +
+            "message type each tool expects.",
+        args: {},
+        async execute() {
+            const [discovery, plugins] = await Promise.all([
+                listGibsonTools(session.clients.component),
+                listGibsonPlugins(session.clients.component).catch(() => []),
+            ]);
+            const lines = [];
+            if (discovery.unavailable) {
+                lines.push(`Tool discovery is unavailable: ${discovery.unavailable}.`);
+            }
+            else if (discovery.tools.length === 0) {
+                lines.push("No Gibson tools are registered for this tenant.");
+            }
+            else {
+                lines.push("Gibson tools:");
+                for (const t of discovery.tools) {
+                    lines.push(`- ${t.name} (${t.version}) — ${t.description || "no description"}`);
+                    if (t.inputMessageType)
+                        lines.push(`    input: ${t.inputMessageType}`);
+                }
+            }
+            const enabled = plugins.filter((p) => p.enabled);
+            if (enabled.length > 0) {
+                lines.push("", "Enabled plugins:");
+                for (const p of enabled) {
+                    lines.push(`- ${p.name} (${p.version}) — methods: ${p.methods.join(", ") || "none"}`);
+                }
+            }
+            return {
+                title: `${discovery.tools.length} tools, ${enabled.length} plugins`,
+                output: lines.join("\n"),
+                metadata: { tool_count: discovery.tools.length, plugin_count: enabled.length },
+            };
+        },
+    });
+}
+/** Invoke a method on an enabled Gibson plugin. */
+export function queryPluginTool(session) {
+    const z = tool.schema;
+    return tool({
+        description: "Call a method on an enabled Gibson plugin through the harness. Use " +
+            "gibson_list_tools first to see which plugins and methods are available.",
+        args: {
+            plugin: z.string().describe("Registered plugin name."),
+            method: z.string().describe("Method to invoke on the plugin."),
+            params: z.record(z.string(), z.any()).optional().describe("Method parameters."),
+            timeout_ms: z.number().optional().describe("Per-call timeout in milliseconds."),
+        },
+        async execute(args) {
+            const result = await queryGibsonPlugin(session.clients.component, {
+                plugin: args.plugin,
+                method: args.method,
+                ...(args.params ? { params: args.params } : {}),
+                ...(args.timeout_ms ? { timeoutMs: args.timeout_ms } : {}),
+            });
+            return formatToolResult(`${args.plugin}.${args.method}`, result);
+        },
+    });
+}
+/**
+ * Discover the tenant's tools and build one opencode tool for each, plus the
+ * always-present dispatcher, catalog and plugin tools.
+ *
+ * Discovery runs once at plugin load. opencode reads the `tool` hook as a
+ * static object, so a tool registered later in the session would not be visible
+ * to the model anyway.
+ */
+export async function buildGibsonTools(session) {
+    const tools = {
+        gibson_call_tool: callToolTool(session),
+        gibson_list_tools: listToolsTool(session),
+        gibson_query_plugin: queryPluginTool(session),
+    };
+    const discovery = await listGibsonTools(session.clients.component);
+    for (const t of discovery.tools) {
+        // Never let a discovered tool shadow the built-ins.
+        const key = toolKey(t.name);
+        if (!(key in tools))
+            tools[key] = wrapGibsonTool(session, t);
+    }
+    return {
+        tools,
+        discovered: discovery.tools.length,
+        ...(discovery.unavailable ? { note: discovery.unavailable } : {}),
+    };
+}
+/** Render a harness tool result, keeping an in-band tool error visible. */
+function formatToolResult(name, result) {
+    if (result.error) {
+        return {
+            title: `${name} failed`,
+            output: `Gibson tool ${name} failed [${result.error.code}]: ${result.error.message}${result.error.retryable ? " (retryable)" : ""}`,
+            metadata: { error_code: result.error.code, retryable: result.error.retryable },
+        };
+    }
+    const text = typeof result.output === "string" ? result.output : JSON.stringify(result.output, null, 2);
+    return { title: name, output: text ?? "(no output)" };
+}

package/dist/http-probe.d.ts

@@ -0,0 +1,43 @@
+import { decodeToolInput, type GibsonClients, type ToolInvocation } from "@zeroroot-ai/sdk";
+/**
+ * The http_probe tool zerocool serves to the fleet.
+ *
+ * A single GET, reported as structured facts. Deliberately the smallest useful
+ * thing a mission node can ask an external component to do: it proves the whole
+ * dispatch path — mission node → work queue → this process → result → mission
+ * completion — without the result depending on anything about the target.
+ *
+ * SAFETY. This is a fetch, not a scanner: one request, no redirect chasing
+ * beyond what fetch does by default, no body execution, and a hard timeout. The
+ * body is measured, never returned — a probe that echoes arbitrary remote
+ * content back into a mission's knowledge graph is an injection surface, and
+ * the size is what the caller actually asked for.
+ */
+export interface ProbeResult {
+    url: string;
+    status: number;
+    statusText: string;
+    server: string | null;
+    contentType: string | null;
+    bytes: number;
+    elapsedMs: number;
+}
+export declare const HTTP_PROBE_TIMEOUT_MS = 15000;
+/** Perform the probe. Exported separately from the handler so it is testable without a work item. */
+export declare function probe(url: string, timeoutMs?: number): Promise<ProbeResult>;
+/**
+ * Work handler: takes a claimed tool invocation and returns the probe result.
+ *
+ * `url` is required. A missing url throws rather than defaulting to something,
+ * because a probe that quietly fetches a different target than the mission
+ * asked for is worse than a failed node.
+ *
+ * `clients` is the callback-harness seam: every dispatched handler receives
+ * the session's Gibson clients so it can reach LLM (`clients.component`),
+ * tools, findings and knowledge (`clients.harness`) during a dispatched run.
+ * The probe itself needs none of that — one request, structured facts — so
+ * the parameter is optional and unused here; richer served tools consume it.
+ */
+export declare function httpProbeHandler(invocation: ToolInvocation, _clients?: GibsonClients): Promise<ProbeResult>;
+/** Re-exported so a caller can decode a raw payload without importing the SDK directly. */
+export { decodeToolInput };

package/dist/http-probe.js

@@ -0,0 +1,51 @@
+import { decodeToolInput } from "@zeroroot-ai/sdk";
+export const HTTP_PROBE_TIMEOUT_MS = 15_000;
+/** Perform the probe. Exported separately from the handler so it is testable without a work item. */
+export async function probe(url, timeoutMs = HTTP_PROBE_TIMEOUT_MS) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`unsupported scheme ${parsed.protocol} (http and https only)`);
+    }
+    const started = Date.now();
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        const res = await fetch(parsed.toString(), { method: "GET", signal: ctl.signal });
+        const body = await res.arrayBuffer();
+        return {
+            url: parsed.toString(),
+            status: res.status,
+            statusText: res.statusText,
+            server: res.headers.get("server"),
+            contentType: res.headers.get("content-type"),
+            bytes: body.byteLength,
+            elapsedMs: Date.now() - started,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Work handler: takes a claimed tool invocation and returns the probe result.
+ *
+ * `url` is required. A missing url throws rather than defaulting to something,
+ * because a probe that quietly fetches a different target than the mission
+ * asked for is worse than a failed node.
+ *
+ * `clients` is the callback-harness seam: every dispatched handler receives
+ * the session's Gibson clients so it can reach LLM (`clients.component`),
+ * tools, findings and knowledge (`clients.harness`) during a dispatched run.
+ * The probe itself needs none of that — one request, structured facts — so
+ * the parameter is optional and unused here; richer served tools consume it.
+ */
+export async function httpProbeHandler(invocation, _clients) {
+    const url = invocation.input.url;
+    if (typeof url !== "string" || !url.trim()) {
+        throw new Error("http_probe requires a `url` parameter");
+    }
+    const timeout = typeof invocation.input.timeout_ms === "number" ? invocation.input.timeout_ms : HTTP_PROBE_TIMEOUT_MS;
+    return probe(url, timeout);
+}
+/** Re-exported so a caller can decode a raw payload without importing the SDK directly. */
+export { decodeToolInput };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * @zeroroot-ai/zerocool — the main Gibson plugin.
+ *
+ * ENROLLMENT — check in once, then run unattended. A human enrolls this host
+ * one time:
+ *
+ *   gibson login                                  # device flow, in a browser
+ *   gibson agent enroll                           # prints a ONE-TIME token
+ *   GIBSON_BOOTSTRAP_TOKEN=<token> opencode       # first start only
+ *
+ * That first start completes the Capability Grant handshake and persists a host
+ * key. Every later start re-registers with that key and needs no token and no
+ * human. This is the platform's design (ADR-0045), not a limitation to work
+ * around: a coding agent joins a tenant's fleet on a person's authority, once.
+ *
+ * Standalone (never enrolled), opencode is almost unchanged: the agent gets a
+ * local findings log and a componentize tool, and nothing else. Enrolled, it
+ * also:
+ *   - checks in as a Gibson component (Capability Grant + RegisterComponent + heartbeat),
+ *   - starts a local OpenAI-compatible shim over the harness,
+ *   - auto-registers a zero-config `gibson` provider via the `config` hook (#6),
+ *   - emits findings into the tenant World (#7),
+ *   - reads the tenant knowledge graph (#8),
+ *   - exposes Gibson tools and plugins as opencode tools (#9),
+ *   - delegates to other agents and drives missions (#10),
+ *   - enrolls produced artifacts into the fleet (#11).
+ *
+ * The plugin fails open throughout. A coding agent that cannot reach its
+ * platform must still be a working coding agent, so every platform failure
+ * degrades to the standalone behaviour instead of refusing to start.
+ */
+export declare const GibsonPlugin: Plugin;
+export default GibsonPlugin;

package/dist/index.js

@@ -0,0 +1,167 @@
+import { connectGibson, startCompletionsShim } from "@zeroroot-ai/sdk";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { componentizeTool, enrollComponentTool } from "./componentize.js";
+import { delegationTools } from "./delegate.js";
+import { buildGibsonTools } from "./gibson-tools.js";
+import { ambientKnowledge, recallTool } from "./knowledge.js";
+import { selectKnowledgeSource } from "./knowledge-source.js";
+import { gibsonFindingsBackend, localFindingsBackend, submitFindingTool, } from "./findings.js";
+/**
+ * @zeroroot-ai/zerocool — the main Gibson plugin.
+ *
+ * ENROLLMENT — check in once, then run unattended. A human enrolls this host
+ * one time:
+ *
+ *   gibson login                                  # device flow, in a browser
+ *   gibson agent enroll                           # prints a ONE-TIME token
+ *   GIBSON_BOOTSTRAP_TOKEN=<token> opencode       # first start only
+ *
+ * That first start completes the Capability Grant handshake and persists a host
+ * key. Every later start re-registers with that key and needs no token and no
+ * human. This is the platform's design (ADR-0045), not a limitation to work
+ * around: a coding agent joins a tenant's fleet on a person's authority, once.
+ *
+ * Standalone (never enrolled), opencode is almost unchanged: the agent gets a
+ * local findings log and a componentize tool, and nothing else. Enrolled, it
+ * also:
+ *   - checks in as a Gibson component (Capability Grant + RegisterComponent + heartbeat),
+ *   - starts a local OpenAI-compatible shim over the harness,
+ *   - auto-registers a zero-config `gibson` provider via the `config` hook (#6),
+ *   - emits findings into the tenant World (#7),
+ *   - reads the tenant knowledge graph (#8),
+ *   - exposes Gibson tools and plugins as opencode tools (#9),
+ *   - delegates to other agents and drives missions (#10),
+ *   - enrolls produced artifacts into the fleet (#11).
+ *
+ * The plugin fails open throughout. A coding agent that cannot reach its
+ * platform must still be a working coding agent, so every platform failure
+ * degrades to the standalone behaviour instead of refusing to start.
+ */
+export const GibsonPlugin = async () => {
+    const platformURL = process.env.GIBSON_PLATFORM_URL;
+    const hostKeyPath = process.env.GIBSON_HOST_KEY_PATH ?? join(homedir(), ".zerocool", "host.key");
+    const context = {};
+    // Check in once, then run unattended — the platform's enrollment model
+    // (ADR-0045). A human runs `gibson login` and `gibson agent enroll` once and
+    // hands over the resulting ONE-TIME bootstrap token. That token completes the
+    // first Capability Grant handshake and the host key it registers is persisted
+    // at `hostKeyPath`. Every later start re-registers by proving possession of
+    // that host key — the daemon routes on credential type: `host+jwt` is
+    // re-registration, anything else is first registration
+    // (gibson `internal/server/daemon/capabilitygrant_register.go:134-155`).
+    //
+    // So the bootstrap token is passed ONLY when no host key exists yet. Replaying
+    // a one-time token on every start would be rejected, and it would mean asking
+    // the operator to keep a spent credential in their environment forever.
+    const checkedIn = existsSync(hostKeyPath);
+    const bootstrapToken = checkedIn ? undefined : process.env.GIBSON_BOOTSTRAP_TOKEN;
+    // Standalone: findings go to a local log, and componentize still works —
+    // producing a manifest needs no platform.
+    const standaloneTools = () => ({
+        submit_finding: submitFindingTool(localFindingsBackend(process.env.ZEROCOOL_FINDINGS_LOG ?? join(homedir(), ".zerocool", "findings.jsonl")), context),
+        gibson_componentize: componentizeTool(),
+    });
+    // Standalone unless we can authenticate: a platform URL plus either a token
+    // for the first check-in or an already-registered host key.
+    if (!platformURL || (!bootstrapToken && !checkedIn)) {
+        if (platformURL && !checkedIn) {
+            console.error("[zerocool] GIBSON_PLATFORM_URL is set but this host has not checked in. " +
+                "Run `gibson login` then `gibson agent enroll`, and start once with " +
+                "GIBSON_BOOTSTRAP_TOKEN=<one-time token>. After that the host key at " +
+                `${hostKeyPath} is enough — you can drop the token.`);
+        }
+        return { tool: standaloneTools() };
+    }
+    let session;
+    let shim;
+    try {
+        session = await connectGibson({
+            platformURL,
+            daemonURL: process.env.GIBSON_DAEMON_URL,
+            bootstrapToken,
+            hostKeyPath,
+            agentName: "zerocool",
+            agentMode: process.env.GIBSON_AGENT_MODE ?? "autonomous",
+            agent: { name: "zerocool", version: "0.0.0", capabilities: ["code"] },
+        });
+        shim = await startCompletionsShim({
+            component: session.clients.component,
+            port: Number(process.env.GIBSON_SHIM_PORT ?? 8787),
+        });
+        console.error(`[zerocool] Gibson connected via ${checkedIn ? "the registered host key" : "first check-in"} ` +
+            `(component_scope=${session.componentScope}); provider "gibson" auto-configured at ` +
+            `${shim.url} — select a gibson/<slot> model`);
+        if (!checkedIn) {
+            console.error(`[zerocool] Host key written to ${hostKeyPath}. The bootstrap token is spent — ` +
+                "unset GIBSON_BOOTSTRAP_TOKEN; later starts re-register with the host key.");
+        }
+    }
+    catch (e) {
+        // Fail open to standalone: a coding agent must still work if the platform is unreachable.
+        console.error(`[zerocool] Gibson connect failed; continuing standalone: ${e.message}`);
+        await shim?.close();
+        return { tool: standaloneTools() };
+    }
+    const shimUrl = shim.url;
+    const live = session;
+    // Tool discovery runs once at load — opencode reads the `tool` hook as a
+    // static object, so a tool registered mid-session would never reach the model.
+    // Which grant this process reads the knowledge graph with. A dispatched run
+    // reads as the TASK; an interactive one keeps the component grant. Chosen once
+    // here so nothing downstream has to ask.
+    const { knowledge, scope: knowledgeScope } = selectKnowledgeSource(live);
+    console.error(`[zerocool] knowledge reads use the ${knowledgeScope} grant`);
+    const gibson = await buildGibsonTools(live);
+    if (gibson.note)
+        console.error(`[zerocool] Gibson tool discovery: ${gibson.note}`);
+    else
+        console.error(`[zerocool] ${gibson.discovered} Gibson tool(s) registered`);
+    const tools = {
+        submit_finding: submitFindingTool(gibsonFindingsBackend(live), context),
+        recall: recallTool(knowledge),
+        gibson_componentize: componentizeTool(),
+        gibson_enroll_component: enrollComponentTool(live),
+        ...gibson.tools,
+        ...delegationTools(live),
+    };
+    const injectKnowledge = ambientKnowledge(knowledge, process.env.ZEROCOOL_AMBIENT_QUERY ?? "prior findings and security facts for this codebase");
+    return {
+        tool: tools,
+        // Zero-config LLM: inject the Gibson provider at config-load time (#6).
+        //
+        // `shimUrl` is always live here, and that is a type-level guarantee rather
+        // than a timing assumption: `Plugin` returns `Promise<Hooks>`, so opencode
+        // cannot reach this hook until the plugin body has resolved — and the body
+        // starts the shim before it builds this object. There is no ordering in
+        // which `config` runs against an unstarted shim.
+        config: async (config) => {
+            const cfg = config;
+            cfg.provider = cfg.provider ?? {};
+            if (!cfg.provider.gibson) {
+                cfg.provider.gibson = {
+                    npm: "@ai-sdk/openai-compatible",
+                    name: "Gibson",
+                    options: { baseURL: shimUrl, apiKey: "gibson" },
+                };
+            }
+        },
+        // Ambient knowledge (#8): one cached GraphRAG lookup per session, injected
+        // into the system prompt from the second turn on.
+        "experimental.chat.system.transform": injectKnowledge,
+        // Track the session so findings carry provenance (#7). This hook does not
+        // emit findings: a file edit is not a security finding, and inventing one
+        // would fill the tenant graph with noise a human then has to triage.
+        event: async ({ event }) => {
+            const sessionID = event.properties?.sessionID;
+            if (sessionID)
+                context.sessionID = sessionID;
+        },
+        dispose: async () => {
+            session?.stop();
+            await shim?.close();
+        },
+    };
+};
+export default GibsonPlugin;

package/dist/knowledge-source.d.ts

@@ -0,0 +1,21 @@
+import { type GibsonSession, type KnowledgeSource } from "@zeroroot-ai/sdk";
+/**
+ * Pick the grant this process should read the knowledge graph with.
+ *
+ * A DISPATCHED run must read as the TASK, not as the component. gibson mints a
+ * per-dispatch capability grant and `zerocool-agent` passes it to the child as
+ * GIBSON_CALLBACK_ENDPOINT / GIBSON_CALLBACK_TOKEN. Reading with the component's
+ * own grant instead is broader authority than the dispatch intended and leaves
+ * no per-task attribution on anything the run reads — the gap ADR-0006 recorded.
+ *
+ * An INTERACTIVE run has no callback seam and keeps the component grant, which
+ * is correct: a human started it, and there is no task to scope to.
+ *
+ * A dispatch that carries an endpoint but no token FAILS rather than falling
+ * back. Falling back is how the gap reappears silently, and a caller who wanted
+ * task-scoped reads would get component-scoped ones without being told.
+ */
+export declare function selectKnowledgeSource(session: GibsonSession): {
+    knowledge: KnowledgeSource;
+    scope: "task" | "component";
+};

package/dist/knowledge-source.js

@@ -0,0 +1,38 @@
+import { componentKnowledge, connectTaskHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
+/**
+ * Pick the grant this process should read the knowledge graph with.
+ *
+ * A DISPATCHED run must read as the TASK, not as the component. gibson mints a
+ * per-dispatch capability grant and `zerocool-agent` passes it to the child as
+ * GIBSON_CALLBACK_ENDPOINT / GIBSON_CALLBACK_TOKEN. Reading with the component's
+ * own grant instead is broader authority than the dispatch intended and leaves
+ * no per-task attribution on anything the run reads — the gap ADR-0006 recorded.
+ *
+ * An INTERACTIVE run has no callback seam and keeps the component grant, which
+ * is correct: a human started it, and there is no task to scope to.
+ *
+ * A dispatch that carries an endpoint but no token FAILS rather than falling
+ * back. Falling back is how the gap reappears silently, and a caller who wanted
+ * task-scoped reads would get component-scoped ones without being told.
+ */
+export function selectKnowledgeSource(session) {
+    const endpoint = process.env.GIBSON_CALLBACK_ENDPOINT;
+    const token = process.env.GIBSON_CALLBACK_TOKEN;
+    if (!endpoint) {
+        return { knowledge: componentKnowledge(session.clients.component), scope: "component" };
+    }
+    if (!token) {
+        throw new Error("GIBSON_CALLBACK_ENDPOINT is set but GIBSON_CALLBACK_TOKEN is not. A dispatched run " +
+            "must read with its task grant; falling back to the component grant would silently " +
+            "widen this run's authority.");
+    }
+    return {
+        knowledge: taskKnowledge(connectTaskHarness({
+            endpoint,
+            token,
+            // A local or kind daemon may serve the callback listener without TLS.
+            insecure: process.env.GIBSON_CALLBACK_INSECURE === "1",
+        })),
+        scope: "task",
+    };
+}

package/dist/knowledge.d.ts

@@ -0,0 +1,15 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import { type KnowledgeSource } from "@zeroroot-ai/sdk";
+export declare function recallTool(knowledge: KnowledgeSource): ToolDefinition;
+/**
+ * Per-session ambient knowledge for the system prompt.
+ *
+ * Returns a transform that injects a short context block once a session has
+ * produced one. The lookup is fired once and cached, so a session pays for at
+ * most one GraphRAG query no matter how many turns it runs.
+ */
+export declare function ambientKnowledge(knowledge: KnowledgeSource, seedQuery: string): (input: {
+    sessionID?: string;
+}, output: {
+    system: string[];
+}) => Promise<void>;

package/dist/knowledge.js

@@ -0,0 +1,113 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatKnowledgeForPrompt, isSeamUnavailable, } from "@zeroroot-ai/sdk";
+/**
+ * Knowledge — read the tenant graph so the agent sharpens across runs
+ * (zerocool-plugins#8).
+ *
+ * Two surfaces, because opencode offers two and they answer different needs:
+ *
+ *  - a **`recall` tool**, which the model calls when it wants prior context.
+ *    This is the primary path: the model knows when a lookup is worth a round
+ *    trip, and the query it writes is better than anything derived from the
+ *    prompt.
+ *  - a **`system.transform` hook**, which injects a small ambient block once
+ *    per session. `experimental.chat.system.transform` runs on every request,
+ *    so an un-cached GraphRAG query there would add a network round trip to
+ *    every single turn. {@link ambientKnowledge} caches per session and injects
+ *    nothing until the first successful lookup.
+ *
+ * All reads are tenant-scoped server-side; there is no tenant argument to get
+ * wrong. Standalone, both surfaces are absent — the plugin does not register
+ * them without a Gibson session.
+ */
+/** How many hits the ambient block injects. Kept small — it is prompt overhead. */
+const AMBIENT_LIMIT = 5;
+export function recallTool(knowledge) {
+    const z = tool.schema;
+    return tool({
+        description: "Search this tenant's Gibson knowledge graph for prior findings, targets and " +
+            "security facts recorded by earlier runs. Use it before starting work on an " +
+            "unfamiliar area, or to check whether an issue was already reported.",
+        args: {
+            query: z.string().describe("What to look for, in natural language."),
+            limit: z.number().min(1).max(50).optional().describe("Maximum hits to return. Defaults to 10."),
+            node_types: z
+                .array(z.string())
+                .optional()
+                .describe('Restrict to node types, e.g. ["finding"] or ["host", "technique"].'),
+        },
+        async execute(args) {
+            let hits;
+            try {
+                hits = await knowledge.query({
+                    text: args.query,
+                    topK: args.limit ?? 10,
+                    ...(args.node_types ? { nodeTypes: args.node_types } : {}),
+                });
+            }
+            catch (e) {
+                if (isSeamUnavailable(e)) {
+                    return {
+                        title: "recall unavailable",
+                        output: "The Gibson knowledge graph is not available on this daemon: the GraphRAG " +
+                            "seam is not wired (gibson#1186). Continue without prior context.",
+                    };
+                }
+                throw e;
+            }
+            if (hits.length === 0) {
+                return { title: "no matches", output: `Nothing in the tenant graph matches "${args.query}".` };
+            }
+            return {
+                title: `${hits.length} match${hits.length === 1 ? "" : "es"}`,
+                output: formatKnowledgeForPrompt(hits),
+                metadata: { hit_count: hits.length, node_types: [...new Set(hits.map((h) => h.type))] },
+            };
+        },
+    });
+}
+/**
+ * Per-session ambient knowledge for the system prompt.
+ *
+ * Returns a transform that injects a short context block once a session has
+ * produced one. The lookup is fired once and cached, so a session pays for at
+ * most one GraphRAG query no matter how many turns it runs.
+ */
+export function ambientKnowledge(knowledge, seedQuery) {
+    const cache = new Map();
+    const inFlight = new Map();
+    const load = async (_key) => {
+        try {
+            const hits = await knowledge.query({
+                text: seedQuery,
+                topK: AMBIENT_LIMIT,
+            });
+            return formatKnowledgeForPrompt(hits);
+        }
+        catch {
+            // A knowledge failure must never break a chat turn — the agent works
+            // without prior context, it just works less well.
+            return "";
+        }
+    };
+    return async (input, output) => {
+        const key = input.sessionID ?? "default";
+        const cached = cache.get(key);
+        if (cached) {
+            output.system.push(cached);
+            return;
+        }
+        // Fire the lookup once per session and let this turn proceed without it;
+        // blocking the first turn on a graph query would be felt as latency on
+        // every new session.
+        if (!inFlight.has(key)) {
+            const p = load(key).then((block) => {
+                if (block)
+                    cache.set(key, block);
+                inFlight.delete(key);
+                return block;
+            });
+            inFlight.set(key, p);
+        }
+    };
+}