@zeroroot-ai/zerocool 0.4.0 → 0.6.0

package/dist/dispatch.d.ts

@@ -57,8 +57,10 @@
  */
 import { type AgentOutcome, type TaskHarness } from "@zeroroot-ai/sdk";
 import { type FindingsBackend } from "./findings.js";
+import { type GitLabClient } from "./gitlab.js";
 import { runOpencode } from "./opencode-run.js";
 import type { SemgrepRunner } from "./semgrep.js";
+import { type ScanLauncher, type WatchCheckpoints } from "./watch.js";
 import { type TriageModel } from "./source-analysis.js";
 /**
  * The per-dispatch grant, as the sandbox injects it. The child authenticates its
@@ -126,8 +128,30 @@ export interface DecodedTask {
  * value that is not a string is dropped rather than guessed at.
  */
 export declare function decodeTask(taskB64: string | undefined): DecodedTask;
+/**
+ * Read one `Task.context` / `Task.metadata` entry as a string.
+ *
+ * Both maps are `map<string, gibson.common.v1.TypedValue>`, so canonical
+ * protojson renders every value as a one-key object naming the oneof arm —
+ * `{"stringValue":"source-analysis"}`, `{"intValue":"42"}` — never as a bare
+ * string. gibson marshals the Task with `protojson.Marshal` over
+ * `agent.TaskToProto`, which wraps each entry with `mapToTypedValueMap`, so
+ * this is the only shape a dispatched agent ever receives. Reading these maps
+ * as plain strings silently dropped every entry, which is why a mission node's
+ * `zerocool.task`, `repository.commit` and `target.id` never reached the run.
+ *
+ * A bare string is still accepted, because a hand-built Task written as plain
+ * JSON is the normal way to drive a dispatch by hand. Both snake_case and
+ * lowerCamel arm names are read: protojson emits lowerCamel by default but can
+ * be told to keep the proto field names, and a decoder that accepts only one of
+ * them fails on a Task that is otherwise valid.
+ *
+ * `nullValue` yields no entry: a null is the absence of a value, and rendering
+ * it as the string "null" would hand a task a target id of `"null"`.
+ */
+export declare function typedValueString(val: unknown): string | undefined;
 /** The task kinds a sandboxed dispatch can serve. */
-export type DispatchTaskKind = "opencode" | "source-analysis";
+export type DispatchTaskKind = "opencode" | "source-analysis" | "watch";
 /**
  * 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.
@@ -164,6 +188,20 @@ export interface DispatchDeps {
     harness?: (ctx: DispatchContext) => TaskHarness;
     /** Force the task kind, over the Task's own context. */
     taskKind?: DispatchTaskKind;
+    /** Watch seams: no GitLab, no World and no child missions in a test. */
+    watch?: WatchDeps;
+}
+/** The watch task's injectable seams. Everything the loop reaches out through. */
+export interface WatchDeps {
+    gitlab?: GitLabClient;
+    checkpoints?: WatchCheckpoints;
+    scans?: ScanLauncher;
+    /** Resolve the GitLab token. Defaults to the harness `GetCredential`. */
+    credential?: (name: string) => Promise<string>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Bound the loop. Unset runs until the sandbox is torn down. */
+    maxPolls?: number;
+    signal?: AbortSignal;
 }
 /**
  * Run one dispatched Task headless and map it to a terminal outcome.
@@ -185,6 +223,31 @@ export declare function runDispatch(ctx: DispatchContext, deps?: DispatchDeps):
  * `repository.url`, `repository.commit`, `target.id`.
  */
 export declare function runSourceAnalysisDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * The watch task, sandboxed (zerocool-plugins#88). The always-on shape: this
+ * dispatch does not finish until the mission is cancelled or the sandbox is
+ * torn down. It polls the application's GitLab project and originates a Scan
+ * mission per finished pipeline on the branch, from inside this very mission
+ * (ADR-0063). See `watch.ts` for why the agent polls rather than CI calling in.
+ *
+ * Task context keys it reads:
+ *   `zerocool.task`        selector, "watch"
+ *   `application`          the Application this watch follows (required)
+ *   `gitlab.project`       `group/project` on the instance (required)
+ *   `gitlab.url`           instance base url; defaults to gitlab.com
+ *   `gitlab.ref`           branch to watch; defaults to `main`
+ *   `gitlab.credential`    tenant secret holding the project access token
+ *   `repository.url`       clone url handed to each Scan mission
+ *   `target.id`            the registered target each Scan mission binds to
+ *   `watch.interval_ms`    poll cadence; defaults to 30s
+ */
+export declare function runWatchDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * Resolve a tenant secret through the harness on the dispatch grant. The value
+ * is returned to the caller and never logged: it is the GitLab token, and the
+ * console stream this dispatch writes is shown in the browser.
+ */
+export declare function harnessCredential(harness: TaskHarness): (name: string) => Promise<string>;
 /**
  * Render a terminal outcome as the last NDJSON line on stdout.
  *

package/dist/dispatch.js

@@ -58,7 +58,9 @@
 import { openTaskHarness } from "@zeroroot-ai/sdk";
 import { join } from "node:path";
 import { taskFindingsBackend } from "./findings.js";
+import { gitlabRest } from "./gitlab.js";
 import { runOpencode } from "./opencode-run.js";
+import { DEFAULT_REF, harnessScanLauncher, runWatchLoop, worldCheckpoints, } from "./watch.js";
 import { formatSourceAnalysis, harnessTriageModel, runSourceAnalysis, } from "./source-analysis.js";
 /**
  * Render the per-dispatch grant back to environment for the opencode child, so
@@ -118,11 +120,58 @@ function stringMap(v) {
         return {};
     const out = {};
     for (const [k, val] of Object.entries(v)) {
-        if (typeof val === "string")
-            out[k] = val;
+        const s = typedValueString(val);
+        if (s !== undefined)
+            out[k] = s;
     }
     return out;
 }
+/**
+ * Read one `Task.context` / `Task.metadata` entry as a string.
+ *
+ * Both maps are `map<string, gibson.common.v1.TypedValue>`, so canonical
+ * protojson renders every value as a one-key object naming the oneof arm —
+ * `{"stringValue":"source-analysis"}`, `{"intValue":"42"}` — never as a bare
+ * string. gibson marshals the Task with `protojson.Marshal` over
+ * `agent.TaskToProto`, which wraps each entry with `mapToTypedValueMap`, so
+ * this is the only shape a dispatched agent ever receives. Reading these maps
+ * as plain strings silently dropped every entry, which is why a mission node's
+ * `zerocool.task`, `repository.commit` and `target.id` never reached the run.
+ *
+ * A bare string is still accepted, because a hand-built Task written as plain
+ * JSON is the normal way to drive a dispatch by hand. Both snake_case and
+ * lowerCamel arm names are read: protojson emits lowerCamel by default but can
+ * be told to keep the proto field names, and a decoder that accepts only one of
+ * them fails on a Task that is otherwise valid.
+ *
+ * `nullValue` yields no entry: a null is the absence of a value, and rendering
+ * it as the string "null" would hand a task a target id of `"null"`.
+ */
+export function typedValueString(val) {
+    if (typeof val === "string")
+        return val;
+    if (!val || typeof val !== "object")
+        return undefined;
+    const v = val;
+    const arm = (camel, snake) => (v[camel] !== undefined ? v[camel] : v[snake]);
+    const s = arm("stringValue", "string_value");
+    if (typeof s === "string")
+        return s;
+    // protojson renders int64 and uint64 as strings, and double as a number.
+    const i = arm("intValue", "int_value");
+    if (typeof i === "string" || typeof i === "number")
+        return String(i);
+    const u = arm("uintValue", "uint_value");
+    if (typeof u === "string" || typeof u === "number")
+        return String(u);
+    const d = arm("doubleValue", "double_value");
+    if (typeof d === "number")
+        return String(d);
+    const b = arm("boolValue", "bool_value");
+    if (typeof b === "boolean")
+        return String(b);
+    return undefined;
+}
 /**
  * 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.
@@ -130,7 +179,11 @@ function stringMap(v) {
  */
 export function dispatchTaskKind(ctx, env = {}) {
     const kind = env.ZEROCOOL_TASK ?? ctx.taskContext["zerocool.task"] ?? "";
-    return kind === "source-analysis" ? "source-analysis" : "opencode";
+    if (kind === "source-analysis")
+        return "source-analysis";
+    if (kind === "watch")
+        return "watch";
+    return "opencode";
 }
 /**
  * Read one sandboxed dispatch's context from the environment.
@@ -185,9 +238,13 @@ 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") {
+    const kind = deps.taskKind ?? dispatchTaskKind(ctx, process.env);
+    if (kind === "source-analysis") {
         return runSourceAnalysisDispatch(ctx, deps);
     }
+    if (kind === "watch") {
+        return runWatchDispatch(ctx, deps);
+    }
     const run = deps.run ?? runOpencode;
     const result = await run({
         goal: ctx.goal,
@@ -264,6 +321,119 @@ export async function runSourceAnalysisDispatch(ctx, deps = {}) {
             harness?.stop();
     }
 }
+/**
+ * The watch task, sandboxed (zerocool-plugins#88). The always-on shape: this
+ * dispatch does not finish until the mission is cancelled or the sandbox is
+ * torn down. It polls the application's GitLab project and originates a Scan
+ * mission per finished pipeline on the branch, from inside this very mission
+ * (ADR-0063). See `watch.ts` for why the agent polls rather than CI calling in.
+ *
+ * Task context keys it reads:
+ *   `zerocool.task`        selector, "watch"
+ *   `application`          the Application this watch follows (required)
+ *   `gitlab.project`       `group/project` on the instance (required)
+ *   `gitlab.url`           instance base url; defaults to gitlab.com
+ *   `gitlab.ref`           branch to watch; defaults to `main`
+ *   `gitlab.credential`    tenant secret holding the project access token
+ *   `repository.url`       clone url handed to each Scan mission
+ *   `target.id`            the registered target each Scan mission binds to
+ *   `watch.interval_ms`    poll cadence; defaults to 30s
+ */
+export async function runWatchDispatch(ctx, deps = {}) {
+    const w = deps.watch ?? {};
+    const application = ctx.taskContext.application || "";
+    const projectPath = ctx.taskContext["gitlab.project"] || "";
+    const ref = ctx.taskContext["gitlab.ref"] || DEFAULT_REF;
+    const targetId = ctx.taskContext["target.id"] || "";
+    const credentialName = ctx.taskContext["gitlab.credential"] || "gitlab-token";
+    if (!application) {
+        throw new Error("watch: the mission node set no `application` in the task context. The watch keys its " +
+            "checkpoints and its Scan missions by Application; without one it cannot tell its own " +
+            "state from another watch's.");
+    }
+    if (!w.gitlab && !projectPath) {
+        throw new Error("watch: the mission node set no `gitlab.project` in the task context, so there is no " +
+            "project to poll.");
+    }
+    // A harness is opened unless every seam that would use one was injected.
+    const needsHarness = !w.gitlab || !w.checkpoints || !w.scans || !w.credential;
+    const opened = needsHarness && !deps.harness;
+    const harness = needsHarness
+        ? (deps.harness ??
+            ((c) => openTaskHarness({ endpoint: c.callbackEndpoint, token: c.callbackToken, insecure: c.insecure ?? false })))(ctx)
+        : undefined;
+    try {
+        const gitlab = w.gitlab ??
+            gitlabRest({
+                projectPath,
+                token: await (w.credential ?? harnessCredential(harness))(credentialName),
+                ...(ctx.taskContext["gitlab.url"] ? { baseUrl: ctx.taskContext["gitlab.url"] } : {}),
+            });
+        const checkpoints = w.checkpoints ?? worldCheckpoints(harness, application);
+        const scans = w.scans ??
+            harnessScanLauncher(harness, {
+                targetId,
+                inputs: {
+                    application,
+                    repositoryUrl: ctx.taskContext["repository.url"] || "",
+                    ...(ctx.taskContext["image.ref"] ? { imageRef: ctx.taskContext["image.ref"] } : {}),
+                },
+            });
+        const intervalMs = Number(ctx.taskContext["watch.interval_ms"] || Number.NaN);
+        const summary = await runWatchLoop({
+            application,
+            ref,
+            gitlab,
+            checkpoints,
+            scans,
+            ...(Number.isFinite(intervalMs) && intervalMs > 0 ? { intervalMs } : {}),
+            ...(w.maxPolls !== undefined ? { maxPolls: w.maxPolls } : {}),
+            ...(w.signal ? { signal: w.signal } : {}),
+            ...(w.sleep ? { sleep: w.sleep } : {}),
+            ...(deps.onEvent ? { onEvent: (e) => deps.onEvent?.(JSON.stringify(e)) } : {}),
+        });
+        return {
+            output: `watch ${application}@${ref}: ${summary.polls} polls, ${summary.scans} scan missions, ` +
+                `${summary.errors} errors; last pipeline ${summary.lastPipelineId || "none"}`,
+            success: true,
+            metadata: {
+                task: "watch",
+                application,
+                ref,
+                polls: String(summary.polls),
+                scans: String(summary.scans),
+                errors: String(summary.errors),
+                last_pipeline_id: String(summary.lastPipelineId),
+            },
+        };
+    }
+    finally {
+        if (opened)
+            harness?.stop();
+    }
+}
+/**
+ * Resolve a tenant secret through the harness on the dispatch grant. The value
+ * is returned to the caller and never logged: it is the GitLab token, and the
+ * console stream this dispatch writes is shown in the browser.
+ */
+export function harnessCredential(harness) {
+    return async (name) => {
+        const res = await harness.client.getCredential({ context: harness.context, name });
+        if (res.error) {
+            throw new Error(`GetCredential(${name}) refused: ${res.error.message}`);
+        }
+        const secret = res.credential?.secretData;
+        const value = secret?.case === "apiKey" || secret?.case === "bearerToken" || secret?.case === "customSecret"
+            ? secret.value
+            : undefined;
+        if (!value) {
+            throw new Error(`GetCredential(${name}) returned no usable secret. A GitLab project access token is ` +
+                "stored as an api key, a bearer token, or a single-valued custom secret.");
+        }
+        return value;
+    };
+}
 /**
  * Render a terminal outcome as the last NDJSON line on stdout.
  *

package/dist/fix.d.ts

@@ -0,0 +1,207 @@
+import type { FileChange, GitLabWriter, MergeRequest } from "./gitlab.js";
+/**
+ * The Fix — what the always-on agent does with a Finding (zerocool-plugins#89).
+ *
+ * After a Scan mission lands, the agent works the Application's open Findings
+ * in priority order. For each one it can act on it rewrites the repository,
+ * runs the repository's own tests, and only then opens a merge request set to
+ * merge itself when the pipeline succeeds. It records the scan verdict on the
+ * commit as `gibson/scan` and posts one note saying what it fixed, what it did
+ * not, and why.
+ *
+ * THE ORDER IS TESTS, THEN PUSH. A fix that breaks the build is worse than the
+ * Finding: it stops every other fix behind it. So the change is applied to a
+ * workspace, the tests run there, and a failure resets the workspace and leaves
+ * the Finding `open` with its reason recorded. Nothing unproven reaches GitLab.
+ *
+ * THE FIX NEVER MARKS A FINDING `verified`. A merge is not evidence that a
+ * rescan did not see the weakness again — only the rescan is, and absence is
+ * not an observation, so it is reconciled once at a scan's completion
+ * (gibson#1686). The Fix moves a Finding `open` → `fixing` when its merge
+ * request opens and `fixing` → `fixed` when GitLab reports that request merged.
+ *
+ * THE TOKEN NEVER APPEARS IN ANYTHING THIS WRITES. It reaches GitLab only as a
+ * `PRIVATE-TOKEN` header inside {@link gitlabRestWriter}. No branch name, merge
+ * request title, description, note or status description is built from it, and
+ * `fix.test.ts` proves that with a sentinel that would show up in every
+ * recorded output if it ever did.
+ *
+ * TWO SEAMS ARE DELIBERATELY UNIMPLEMENTED HERE. Reading an Application's
+ * Findings and writing a Finding's status both exist on the Go SDK as of
+ * v0.174.0, and on neither the TypeScript SDK nor this package: `@zeroroot-ai/sdk`
+ * carries no `applicationFindings` and its `observe` admits only host, domain,
+ * subdomain, credential, account and memory. That is sdk-ts#51. Until it lands,
+ * {@link FindingSource} and {@link FindingStatusWriter} have no platform
+ * implementation, and the Fix is driven by whatever supplies them. This is a
+ * seam, not a second code path: when the wire arrives there is one
+ * implementation to add and nothing here changes.
+ */
+/** Severities, worst first. Used for the note's counts and for a stable order. */
+export declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+/** A Finding as the Fix needs it — the read half of sdk-ts#51. */
+export interface FixableFinding {
+    /** The graph's `brain_id`, so a write lands on the node that was read. */
+    id: string;
+    /** `open`, `fixing`, `fixed` or `verified`. */
+    status: string;
+    severity: string;
+    /** The CVE, GHSA or platform id this Finding is an instance of. */
+    vulnerabilityId: string;
+    /** Where it is: a `Package`, a `Repository` file, or a `Service`. */
+    placeLabel: string;
+    placeKey: string;
+    /** `P1`..`P4` once the read carries what a triage pass decided (gibson#1684). */
+    priority?: string;
+    /** The merge request already opened for this Finding, when it is `fixing`. */
+    mergeRequestIid?: number;
+}
+/** Reads an Application's Findings. Platform implementation pending sdk-ts#51. */
+export interface FindingSource {
+    /**
+     * The Application's Findings in the given statuses, **in the order they
+     * should be worked**. Rejects when the graph is unreachable; it must never
+     * resolve empty to signal failure, because an empty list reads as a healthy
+     * Application and the Fix would report success over a live backlog.
+     */
+    findings(application: string, statuses: string[]): Promise<FixableFinding[]>;
+}
+/** Moves a Finding through its statuses. Platform implementation pending sdk-ts#51. */
+export interface FindingStatusWriter {
+    /** Record that a merge request now proposes this Finding's fix. */
+    markFixing(findingId: string, mr: MergeRequest): Promise<void>;
+    /** Record that the merge request merged. Never `verified` — the rescan does that. */
+    markFixed(findingId: string): Promise<void>;
+}
+/** A checkout the Fix can change and test before anything is pushed. */
+export interface Workspace {
+    /** File contents, or `undefined` when the path does not exist. */
+    read(path: string): Promise<string | undefined>;
+    /** Stage a rewrite in the workspace. Not a push. */
+    write(path: string, content: string): Promise<void>;
+    /** Run the repository's own tests. `output` is quoted in the note on failure. */
+    test(): Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+    /** Discard staged rewrites, so a failed fix does not leak into the next one. */
+    reset(): Promise<void>;
+    /** What was staged, in commit order. */
+    staged(): FileChange[];
+}
+/** What the agent proposes to do about one Finding. */
+export interface FixPlan {
+    /** Which of the three the owner's scope named. Reported in the note. */
+    kind: "dependency" | "source" | "config";
+    /** One line, for the merge request title. */
+    summary: string;
+    /** The commit message body. */
+    detail: string;
+}
+/**
+ * Decides what to change for a Finding, and stages it in the workspace.
+ *
+ * Returning `undefined` means "no strategy for this Finding" — reported in the
+ * note as unfixed with that reason, never silently skipped. A planner that
+ * throws is treated the same way, with its message as the reason: one Finding
+ * with no strategy must not stop the ones behind it.
+ */
+export interface FixPlanner {
+    plan(finding: FixableFinding, ws: Workspace): Promise<FixPlan | undefined>;
+}
+/** What happened to one Finding in a Fix pass. */
+export interface FixOutcome {
+    finding: FixableFinding;
+    /** `fixing` when a merge request opened, `merged` when one already had, else `unfixed`. */
+    result: "fixing" | "merged" | "unfixed";
+    /** Why it is unfixed. Empty otherwise. Quoted verbatim in the note. */
+    reason: string;
+    mergeRequest?: MergeRequest;
+    plan?: FixPlan;
+}
+/** One line of the console stream, so the ops wall shows the Fix working. */
+export type FixEvent = {
+    type: "fix.start";
+    application: string;
+    commit: string;
+    open: number;
+    fixing: number;
+} | {
+    type: "fix.plan";
+    findingId: string;
+    kind: FixPlan["kind"];
+    summary: string;
+} | {
+    type: "fix.tests";
+    findingId: string;
+    ok: boolean;
+} | {
+    type: "fix.mr";
+    findingId: string;
+    iid: number;
+    webUrl: string;
+} | {
+    type: "fix.merged";
+    findingId: string;
+    iid: number;
+} | {
+    type: "fix.skip";
+    findingId: string;
+    reason: string;
+} | {
+    type: "fix.error";
+    stage: "read" | "status" | "note" | "plan";
+    message: string;
+};
+export interface FixSummary {
+    application: string;
+    commit: string;
+    outcomes: FixOutcome[];
+    /** True when every Finding that had a strategy ended `fixing` or `merged`. */
+    clean: boolean;
+}
+export interface RunFixOptions {
+    application: string;
+    /** The commit the Scan mission ran against — what the status is set on. */
+    commit: string;
+    /** The branch merge requests target. */
+    targetRef: string;
+    findings: FindingSource;
+    status: FindingStatusWriter;
+    planner: FixPlanner;
+    workspace: Workspace;
+    gitlab: GitLabWriter;
+    /** The pipeline page, linked from the commit status. */
+    pipelineUrl?: string;
+    /** Cap on merge requests opened in one pass, so a backlog cannot flood review. */
+    maxMergeRequests?: number;
+    onEvent?: (e: FixEvent) => void;
+}
+/** Default ceiling on merge requests opened by one pass. */
+export declare const DEFAULT_MAX_MERGE_REQUESTS = 10;
+/**
+ * Run one Fix pass over an Application.
+ *
+ * Reconcile first, then fix. A Finding already `fixing` whose merge request has
+ * merged becomes `fixed` before anything new is opened, so a pass never opens a
+ * second merge request for a Finding the previous pass already resolved.
+ */
+export declare function runFix(opts: RunFixOptions): Promise<FixSummary>;
+/**
+ * The branch one Finding's fix lands on. Stable, so a retry reuses it rather
+ * than opening a second merge request for the same Finding.
+ *
+ * The slug keeps only `[a-z0-9-]`. Dots are dropped rather than preserved:
+ * git refuses a ref containing `..`, and a vulnerability id is attacker-
+ * adjacent text that ends up interpolated into a URL path, so a dot run is
+ * exactly the shape not to carry through. The Finding id is appended so two
+ * occurrences of one CVE get two branches.
+ */
+export declare function fixBranch(finding: FixableFinding): string;
+/** Counts by severity, worst first, for the note and the status line. */
+export declare function countsBySeverity(findings: FixableFinding[]): Record<string, number>;
+/** The one-line verdict GitLab shows beside the commit. */
+export declare function statusDescription(summary: FixSummary): string;
+/** The merge request description. Names the Finding it closes and how. */
+export declare function mergeRequestBody(finding: FixableFinding, plan: FixPlan): string;
+/** The note posted on each merge request: what this pass did, in full. */
+export declare function noteBody(summary: FixSummary): string;