@zeroroot-ai/zerocool 0.3.0 → 0.4.0

package/dist/dispatch.d.ts

@@ -16,9 +16,9 @@
  * 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.
+ * `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
@@ -35,18 +35,31 @@
  *
  * 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_CALLBACK_TOKEN      per-dispatch capability grant             (required)
- *   GIBSON_TASK_GOAL           the task to pursue                        (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_RUN_ID / GIBSON_AGENT_RUN_ID / GIBSON_TRACE_ID   provenance
+ *   GIBSON_MISSION_ID / GIBSON_MISSION_RUN_ID / GIBSON_AGENT_RUN_ID   provenance
  *   ZEROCOOL_WORKSPACE         working directory (defaults to the cwd)
- *   ZEROCOOL_MODEL             provider/model for opencode
+ *   ZEROCOOL_TASK              force a task kind ("source-analysis"); the Task's
+ *                              own context `zerocool.task` is the normal way
  *   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 { type AgentOutcome, type TaskHarness } from "@zeroroot-ai/sdk";
+import { type FindingsBackend } from "./findings.js";
 import { runOpencode } from "./opencode-run.js";
+import type { SemgrepRunner } from "./semgrep.js";
+import { type TriageModel } from "./source-analysis.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.
@@ -67,6 +80,14 @@ export interface CallbackGrant {
 export interface DispatchContext extends CallbackGrant {
     /** `task.goal` — the natural-language objective the sandbox handed over. */
     goal: string;
+    /**
+     * `task.context` — the string map the mission node set. Selects the task kind
+     * (`zerocool.task`) and carries what a task needs beyond a goal: the
+     * repository url and commit, a sub-path, the target id.
+     */
+    taskContext: Record<string, string>;
+    /** `GIBSON_MISSION_ID`, so a Finding names the mission it belongs to. */
+    missionId?: string;
     /** opencode edits files here; it is the run's workspace. */
     workspace: string;
     /** `provider/model`, e.g. `gibson/default`. Omitted lets opencode choose. */
@@ -86,6 +107,33 @@ export interface DispatchContext extends CallbackGrant {
  * 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;
+/** The parts of a `gibson.types.v1.Task` a dispatch reads. */
+export interface DecodedTask {
+    goal: string;
+    context: Record<string, string>;
+    metadata: Record<string, string>;
+}
+/**
+ * Decode the whole Task: the goal, and the `context` and `metadata` string
+ * maps a mission node sets. protojson renders both as plain objects, so a
+ * value that is not a string is dropped rather than guessed at.
+ */
+export declare function decodeTask(taskB64: string | undefined): DecodedTask;
+/** The task kinds a sandboxed dispatch can serve. */
+export type DispatchTaskKind = "opencode" | "source-analysis";
+/**
+ * Which task this dispatch runs. The mission node says so in the Task's
+ * context (`zerocool.task`); ZEROCOOL_TASK forces it for a hand-run sandbox.
+ * Anything unrecognized is the default: drive opencode on the goal.
+ */
+export declare function dispatchTaskKind(ctx: Pick<DispatchContext, "taskContext">, env?: NodeJS.ProcessEnv): DispatchTaskKind;
 /**
  * Read one sandboxed dispatch's context from the environment.
  *
@@ -108,6 +156,14 @@ export interface DispatchDeps {
     run?: typeof runOpencode;
     /** Live tap for each NDJSON event opencode prints. */
     onEvent?: (line: string) => void;
+    /** Source-analysis seams: no semgrep binary, no model, no daemon in a test. */
+    semgrep?: SemgrepRunner;
+    model?: TriageModel;
+    findings?: FindingsBackend;
+    /** Opens the task harness. Defaults to `openTaskHarness` on the dispatch grant. */
+    harness?: (ctx: DispatchContext) => TaskHarness;
+    /** Force the task kind, over the Task's own context. */
+    taskKind?: DispatchTaskKind;
 }
 /**
  * Run one dispatched Task headless and map it to a terminal outcome.
@@ -118,6 +174,17 @@ export interface DispatchDeps {
  * into a failed terminal result and a non-zero exit.
  */
 export declare function runDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * The source-analysis task, sandboxed (zerocool-plugins#87). opencode is not
+ * involved: semgrep produces candidates, the model triages them through the
+ * harness `LLMComplete` on the task grant, and real ones are submitted through
+ * the harness `SubmitFinding` on the same grant. The task reads the checkout
+ * (the workspace, or `source.path` under it) and changes nothing.
+ *
+ * Task context keys it reads: `zerocool.task` (selector), `source.path`,
+ * `repository.url`, `repository.commit`, `target.id`.
+ */
+export declare function runSourceAnalysisDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
 /**
  * Render a terminal outcome as the last NDJSON line on stdout.
  *

package/dist/dispatch.js

@@ -1,5 +1,65 @@
 #!/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)
+ *   ZEROCOOL_TASK              force a task kind ("source-analysis"); the Task's
+ *                              own context `zerocool.task` is the normal way
+ *   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 { openTaskHarness } from "@zeroroot-ai/sdk";
+import { join } from "node:path";
+import { taskFindingsBackend } from "./findings.js";
 import { runOpencode } from "./opencode-run.js";
+import { formatSourceAnalysis, harnessTriageModel, runSourceAnalysis, } from "./source-analysis.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
@@ -19,6 +79,59 @@ export function dispatchChildEnv(g) {
         ...(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) {
+    return decodeTask(taskB64).goal;
+}
+/**
+ * Decode the whole Task: the goal, and the `context` and `metadata` string
+ * maps a mission node sets. protojson renders both as plain objects, so a
+ * value that is not a string is dropped rather than guessed at.
+ */
+export function decodeTask(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, context: stringMap(task.context), metadata: stringMap(task.metadata) };
+}
+function stringMap(v) {
+    if (!v || typeof v !== "object")
+        return {};
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (typeof val === "string")
+            out[k] = val;
+    }
+    return out;
+}
+/**
+ * Which task this dispatch runs. The mission node says so in the Task's
+ * context (`zerocool.task`); ZEROCOOL_TASK forces it for a hand-run sandbox.
+ * Anything unrecognized is the default: drive opencode on the goal.
+ */
+export function dispatchTaskKind(ctx, env = {}) {
+    const kind = env.ZEROCOOL_TASK ?? ctx.taskContext["zerocool.task"] ?? "";
+    return kind === "source-analysis" ? "source-analysis" : "opencode";
+}
 /**
  * Read one sandboxed dispatch's context from the environment.
  *
@@ -34,22 +147,18 @@ export function dispatchChildEnv(g) {
  */
 export function readDispatchContext(env, opts = {}) {
     const endpoint = env.GIBSON_CALLBACK_ENDPOINT;
-    const token = env.GIBSON_CALLBACK_TOKEN;
+    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 token.");
+            "launch must supply the callback endpoint and the grant.");
     }
     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.");
+        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 task = decodeTask(env.GIBSON_AGENT_TASK_B64);
     const timeoutRaw = env.GIBSON_TIMEOUT_MS ? Number(env.GIBSON_TIMEOUT_MS) : 0;
     return {
         callbackEndpoint: endpoint,
@@ -58,9 +167,11 @@ export function readDispatchContext(env, opts = {}) {
         missionRunId: env.GIBSON_MISSION_RUN_ID ?? "",
         agentRunId: env.GIBSON_AGENT_RUN_ID ?? "",
         traceId: env.GIBSON_TRACE_ID ?? "",
-        goal,
+        goal: task.goal,
+        taskContext: task.context,
+        ...(env.GIBSON_MISSION_ID ? { missionId: env.GIBSON_MISSION_ID } : {}),
         workspace: env.ZEROCOOL_WORKSPACE ?? opts.cwd ?? process.cwd(),
-        ...(env.ZEROCOOL_MODEL ? { model: env.ZEROCOOL_MODEL } : {}),
+        ...(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,
     };
@@ -74,6 +185,9 @@ export function readDispatchContext(env, opts = {}) {
  * into a failed terminal result and a non-zero exit.
  */
 export async function runDispatch(ctx, deps = {}) {
+    if ((deps.taskKind ?? dispatchTaskKind(ctx, process.env)) === "source-analysis") {
+        return runSourceAnalysisDispatch(ctx, deps);
+    }
     const run = deps.run ?? runOpencode;
     const result = await run({
         goal: ctx.goal,
@@ -96,6 +210,60 @@ export async function runDispatch(ctx, deps = {}) {
         },
     };
 }
+/**
+ * The source-analysis task, sandboxed (zerocool-plugins#87). opencode is not
+ * involved: semgrep produces candidates, the model triages them through the
+ * harness `LLMComplete` on the task grant, and real ones are submitted through
+ * the harness `SubmitFinding` on the same grant. The task reads the checkout
+ * (the workspace, or `source.path` under it) and changes nothing.
+ *
+ * Task context keys it reads: `zerocool.task` (selector), `source.path`,
+ * `repository.url`, `repository.commit`, `target.id`.
+ */
+export async function runSourceAnalysisDispatch(ctx, deps = {}) {
+    const opened = !deps.harness && !(deps.model && deps.findings);
+    const harness = deps.model && deps.findings
+        ? undefined
+        : (deps.harness ?? ((c) => openTaskHarness({ endpoint: c.callbackEndpoint, token: c.callbackToken, insecure: c.insecure ?? false })))(ctx);
+    const model = deps.model ?? harnessTriageModel(harness);
+    const findings = deps.findings ?? taskFindingsBackend(harness);
+    const sub = ctx.taskContext["source.path"];
+    const dir = sub ? join(ctx.workspace, sub) : ctx.workspace;
+    try {
+        const summary = await runSourceAnalysis({
+            dir,
+            model,
+            findings,
+            ...(deps.semgrep ? { semgrep: deps.semgrep } : {}),
+            ...(ctx.timeoutMs > 0 ? { semgrepTimeoutMs: ctx.timeoutMs } : {}),
+            provenance: {
+                ...(ctx.missionId ? { missionId: ctx.missionId } : {}),
+                ...(ctx.taskContext["repository.url"] ? { repository: ctx.taskContext["repository.url"] } : {}),
+                ...(ctx.taskContext["repository.commit"] ? { commit: ctx.taskContext["repository.commit"] } : {}),
+                ...(ctx.taskContext["target.id"] ? { targetId: ctx.taskContext["target.id"] } : {}),
+            },
+            ...(deps.onEvent ? { onEvent: (event) => deps.onEvent?.(JSON.stringify(event)) } : {}),
+        });
+        return {
+            output: formatSourceAnalysis(summary),
+            success: true,
+            findingIds: summary.findingIds,
+            metadata: {
+                task: "source-analysis",
+                matches: String(summary.matches),
+                candidates: String(summary.candidates),
+                real: String(summary.real),
+                noise: String(summary.noise),
+                submitted: String(summary.findingIds.length),
+                failed: String(summary.failed.length),
+            },
+        };
+    }
+    finally {
+        if (opened)
+            harness?.stop();
+    }
+}
 /**
  * Render a terminal outcome as the last NDJSON line on stdout.
  *

package/dist/findings.d.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from "@opencode-ai/plugin";
-import { type Finding, type GibsonSession } from "@zeroroot-ai/sdk";
+import { type Finding, type GibsonSession, type TaskHarness } from "@zeroroot-ai/sdk";
 export interface FindingsBackend {
     /** Submit a finding; returns the identifier it was recorded under. */
     submit(f: Finding): Promise<string>;
@@ -8,6 +8,14 @@ export interface FindingsBackend {
 }
 /** Platform backend — findings land in the tenant knowledge graph. */
 export declare function gibsonFindingsBackend(session: GibsonSession): FindingsBackend;
+/**
+ * Task backend — the callback service's typed `SubmitFinding` under the
+ * per-dispatch grant, so a sandboxed run's findings are attributed to the TASK
+ * (mission and run), never to a component identity the sandbox does not hold.
+ * Fields map from the SDK's JSON finding onto `gibson.types.v1.Finding`; the
+ * daemon keeps the id `newFinding` minted. Same mapping as claude-gibson's.
+ */
+export declare function taskFindingsBackend(harness: TaskHarness): FindingsBackend;
 /**
  * Standalone backend — findings are appended as JSONL. The same Finding shape is
  * written, so a local log can be replayed into Gibson later.

package/dist/findings.js

@@ -26,6 +26,42 @@ export function gibsonFindingsBackend(session) {
         describe: () => "the tenant Gibson graph",
     };
 }
+/**
+ * Task backend — the callback service's typed `SubmitFinding` under the
+ * per-dispatch grant, so a sandboxed run's findings are attributed to the TASK
+ * (mission and run), never to a component identity the sandbox does not hold.
+ * Fields map from the SDK's JSON finding onto `gibson.types.v1.Finding`; the
+ * daemon keeps the id `newFinding` minted. Same mapping as claude-gibson's.
+ */
+export function taskFindingsBackend(harness) {
+    const severity = (s) => ({ critical: 1, high: 2, medium: 3, low: 4, info: 5 })[s] ?? 0;
+    return {
+        submit: async (f) => {
+            const res = await harness.client.submitFinding({
+                context: harness.context,
+                finding: {
+                    id: f.id,
+                    missionId: f.mission_id,
+                    agentName: f.agent_name,
+                    title: f.title,
+                    description: f.description,
+                    category: f.category,
+                    severity: severity(f.severity),
+                    confidence: f.confidence,
+                    remediation: f.remediation ?? "",
+                    targetId: f.target_id ?? "",
+                    tags: f.tags ?? [],
+                    references: f.references ?? [],
+                    evidence: (f.evidence ?? []).map((e) => ({ type: e.type, title: e.title, content: e.content })),
+                },
+            });
+            if (res.error)
+                throw new Error(`SubmitFinding refused: ${res.error.message}`);
+            return f.id;
+        },
+        describe: () => "the tenant Gibson graph (dispatch grant)",
+    };
+}
 /**
  * Standalone backend — findings are appended as JSONL. The same Finding shape is
  * written, so a local log can be replayed into Gibson later.

package/dist/knowledge-source.js

@@ -1,4 +1,4 @@
-import { componentKnowledge, connectTaskHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
+import { componentKnowledge, openTaskHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
 /**
  * Pick the grant this process should read the knowledge graph with.
  *
@@ -27,7 +27,7 @@ export function selectKnowledgeSource(session) {
             "widen this run's authority.");
     }
     return {
-        knowledge: taskKnowledge(connectTaskHarness({
+        knowledge: taskKnowledge(openTaskHarness({
             endpoint,
             token,
             // A local or kind daemon may serve the callback listener without TLS.

package/dist/semgrep.d.ts

@@ -0,0 +1,76 @@
+/**
+ * semgrep — the candidate producer for the source-analysis task
+ * (zerocool-plugins#87).
+ *
+ * semgrep runs the vendored ruleset (`semgrep/rules.yaml`, pinned with the
+ * package, never fetched) over a checkout and prints one JSON document. The
+ * parser below is pure and is tested against bytes recorded from semgrep
+ * 1.175.0 over the fixture repository, so a change in semgrep's output fails a
+ * unit test rather than a Scan mission.
+ *
+ * A match is a CANDIDATE, not a Finding. The model triages each one in
+ * `source-analysis.ts`; nothing here decides.
+ */
+/** One semgrep match, reduced to what triage and a Finding need. */
+export interface SemgrepCandidate {
+    /** The rule id, e.g. `rules.js-eval-of-request-input`. */
+    checkId: string;
+    /** Repository-relative path, as semgrep printed it. */
+    path: string;
+    line: number;
+    endLine: number;
+    message: string;
+    /** semgrep's own level: ERROR, WARNING or INFO. */
+    severity: string;
+    /** CWE strings from the rule's metadata, verbatim (`CWE-79: ...`). */
+    cwe: string[];
+    /** The rule's `metadata.category`, when it set one. */
+    category?: string;
+    /** The matched source lines. */
+    snippet: string;
+}
+/**
+ * Parse the JSON `semgrep scan --json` writes. Throws when the document is not
+ * JSON or carries an error semgrep itself marked as an error, because a partial
+ * candidate list would look like a clean checkout.
+ */
+export declare function parseSemgrepOutput(stdout: string): SemgrepCandidate[];
+/**
+ * semgrep prefixes a local rule's id with the config file's path, dot-joined
+ * (`app.semgrep.js-eval-any` in the image, `rules.js-eval-any` from a relative
+ * config). The rule is the last segment; the prefix is where the file sat. A
+ * Finding must name the rule, not the install path, so the prefix is dropped.
+ */
+export declare function bareRuleId(checkId: string): string;
+/** The vendored ruleset, resolved from the package it ships with. */
+export declare function defaultRulesPath(): string;
+export interface SemgrepRunOptions {
+    /** The checkout to scan. semgrep runs with this as its cwd and `.` as the target. */
+    dir: string;
+    /** Ruleset path. Defaults to the vendored one. */
+    rules?: string;
+    /** Binary to run. Overridable for a pinned install and for tests. */
+    bin?: string;
+    /** Hard deadline. The child is killed when it elapses. */
+    timeoutMs?: number;
+}
+/**
+ * Build the argv. Exported so a test can assert it.
+ *
+ * The target is `.` and the cwd is the checkout, on purpose: semgrep reports
+ * paths relative to the target, so a Finding's `file` is repository-relative
+ * rather than a sandbox path, and semgrep's default ignore list (which skips
+ * `test/` directories anywhere in the path) is judged against the checkout,
+ * not against wherever the sandbox mounted it.
+ */
+export declare function semgrepArgs(opts: SemgrepRunOptions): string[];
+/** A function that yields candidates for a checkout. The seam tests stub. */
+export type SemgrepRunner = (opts: SemgrepRunOptions) => Promise<SemgrepCandidate[]>;
+/**
+ * Run semgrep once over a checkout and return the candidates.
+ *
+ * semgrep exits 0 when the scan ran, with or without matches; anything else is
+ * a failed scan and throws with semgrep's stderr tail, so a task never reports
+ * "no findings" for a scan that did not happen.
+ */
+export declare const runSemgrep: SemgrepRunner;

package/dist/semgrep.js

@@ -0,0 +1,111 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+/**
+ * Parse the JSON `semgrep scan --json` writes. Throws when the document is not
+ * JSON or carries an error semgrep itself marked as an error, because a partial
+ * candidate list would look like a clean checkout.
+ */
+export function parseSemgrepOutput(stdout) {
+    let doc;
+    try {
+        doc = JSON.parse(stdout);
+    }
+    catch (e) {
+        throw new Error(`semgrep output is not JSON: ${e.message}`);
+    }
+    const fatal = (doc.errors ?? []).filter((err) => (err.level ?? "error") === "error");
+    if (fatal.length > 0) {
+        throw new Error(`semgrep reported ${fatal.length} error(s): ${fatal.map((err) => err.message ?? "?").join("; ")}`);
+    }
+    return (doc.results ?? []).map((r) => {
+        const cweRaw = r.extra?.metadata?.cwe;
+        const cwe = Array.isArray(cweRaw) ? cweRaw : cweRaw ? [cweRaw] : [];
+        return {
+            checkId: bareRuleId(r.check_id ?? ""),
+            path: r.path ?? "",
+            line: r.start?.line ?? 0,
+            endLine: r.end?.line ?? r.start?.line ?? 0,
+            message: (r.extra?.message ?? "").trim(),
+            severity: r.extra?.severity ?? "",
+            cwe,
+            ...(r.extra?.metadata?.category ? { category: r.extra.metadata.category } : {}),
+            snippet: r.extra?.lines ?? "",
+        };
+    });
+}
+/**
+ * semgrep prefixes a local rule's id with the config file's path, dot-joined
+ * (`app.semgrep.js-eval-any` in the image, `rules.js-eval-any` from a relative
+ * config). The rule is the last segment; the prefix is where the file sat. A
+ * Finding must name the rule, not the install path, so the prefix is dropped.
+ */
+export function bareRuleId(checkId) {
+    const i = checkId.lastIndexOf(".");
+    return i >= 0 ? checkId.slice(i + 1) : checkId;
+}
+/** The vendored ruleset, resolved from the package it ships with. */
+export function defaultRulesPath() {
+    return fileURLToPath(new URL("../semgrep/rules.yaml", import.meta.url));
+}
+/**
+ * Build the argv. Exported so a test can assert it.
+ *
+ * The target is `.` and the cwd is the checkout, on purpose: semgrep reports
+ * paths relative to the target, so a Finding's `file` is repository-relative
+ * rather than a sandbox path, and semgrep's default ignore list (which skips
+ * `test/` directories anywhere in the path) is judged against the checkout,
+ * not against wherever the sandbox mounted it.
+ */
+export function semgrepArgs(opts) {
+    return [
+        "scan",
+        "--json",
+        "--quiet",
+        "--metrics=off",
+        "--disable-version-check",
+        "--config",
+        opts.rules ?? defaultRulesPath(),
+        ".",
+    ];
+}
+/**
+ * Run semgrep once over a checkout and return the candidates.
+ *
+ * semgrep exits 0 when the scan ran, with or without matches; anything else is
+ * a failed scan and throws with semgrep's stderr tail, so a task never reports
+ * "no findings" for a scan that did not happen.
+ */
+export const runSemgrep = async (opts) => {
+    const bin = opts.bin ?? process.env.ZEROCOOL_SEMGREP_BIN ?? "semgrep";
+    const args = semgrepArgs(opts);
+    return await new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            cwd: opts.dir,
+            env: { ...process.env, SEMGREP_SEND_METRICS: "off", SEMGREP_ENABLE_VERSION_CHECK: "0" },
+            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) {
+                reject(new Error(`semgrep 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(`semgrep exited ${code}${tail ? `: ${tail}` : ""}`));
+                return;
+            }
+            try {
+                resolve(parseSemgrepOutput(stdout));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    });
+};

package/dist/source-analysis.d.ts

@@ -0,0 +1,134 @@
+import { type Finding, type Severity, type TaskHarness } from "@zeroroot-ai/sdk";
+import type { FindingsBackend } from "./findings.js";
+import { type SemgrepCandidate, type SemgrepRunner } from "./semgrep.js";
+/**
+ * The source-analysis task (zerocool-plugins#87).
+ *
+ * semgrep produces candidates from a checkout; the model triages each one as
+ * real or noise; every real one is submitted as a Finding that names its
+ * Vulnerability (a CWE, or a platform id when the rule carries none), the file
+ * and line, and the model's reason. The task reads the checkout and writes
+ * Findings. It changes no file and pushes nothing — that is the Fix's job
+ * (zerocool-plugins#89), a different task with a different grant posture.
+ *
+ * Deterministic first, model second. semgrep decides what is a candidate; the
+ * model only decides whether a candidate is real, given the rule's message and
+ * the code around the match. A rule that never yields a real finding is
+ * removed from the ruleset rather than argued with in a prompt.
+ *
+ * Every seam is injectable — the semgrep runner, the model, the findings
+ * backend, the file reader — so the test in `source-analysis.test.ts` drives a
+ * whole pass over the fixture repository with no semgrep binary, no network,
+ * and no daemon.
+ */
+/** What the model said about one candidate. */
+export interface Triage {
+    verdict: "real" | "noise";
+    reason: string;
+}
+/** The model seam: one candidate in, one verdict out. */
+export type TriageModel = (c: AnalysisCandidate, snippet: string) => Promise<Triage>;
+/** A deduplicated candidate: one place, one Vulnerability, the rules that hit it. */
+export interface AnalysisCandidate extends SemgrepCandidate {
+    /** `CWE-95`, or `zerocool:semgrep:<rule>` when the rule names no CWE. */
+    vulnerabilityId: string;
+    /** Every rule that matched this place for this Vulnerability. */
+    ruleIds: string[];
+}
+/**
+ * The Vulnerability id for a candidate. A CWE from the rule's metadata wins,
+ * normalized to `CWE-<n>` so the same weakness from two rules is one node in
+ * the graph. A rule with no CWE gets a platform id keyed by the rule, which is
+ * still stable across runs and repositories.
+ */
+export declare function vulnerabilityId(c: SemgrepCandidate): string;
+/**
+ * Collapse matches to one candidate per (path, line, Vulnerability). Two rules
+ * that flag the same eval on the same line are one weakness, and two Findings
+ * for it would be one duplicate for a person to close. The strongest rule's
+ * level and message are kept; every rule id is recorded.
+ */
+export declare function dedupeCandidates(matches: SemgrepCandidate[]): AnalysisCandidate[];
+/** Lines around a match, numbered, for the model and for the Finding's evidence. */
+export declare function readSnippet(dir: string, c: SemgrepCandidate, read?: (path: string) => Promise<string>, context?: number): Promise<string>;
+/**
+ * The triage prompt. The model gets the rule's message, the weakness, and the
+ * code; it answers with one JSON object. Exported so the wording is testable
+ * and so a reader can see exactly what the model is asked.
+ */
+export declare function triageMessages(c: AnalysisCandidate, snippet: string): {
+    role: string;
+    content: string;
+}[];
+/**
+ * Parse the model's answer. Tolerant of prose around the object, strict about
+ * the verdict: anything but a clear "real" is noise, because a Finding the
+ * model did not clearly confirm is exactly the noise this task exists to drop.
+ */
+export declare function parseTriage(text: string): Triage;
+/**
+ * The model behind the task grant: one `LLMComplete` on the harness per
+ * candidate, on the tenant's own provider, through the harness so the call is
+ * traced and budgeted like every other model call the run makes.
+ */
+export declare function harnessTriageModel(harness: TaskHarness, slot?: string): TriageModel;
+/** semgrep's level mapped onto the Finding severity scale. */
+export declare function findingSeverity(level: string): Severity;
+/** What the Finding needs to say where it came from. */
+export interface AnalysisProvenance {
+    missionId?: string;
+    /** `https://gitlab.com/examplebank/customer-portal`, when the task knows it. */
+    repository?: string;
+    commit?: string;
+    targetId?: string;
+}
+/**
+ * Build the Finding for a real candidate. The Vulnerability id, the file and
+ * the line travel in the title, the tags and the evidence, so they survive the
+ * typed `SubmitFinding` mapping, which carries no free-form metadata.
+ */
+export declare function candidateFinding(c: AnalysisCandidate, triage: Triage, snippet: string, prov: AnalysisProvenance): Finding;
+export interface SourceAnalysisOptions {
+    /** The checkout to analyze. */
+    dir: string;
+    model: TriageModel;
+    findings: FindingsBackend;
+    provenance?: AnalysisProvenance;
+    /** Seams. */
+    semgrep?: SemgrepRunner;
+    readFile?: (path: string) => Promise<string>;
+    rules?: string;
+    semgrepTimeoutMs?: number;
+    /** Progress events, one object per step, for the console stream. */
+    onEvent?: (event: Record<string, unknown>) => void;
+}
+/** What one pass produced. */
+export interface SourceAnalysisSummary {
+    matches: number;
+    candidates: number;
+    real: number;
+    noise: number;
+    /** Ids of the Findings submitted, in order. */
+    findingIds: string[];
+    /** Candidates the model or the backend failed on, with the error. Never silent. */
+    failed: {
+        candidate: string;
+        error: string;
+    }[];
+    /** Every verdict, for the terminal result and the MR note. */
+    verdicts: {
+        candidate: string;
+        vulnerabilityId: string;
+        verdict: Triage["verdict"];
+        reason: string;
+    }[];
+}
+/**
+ * One pass: scan, dedupe, triage, submit. A candidate the model or the backend
+ * fails on is recorded in `failed` and the pass continues, so one bad answer
+ * costs one candidate rather than the whole scan. The pass never throws for a
+ * clean checkout; it throws only when semgrep itself could not run.
+ */
+export declare function runSourceAnalysis(opts: SourceAnalysisOptions): Promise<SourceAnalysisSummary>;
+/** The human-readable result the mission node records. */
+export declare function formatSourceAnalysis(s: SourceAnalysisSummary): string;

package/dist/source-analysis.js

@@ -0,0 +1,251 @@
+import { newFinding } from "@zeroroot-ai/sdk";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runSemgrep } from "./semgrep.js";
+/** semgrep's level, ranked so the strongest rule wins a deduplicated place. */
+const LEVEL_RANK = { ERROR: 3, WARNING: 2, INFO: 1 };
+/**
+ * The Vulnerability id for a candidate. A CWE from the rule's metadata wins,
+ * normalized to `CWE-<n>` so the same weakness from two rules is one node in
+ * the graph. A rule with no CWE gets a platform id keyed by the rule, which is
+ * still stable across runs and repositories.
+ */
+export function vulnerabilityId(c) {
+    for (const raw of c.cwe) {
+        const m = /CWE-(\d+)/i.exec(raw);
+        if (m)
+            return `CWE-${m[1]}`;
+    }
+    return `zerocool:semgrep:${c.checkId}`;
+}
+/**
+ * Collapse matches to one candidate per (path, line, Vulnerability). Two rules
+ * that flag the same eval on the same line are one weakness, and two Findings
+ * for it would be one duplicate for a person to close. The strongest rule's
+ * level and message are kept; every rule id is recorded.
+ */
+export function dedupeCandidates(matches) {
+    const byKey = new Map();
+    for (const m of matches) {
+        const id = vulnerabilityId(m);
+        const key = `${m.path}:${m.line}:${id}`;
+        const seen = byKey.get(key);
+        if (!seen) {
+            byKey.set(key, { ...m, vulnerabilityId: id, ruleIds: [m.checkId] });
+            continue;
+        }
+        if (!seen.ruleIds.includes(m.checkId))
+            seen.ruleIds.push(m.checkId);
+        if ((LEVEL_RANK[m.severity] ?? 0) > (LEVEL_RANK[seen.severity] ?? 0)) {
+            seen.severity = m.severity;
+            seen.message = m.message;
+            seen.checkId = m.checkId;
+            seen.endLine = Math.max(seen.endLine, m.endLine);
+        }
+    }
+    return [...byKey.values()].sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line);
+}
+/** Lines around a match, numbered, for the model and for the Finding's evidence. */
+export async function readSnippet(dir, c, read = (p) => readFile(p, "utf8"), context = 4) {
+    let text;
+    try {
+        text = await read(join(dir, c.path));
+    }
+    catch {
+        return "";
+    }
+    const lines = text.split("\n");
+    const from = Math.max(1, c.line - context);
+    const to = Math.min(lines.length, c.endLine + context);
+    const out = [];
+    for (let n = from; n <= to; n++) {
+        const mark = n >= c.line && n <= c.endLine ? ">" : " ";
+        out.push(`${mark} ${String(n).padStart(4)} | ${lines[n - 1] ?? ""}`);
+    }
+    return out.join("\n");
+}
+/**
+ * The triage prompt. The model gets the rule's message, the weakness, and the
+ * code; it answers with one JSON object. Exported so the wording is testable
+ * and so a reader can see exactly what the model is asked.
+ */
+export function triageMessages(c, snippet) {
+    return [
+        {
+            role: "system",
+            content: "You triage static-analysis matches in application source code. For the match below, " +
+                "decide whether it is a real weakness an attacker or a caller could exploit, or noise " +
+                "(a constant, dead code, a test, a value no caller can influence). Answer with exactly " +
+                'one JSON object and nothing else: {"verdict":"real"|"noise","reason":"<one sentence>"}.',
+        },
+        {
+            role: "user",
+            content: `Rule: ${c.ruleIds.join(", ")}\n` +
+                `Weakness: ${c.vulnerabilityId}\n` +
+                `Rule message: ${c.message}\n` +
+                `File: ${c.path} lines ${c.line}-${c.endLine}\n\n` +
+                `${snippet || "(source not available)"}`,
+        },
+    ];
+}
+/**
+ * Parse the model's answer. Tolerant of prose around the object, strict about
+ * the verdict: anything but a clear "real" is noise, because a Finding the
+ * model did not clearly confirm is exactly the noise this task exists to drop.
+ */
+export function parseTriage(text) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (m) {
+        try {
+            const obj = JSON.parse(m[0]);
+            const verdict = String(obj.verdict ?? "").toLowerCase() === "real" ? "real" : "noise";
+            const reason = typeof obj.reason === "string" && obj.reason.trim() ? obj.reason.trim() : "no reason given";
+            return { verdict, reason };
+        }
+        catch {
+            // fall through
+        }
+    }
+    return { verdict: "noise", reason: `model answer was not the expected JSON: ${text.slice(0, 120)}` };
+}
+/**
+ * The model behind the task grant: one `LLMComplete` on the harness per
+ * candidate, on the tenant's own provider, through the harness so the call is
+ * traced and budgeted like every other model call the run makes.
+ */
+export function harnessTriageModel(harness, slot = "primary") {
+    return async (c, snippet) => {
+        const res = await harness.client.lLMComplete({
+            context: harness.context,
+            slot,
+            messages: triageMessages(c, snippet).map((m) => ({ role: m.role, content: m.content })),
+            temperature: 0,
+            stop: [],
+        });
+        if (res.error)
+            throw new Error(`LLMComplete refused: ${res.error.message}`);
+        return parseTriage(res.content);
+    };
+}
+/** semgrep's level mapped onto the Finding severity scale. */
+export function findingSeverity(level) {
+    if (level === "ERROR")
+        return "high";
+    if (level === "WARNING")
+        return "medium";
+    return "low";
+}
+/**
+ * Build the Finding for a real candidate. The Vulnerability id, the file and
+ * the line travel in the title, the tags and the evidence, so they survive the
+ * typed `SubmitFinding` mapping, which carries no free-form metadata.
+ */
+export function candidateFinding(c, triage, snippet, prov) {
+    const where = `${c.path}:${c.line}`;
+    return newFinding({
+        title: `${c.vulnerabilityId} at ${where}: ${c.message.split(".")[0] ?? c.message}`.slice(0, 200),
+        description: `${c.message}\n\n` +
+            `Vulnerability: ${c.vulnerabilityId}\n` +
+            `File: ${c.path}\nLines: ${c.line}-${c.endLine}\n` +
+            `Rules: ${c.ruleIds.join(", ")}\n` +
+            (prov.repository ? `Repository: ${prov.repository}${prov.commit ? ` @ ${prov.commit}` : ""}\n` : "") +
+            `\nTriage: ${triage.reason}`,
+        category: c.category ?? "source",
+        severity: findingSeverity(c.severity),
+        confidence: 0.8,
+        missionID: prov.missionId ?? "",
+        agentName: "zerocool",
+        ...(prov.targetId ? { targetID: prov.targetId } : {}),
+        tags: [
+            "source-analysis",
+            `vulnerability:${c.vulnerabilityId}`,
+            `file:${c.path}`,
+            `line:${c.line}`,
+            ...c.ruleIds.map((r) => `semgrep:${r}`),
+            ...(prov.commit ? [`commit:${prov.commit}`] : []),
+        ],
+        evidence: [
+            {
+                type: "code",
+                title: where,
+                content: snippet || "(source not available)",
+                timestamp: new Date().toISOString(),
+                metadata: { path: c.path, line: c.line, end_line: c.endLine, rules: c.ruleIds },
+            },
+        ],
+    });
+}
+/**
+ * One pass: scan, dedupe, triage, submit. A candidate the model or the backend
+ * fails on is recorded in `failed` and the pass continues, so one bad answer
+ * costs one candidate rather than the whole scan. The pass never throws for a
+ * clean checkout; it throws only when semgrep itself could not run.
+ */
+export async function runSourceAnalysis(opts) {
+    const emit = opts.onEvent ?? (() => { });
+    const semgrep = opts.semgrep ?? runSemgrep;
+    emit({ type: "source_analysis", phase: "semgrep", dir: opts.dir });
+    const matches = await semgrep({
+        dir: opts.dir,
+        ...(opts.rules ? { rules: opts.rules } : {}),
+        ...(opts.semgrepTimeoutMs ? { timeoutMs: opts.semgrepTimeoutMs } : {}),
+    });
+    const candidates = dedupeCandidates(matches);
+    emit({ type: "source_analysis", phase: "candidates", matches: matches.length, candidates: candidates.length });
+    const summary = {
+        matches: matches.length,
+        candidates: candidates.length,
+        real: 0,
+        noise: 0,
+        findingIds: [],
+        failed: [],
+        verdicts: [],
+    };
+    for (const c of candidates) {
+        const label = `${c.path}:${c.line} ${c.vulnerabilityId}`;
+        const snippet = await readSnippet(opts.dir, c, opts.readFile);
+        let triage;
+        try {
+            triage = await opts.model(c, snippet);
+        }
+        catch (e) {
+            summary.failed.push({ candidate: label, error: `triage: ${e.message}` });
+            emit({ type: "source_analysis", phase: "triage", candidate: label, error: e.message });
+            continue;
+        }
+        summary.verdicts.push({ candidate: label, vulnerabilityId: c.vulnerabilityId, verdict: triage.verdict, reason: triage.reason });
+        emit({ type: "source_analysis", phase: "triage", candidate: label, verdict: triage.verdict, reason: triage.reason });
+        if (triage.verdict !== "real") {
+            summary.noise += 1;
+            continue;
+        }
+        summary.real += 1;
+        const finding = candidateFinding(c, triage, snippet, opts.provenance ?? {});
+        try {
+            const id = await opts.findings.submit(finding);
+            summary.findingIds.push(id);
+            emit({ type: "source_analysis", phase: "submit", candidate: label, finding_id: id });
+        }
+        catch (e) {
+            summary.failed.push({ candidate: label, error: `submit: ${e.message}` });
+            emit({ type: "source_analysis", phase: "submit", candidate: label, error: e.message });
+        }
+    }
+    emit({ type: "source_analysis", phase: "done", ...summaryCounts(summary) });
+    return summary;
+}
+function summaryCounts(s) {
+    return { matches: s.matches, candidates: s.candidates, real: s.real, noise: s.noise, submitted: s.findingIds.length, failed: s.failed.length };
+}
+/** The human-readable result the mission node records. */
+export function formatSourceAnalysis(s) {
+    const lines = [
+        `source analysis: ${s.matches} semgrep matches, ${s.candidates} candidates, ` +
+            `${s.real} real, ${s.noise} noise, ${s.findingIds.length} findings submitted, ${s.failed.length} failed`,
+    ];
+    for (const v of s.verdicts)
+        lines.push(`- ${v.verdict.padEnd(5)} ${v.candidate}: ${v.reason}`);
+    for (const f of s.failed)
+        lines.push(`- FAILED ${f.candidate}: ${f.error}`);
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
   "license": "MIT",
   "repository": {
@@ -14,7 +14,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "semgrep"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -22,7 +23,7 @@
     "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\""
   },
   "dependencies": {
-    "@zeroroot-ai/sdk": "^0.4.0"
+    "@zeroroot-ai/sdk": "^0.9.0"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "*"

package/semgrep/rules.yaml

@@ -0,0 +1,178 @@
+# The pinned semgrep ruleset the zerocool source-analysis task runs
+# (zerocool-plugins#87). Vendored, not fetched: the sandbox must produce the
+# same candidate list for the same checkout on every run, with no registry
+# call and no telemetry. Every rule names the CWE it detects in metadata.cwe;
+# the task turns that into the Finding's Vulnerability id. A rule without a
+# CWE gets a platform id instead (zerocool:semgrep:<rule id>).
+#
+# Rules are candidates, not verdicts. The model triages each match; a rule
+# here may be noisy on purpose as long as the match carries enough context
+# to be judged. Keep the set small and cross-language; a rule that never
+# yields a real finding in the demo fixture or a real repository is removed.
+rules:
+  - id: js-eval-of-request-input
+    languages: [javascript, typescript]
+    severity: ERROR
+    message: >-
+      eval() runs a string that comes from request input. An attacker who
+      controls that input runs arbitrary code in the server process.
+    patterns:
+      - pattern-either:
+          - pattern: eval($ARG)
+          - pattern: new Function($ARG)
+      - metavariable-pattern:
+          metavariable: $ARG
+          pattern-either:
+            - pattern: $REQ.body.$X
+            - pattern: $REQ.query.$X
+            - pattern: $REQ.params.$X
+            - pattern: $REQ.body
+            - pattern: $REQ.query
+    metadata:
+      cwe: "CWE-95: Improper Neutralization of Directives in Dynamically Evaluated Code"
+      category: injection
+
+  - id: js-eval-any
+    languages: [javascript, typescript]
+    severity: WARNING
+    message: >-
+      eval() on a value. Real when the value can be influenced by a caller;
+      noise when it is a constant.
+    pattern: eval($ARG)
+    metadata:
+      cwe: "CWE-95: Improper Neutralization of Directives in Dynamically Evaluated Code"
+      category: injection
+
+  - id: js-child-process-shell-concat
+    languages: [javascript, typescript]
+    severity: ERROR
+    message: >-
+      A shell command is built by string concatenation and run through
+      child_process. Input in the string becomes shell syntax.
+    patterns:
+      - pattern-either:
+          - pattern: $CP.exec($CMD, ...)
+          - pattern: $CP.execSync($CMD, ...)
+          - pattern: exec($CMD, ...)
+          - pattern: execSync($CMD, ...)
+      - metavariable-pattern:
+          metavariable: $CMD
+          pattern-either:
+            - pattern: $A + $B
+            - pattern: "`...${$X}...`"
+    metadata:
+      cwe: "CWE-78: Improper Neutralization of Special Elements used in an OS Command"
+      category: injection
+
+  - id: js-sql-string-concat
+    languages: [javascript, typescript]
+    severity: ERROR
+    message: >-
+      A SQL query is built by string concatenation or interpolation and passed
+      to a query function. Use a parameterized query.
+    patterns:
+      - pattern-either:
+          - pattern: $DB.query($SQL, ...)
+          - pattern: $DB.raw($SQL, ...)
+          - pattern: $DB.execute($SQL, ...)
+      - metavariable-pattern:
+          metavariable: $SQL
+          pattern-either:
+            - pattern: $A + $B
+            - pattern: "`...${$X}...`"
+    metadata:
+      cwe: "CWE-89: Improper Neutralization of Special Elements used in an SQL Command"
+      category: injection
+
+  - id: js-hardcoded-jwt-secret
+    languages: [javascript, typescript]
+    severity: ERROR
+    message: >-
+      A JWT is signed or verified with a string literal secret. Anyone who
+      reads the source can forge tokens.
+    patterns:
+      - pattern-either:
+          - pattern: $JWT.sign($P, "$SECRET", ...)
+          - pattern: $JWT.verify($T, "$SECRET", ...)
+    metadata:
+      cwe: "CWE-798: Use of Hard-coded Credentials"
+      category: secrets-exposure
+
+  - id: js-express-res-send-request-input
+    languages: [javascript, typescript]
+    severity: WARNING
+    message: >-
+      Request input is written straight into the response body. If the
+      response is HTML this is reflected cross-site scripting.
+    patterns:
+      - pattern-either:
+          - pattern: $RES.send($ARG)
+          - pattern: $RES.write($ARG)
+      - metavariable-pattern:
+          metavariable: $ARG
+          pattern-either:
+            - pattern: $REQ.query.$X
+            - pattern: $REQ.params.$X
+            - pattern: $REQ.body.$X
+            - pattern: "`...${$REQ.query.$X}...`"
+            - pattern: "`...${$REQ.params.$X}...`"
+            - pattern: $A + $REQ.query.$X
+            - pattern: $A + $REQ.params.$X
+    metadata:
+      cwe: "CWE-79: Improper Neutralization of Input During Web Page Generation"
+      category: injection
+
+  - id: py-subprocess-shell-true
+    languages: [python]
+    severity: ERROR
+    message: >-
+      subprocess is called with shell=True and a command that is not a
+      constant. Input in the command becomes shell syntax.
+    patterns:
+      - pattern-either:
+          - pattern: subprocess.$F($CMD, ..., shell=True, ...)
+      - pattern-not: subprocess.$F("...", ..., shell=True, ...)
+    metadata:
+      cwe: "CWE-78: Improper Neutralization of Special Elements used in an OS Command"
+      category: injection
+
+  - id: py-yaml-unsafe-load
+    languages: [python]
+    severity: ERROR
+    message: yaml.load without a safe Loader deserializes arbitrary objects.
+    patterns:
+      - pattern: yaml.load($X)
+    metadata:
+      cwe: "CWE-502: Deserialization of Untrusted Data"
+      category: deserialization
+
+  - id: go-sql-string-concat
+    languages: [go]
+    severity: ERROR
+    message: >-
+      A SQL query is built with fmt.Sprintf or concatenation and passed to the
+      database. Use placeholders.
+    patterns:
+      - pattern-either:
+          - pattern: $DB.Query(fmt.Sprintf(...), ...)
+          - pattern: $DB.Exec(fmt.Sprintf(...), ...)
+          - pattern: $DB.QueryRow(fmt.Sprintf(...), ...)
+          - pattern: $DB.Query($A + $B, ...)
+          - pattern: $DB.Exec($A + $B, ...)
+    metadata:
+      cwe: "CWE-89: Improper Neutralization of Special Elements used in an SQL Command"
+      category: injection
+
+  - id: go-exec-command-shell
+    languages: [go]
+    severity: WARNING
+    message: >-
+      A shell is invoked with -c and a command that is not a constant.
+    patterns:
+      - pattern-either:
+          - pattern: exec.Command("sh", "-c", $CMD, ...)
+          - pattern: exec.Command("bash", "-c", $CMD, ...)
+      - pattern-not: exec.Command("...", "-c", "...", ...)
+    metadata:
+      cwe: "CWE-78: Improper Neutralization of Special Elements used in an OS Command"
+      category: injection