@zeroroot-ai/zerocool 0.4.0 → 0.5.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/gitlab.d.ts

@@ -0,0 +1,74 @@
+/**
+ * GitLab — the trigger the always-on agent watches (zerocool-plugins#88).
+ *
+ * The agent polls one project's pipelines on one branch. It never receives a
+ * webhook and GitLab holds no Gibson credential: the poll runs outbound from
+ * the sandbox on the tenant's own project access token, resolved through the
+ * harness `GetCredential` under the dispatch grant. That direction is the point
+ * — a CI job cannot originate a Gibson mission (ADR-0063 admits a component
+ * only from inside a mission it was dispatched to), so the agent watches
+ * GitLab rather than GitLab calling Gibson.
+ *
+ * FINISHED MEANS `success`. A pipeline that failed published no image and left
+ * `main` unchanged, so there is nothing new to scan; treating it as a trigger
+ * would run a Scan mission against the image the previous pipeline built and
+ * report its findings against the new commit. `canceled` and `skipped` are the
+ * same case. The status this polls for is therefore `success`, named once in
+ * {@link TRIGGER_STATUS} rather than spelled at each call site.
+ *
+ * Everything here is one `fetch` away from pure: {@link gitlabRest} takes the
+ * fetch it uses, so `watch.test.ts` drives a whole loop against a stub with no
+ * network and no token.
+ */
+/** The pipeline status that triggers a Scan mission. See the module note. */
+export declare const TRIGGER_STATUS = "success";
+/** GitLab's public host, when a tenant names no other instance. */
+export declare const GITLAB_DEFAULT_URL = "https://gitlab.com";
+/** One pipeline, reduced to what a trigger decision and a Scan mission need. */
+export interface Pipeline {
+    /** GitLab's own pipeline id. Monotonic per project, and the checkpoint key. */
+    id: number;
+    /** The commit the pipeline ran on — the Scan mission's `repository.commit`. */
+    sha: string;
+    /** `success` for anything this module returns; carried for the console line. */
+    status: string;
+    /** The branch, echoed back so a caller can log what it matched. */
+    ref: string;
+    /** GitLab's page for the pipeline, for the console line and the MR note. */
+    webUrl: string;
+}
+/** The GitLab reads the watch loop makes. One method, so a stub is three lines. */
+export interface GitLabClient {
+    /**
+     * The most recent successful pipeline on `ref`, or `undefined` when the
+     * project has none. Rejects when GitLab refuses or is unreachable — the loop
+     * reports that and keeps polling.
+     */
+    latestFinishedPipeline(ref: string): Promise<Pipeline | undefined>;
+}
+/** What {@link gitlabRest} needs to reach one project. */
+export interface GitLabRestOptions {
+    /** `group/project`, unencoded. Encoded once here, at the call. */
+    projectPath: string;
+    /** The project access token, resolved from the tenant secret store. */
+    token: string;
+    /** The instance. Defaults to {@link GITLAB_DEFAULT_URL}. */
+    baseUrl?: string;
+    /** Injectable transport. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Read one pipeline out of GitLab's JSON. A row without an id or a sha is
+ * dropped rather than guessed at: a Scan mission keyed on a missing commit
+ * would scan whatever the workspace happened to hold.
+ */
+export declare function parsePipeline(raw: unknown): Pipeline | undefined;
+/**
+ * A {@link GitLabClient} over GitLab's REST API.
+ *
+ * The token travels in `PRIVATE-TOKEN`, which is what a project access token
+ * authenticates with. It is never logged and never placed in a URL, so it
+ * cannot reach the console stream through an error message that quotes the
+ * request.
+ */
+export declare function gitlabRest(opts: GitLabRestOptions): GitLabClient;

package/dist/gitlab.js

@@ -0,0 +1,82 @@
+/**
+ * GitLab — the trigger the always-on agent watches (zerocool-plugins#88).
+ *
+ * The agent polls one project's pipelines on one branch. It never receives a
+ * webhook and GitLab holds no Gibson credential: the poll runs outbound from
+ * the sandbox on the tenant's own project access token, resolved through the
+ * harness `GetCredential` under the dispatch grant. That direction is the point
+ * — a CI job cannot originate a Gibson mission (ADR-0063 admits a component
+ * only from inside a mission it was dispatched to), so the agent watches
+ * GitLab rather than GitLab calling Gibson.
+ *
+ * FINISHED MEANS `success`. A pipeline that failed published no image and left
+ * `main` unchanged, so there is nothing new to scan; treating it as a trigger
+ * would run a Scan mission against the image the previous pipeline built and
+ * report its findings against the new commit. `canceled` and `skipped` are the
+ * same case. The status this polls for is therefore `success`, named once in
+ * {@link TRIGGER_STATUS} rather than spelled at each call site.
+ *
+ * Everything here is one `fetch` away from pure: {@link gitlabRest} takes the
+ * fetch it uses, so `watch.test.ts` drives a whole loop against a stub with no
+ * network and no token.
+ */
+/** The pipeline status that triggers a Scan mission. See the module note. */
+export const TRIGGER_STATUS = "success";
+/** GitLab's public host, when a tenant names no other instance. */
+export const GITLAB_DEFAULT_URL = "https://gitlab.com";
+/**
+ * Read one pipeline out of GitLab's JSON. A row without an id or a sha is
+ * dropped rather than guessed at: a Scan mission keyed on a missing commit
+ * would scan whatever the workspace happened to hold.
+ */
+export function parsePipeline(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const p = raw;
+    const id = typeof p.id === "number" ? p.id : Number.NaN;
+    const sha = typeof p.sha === "string" ? p.sha : "";
+    if (!Number.isInteger(id) || id <= 0 || !sha)
+        return undefined;
+    return {
+        id,
+        sha,
+        status: typeof p.status === "string" ? p.status : "",
+        ref: typeof p.ref === "string" ? p.ref : "",
+        webUrl: typeof p.web_url === "string" ? p.web_url : "",
+    };
+}
+/**
+ * A {@link GitLabClient} over GitLab's REST API.
+ *
+ * The token travels in `PRIVATE-TOKEN`, which is what a project access token
+ * authenticates with. It is never logged and never placed in a URL, so it
+ * cannot reach the console stream through an error message that quotes the
+ * request.
+ */
+export function gitlabRest(opts) {
+    const base = (opts.baseUrl || GITLAB_DEFAULT_URL).replace(/\/+$/, "");
+    const project = encodeURIComponent(opts.projectPath);
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    return {
+        async latestFinishedPipeline(ref) {
+            const url = `${base}/api/v4/projects/${project}/pipelines` +
+                `?ref=${encodeURIComponent(ref)}&status=${TRIGGER_STATUS}&order_by=id&sort=desc&per_page=1`;
+            const res = await doFetch(url, {
+                headers: { "PRIVATE-TOKEN": opts.token, Accept: "application/json" },
+            });
+            if (!res.ok) {
+                throw new Error(`GitLab pipelines for ${opts.projectPath}@${ref} returned ${res.status} ${res.statusText}`);
+            }
+            const body = await res.json();
+            if (!Array.isArray(body)) {
+                throw new Error(`GitLab pipelines for ${opts.projectPath}@${ref} returned ${typeof body}, expected an array`);
+            }
+            for (const row of body) {
+                const p = parsePipeline(row);
+                if (p)
+                    return p;
+            }
+            return undefined;
+        },
+    };
+}

package/dist/watch.d.ts

@@ -0,0 +1,214 @@
+import { type TaskHarness } from "@zeroroot-ai/sdk";
+import { type GitLabClient, type Pipeline } from "./gitlab.js";
+/**
+ * The always-on watch loop (zerocool-plugins#88).
+ *
+ * Dispatched into a `watch-<application>` mission, the agent does not run a
+ * task and exit. It polls the application's GitLab project every 30 seconds,
+ * and on each finished pipeline on `main` it has not seen it originates a Scan
+ * mission, waits for it, and goes back to polling. The loop ends when the
+ * mission is cancelled or the sandbox is torn down, not on its own.
+ *
+ * WHY THE AGENT POLLS RATHER THAN CI CALLING GIBSON. ADR-0063 lets a component
+ * originate a mission only from inside one it was dispatched to. A GitLab job
+ * is not inside a mission, so it cannot originate a Scan mission whatever
+ * credential it holds. The person originates the long-lived watch mission once;
+ * every Scan mission after that is originated by the agent from inside it,
+ * through `HarnessCallbackService.CreateMission` on the dispatch grant. Since
+ * gibson#1657 that RPC takes its parent, tenant and lineage from the resolved
+ * harness rather than the request, so the child is attributed to this mission
+ * and a caller outside a live mission is refused outright.
+ *
+ * ONLY THE LATEST PIPELINE IS EVER CONSIDERED. The loop asks GitLab for the
+ * most recent successful pipeline on the branch — never for a backlog. That is
+ * what makes the checkpoint safe to lose: an unreadable checkpoint costs one
+ * redundant Scan of the current head, never a stampede over a project's
+ * history. A checkpoint is an optimisation against duplicate work, not a
+ * correctness gate, and the loop is written so that is true.
+ *
+ * THE CHECKPOINT IS AN OBSERVATION, NOT A FILE. The sandbox is ephemeral, so
+ * anything written to its disk dies with it. The last pipeline seen goes into
+ * the World as a memory observation under the dispatch grant, which is the same
+ * write path every other thing the agent learns takes.
+ */
+/** The observation `kind` the checkpoint is written under. */
+export declare const CHECKPOINT_KIND = "watch-checkpoint";
+/** Default poll interval. The issue's cadence, and slow enough for GitLab. */
+export declare const DEFAULT_INTERVAL_MS = 30000;
+/** Default ceiling on one Scan mission before the loop stops waiting on it. */
+export declare const DEFAULT_SCAN_TIMEOUT_MS: number;
+/** The branch a watch follows unless the task says otherwise. */
+export declare const DEFAULT_REF = "main";
+/**
+ * Poll state, kept in the World so a restarted agent resumes.
+ *
+ * `last` returning 0 means "nothing recorded, or the record could not be read".
+ * Both are the same instruction to the loop — scan the current head once — so
+ * there is nothing here for a caller to distinguish or get wrong.
+ */
+export interface WatchCheckpoints {
+    last(): Promise<number>;
+    record(p: Pipeline): Promise<void>;
+}
+/** Originates and awaits one Scan mission. */
+export interface ScanLauncher {
+    /** Create and run the Scan mission for `p`. Returns its mission id. */
+    launch(p: Pipeline): Promise<string>;
+    /** Block until that mission is terminal. Returns its status, for the console. */
+    wait(missionId: string): Promise<string>;
+}
+/** One line of the console stream. Rendered as NDJSON by the dispatch driver. */
+export type WatchEvent = {
+    type: "watch.start";
+    application: string;
+    ref: string;
+    lastPipelineId: number;
+} | {
+    type: "watch.poll";
+    application: string;
+    ref: string;
+    pipelineId: number;
+    status: string;
+    fresh: boolean;
+} | {
+    type: "watch.scan";
+    application: string;
+    pipelineId: number;
+    commit: string;
+    missionId: string;
+} | {
+    type: "watch.scan.done";
+    application: string;
+    pipelineId: number;
+    missionId: string;
+    status: string;
+} | {
+    type: "watch.error";
+    application: string;
+    stage: "checkpoint" | "poll" | "scan" | "record";
+    message: string;
+};
+/** What one watch run reports back when it is asked to stop. */
+export interface WatchSummary {
+    polls: number;
+    scans: number;
+    errors: number;
+    lastPipelineId: number;
+}
+export interface WatchLoopOptions {
+    /** The Application this watch follows, e.g. `customer-portal`. */
+    application: string;
+    /** The branch whose pipelines trigger a Scan. */
+    ref?: string;
+    gitlab: GitLabClient;
+    checkpoints: WatchCheckpoints;
+    scans: ScanLauncher;
+    /** Poll cadence. Defaults to {@link DEFAULT_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Stop after this many polls. Unset runs until aborted — the real posture. */
+    maxPolls?: number;
+    /** Cooperative stop, so a caller can end the loop between polls. */
+    signal?: AbortSignal;
+    /** Console stream. Every poll emits one line so the ops wall shows life. */
+    onEvent?: (e: WatchEvent) => void;
+    /** Test seams. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Run the watch loop.
+ *
+ * Nothing in here throws for an expected failure. A GitLab outage, a refused
+ * Scan, a checkpoint that cannot be written — each is reported to the console
+ * and the loop keeps polling, because an always-on agent that exits on the
+ * first transient error is not always-on. The one thing it will not do is
+ * record a checkpoint for a Scan it failed to originate: that pipeline is
+ * retried on the next poll.
+ */
+export declare function runWatchLoop(opts: WatchLoopOptions): Promise<WatchSummary>;
+/**
+ * The checkpoint fact, in one parseable line.
+ *
+ * A memory is free text by design, so the loop writes a line it can read back
+ * without depending on which properties the projector chose to keep. The
+ * application is part of the line, so one tenant's several watches never read
+ * each other's checkpoints.
+ */
+export declare function checkpointText(application: string, p: Pipeline): string;
+/** The checkpoint a line carries, or `undefined` when it is not one. */
+export declare function parseCheckpoint(text: string): {
+    application: string;
+    pipelineId: number;
+    commit: string;
+} | undefined;
+/**
+ * Checkpoints kept in the tenant World under the dispatch grant.
+ *
+ * The write is `Observe` with a memory shape, which the Taxonomy gate lands as
+ * an `Observation` node. The read is the graph query for those observations.
+ *
+ * DAEMON STATE, and why the loop is built to survive it: the SDK records that
+ * `QueryNodes` is declared but not wired at the daemon's registration site and
+ * answers `Unimplemented` on a live cluster (gibson#1186). Until that seam is
+ * wired, `last` reports 0 and the loop scans the current head once per restart
+ * rather than resuming — which is the same behaviour as a first run, and is why
+ * the loop never reads a backlog.
+ */
+export declare function worldCheckpoints(harness: TaskHarness, application: string): WatchCheckpoints;
+/** The recall text for an application's checkpoints. Exported so a test names it once. */
+export declare function checkpointQueryText(application: string): string;
+/** What a Scan mission needs to know about the pipeline that triggered it. */
+export interface ScanMissionInputs {
+    application: string;
+    pipeline: Pipeline;
+    /** The project's clone url, so the Scan mission knows what to check out. */
+    repositoryUrl: string;
+    /** The image the pipeline built, when the watch was told how to name it. */
+    imageRef?: string;
+    /** The registered target the runtime scans are allowed to reach. */
+    targetId?: string;
+}
+/**
+ * The Scan mission definition, as canonical proto JSON.
+ *
+ * A PLACEHOLDER WITH A REAL SHAPE. gibson#1660 owns the Scan mission proper —
+ * Trivy on the image, source analysis on the commit, and the runtime tools
+ * against the target, fanned out and joined. Until it lands, this originates
+ * the one node that exists today: zerocool's source-analysis task
+ * (zerocool-plugins#87) on the pipeline's commit. Everything the full fan-out
+ * needs is already carried in the node's task context, so gibson#1660 replaces
+ * the body of this one function and nothing else in the loop changes.
+ *
+ * The definition is built as protojson by hand rather than through the
+ * generated schema because the SDK's package exports only its index, and the
+ * mission schema is not re-exported from it.
+ */
+export declare function scanMissionDefinition(inputs: ScanMissionInputs): unknown;
+/** The child mission's name, which is also how a person finds it in the dashboard. */
+export declare function scanMissionName(inputs: ScanMissionInputs): string;
+/**
+ * Render a string map as `map<string, gibson.common.v1.TypedValue>` in
+ * protojson. Every value the loop passes is a string, so every entry is a
+ * `stringValue`.
+ */
+export declare function typedContext(ctx: Record<string, string>): Record<string, {
+    stringValue: string;
+}>;
+export interface HarnessScanLauncherOptions {
+    /** Everything but the pipeline, which the launcher fills in per trigger. */
+    inputs: Omit<ScanMissionInputs, "pipeline">;
+    /** The target the child mission binds to. Its scope for every observation. */
+    targetId: string;
+    /** Ceiling on one Scan. Defaults to {@link DEFAULT_SCAN_TIMEOUT_MS}. */
+    scanTimeoutMs?: number;
+    /** Override the definition, so gibson#1660 can supply the real one. */
+    definition?: (inputs: ScanMissionInputs) => unknown;
+}
+/**
+ * A {@link ScanLauncher} over the harness callbacks, on the dispatch grant.
+ *
+ * `CreateMission` here is the in-mission origination ADR-0063 permits: the
+ * daemon resolves the parent from this harness, so the Scan mission is a child
+ * of the watch mission and inherits its tenant. Nothing in the request names a
+ * parent, a tenant or an originator, so nothing here can widen them.
+ */
+export declare function harnessScanLauncher(harness: TaskHarness, opts: HarnessScanLauncherOptions): ScanLauncher;

package/dist/watch.js

@@ -0,0 +1,341 @@
+import { remember, taskKnowledge } from "@zeroroot-ai/sdk";
+import { TRIGGER_STATUS } from "./gitlab.js";
+/**
+ * The always-on watch loop (zerocool-plugins#88).
+ *
+ * Dispatched into a `watch-<application>` mission, the agent does not run a
+ * task and exit. It polls the application's GitLab project every 30 seconds,
+ * and on each finished pipeline on `main` it has not seen it originates a Scan
+ * mission, waits for it, and goes back to polling. The loop ends when the
+ * mission is cancelled or the sandbox is torn down, not on its own.
+ *
+ * WHY THE AGENT POLLS RATHER THAN CI CALLING GIBSON. ADR-0063 lets a component
+ * originate a mission only from inside one it was dispatched to. A GitLab job
+ * is not inside a mission, so it cannot originate a Scan mission whatever
+ * credential it holds. The person originates the long-lived watch mission once;
+ * every Scan mission after that is originated by the agent from inside it,
+ * through `HarnessCallbackService.CreateMission` on the dispatch grant. Since
+ * gibson#1657 that RPC takes its parent, tenant and lineage from the resolved
+ * harness rather than the request, so the child is attributed to this mission
+ * and a caller outside a live mission is refused outright.
+ *
+ * ONLY THE LATEST PIPELINE IS EVER CONSIDERED. The loop asks GitLab for the
+ * most recent successful pipeline on the branch — never for a backlog. That is
+ * what makes the checkpoint safe to lose: an unreadable checkpoint costs one
+ * redundant Scan of the current head, never a stampede over a project's
+ * history. A checkpoint is an optimisation against duplicate work, not a
+ * correctness gate, and the loop is written so that is true.
+ *
+ * THE CHECKPOINT IS AN OBSERVATION, NOT A FILE. The sandbox is ephemeral, so
+ * anything written to its disk dies with it. The last pipeline seen goes into
+ * the World as a memory observation under the dispatch grant, which is the same
+ * write path every other thing the agent learns takes.
+ */
+/** The observation `kind` the checkpoint is written under. */
+export const CHECKPOINT_KIND = "watch-checkpoint";
+/** Default poll interval. The issue's cadence, and slow enough for GitLab. */
+export const DEFAULT_INTERVAL_MS = 30_000;
+/** Default ceiling on one Scan mission before the loop stops waiting on it. */
+export const DEFAULT_SCAN_TIMEOUT_MS = 30 * 60_000;
+/** The branch a watch follows unless the task says otherwise. */
+export const DEFAULT_REF = "main";
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Run the watch loop.
+ *
+ * Nothing in here throws for an expected failure. A GitLab outage, a refused
+ * Scan, a checkpoint that cannot be written — each is reported to the console
+ * and the loop keeps polling, because an always-on agent that exits on the
+ * first transient error is not always-on. The one thing it will not do is
+ * record a checkpoint for a Scan it failed to originate: that pipeline is
+ * retried on the next poll.
+ */
+export async function runWatchLoop(opts) {
+    const ref = opts.ref || DEFAULT_REF;
+    const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const sleep = opts.sleep ?? defaultSleep;
+    const emit = (e) => opts.onEvent?.(e);
+    const summary = { polls: 0, scans: 0, errors: 0, lastPipelineId: 0 };
+    // A checkpoint that cannot be read is not fatal: the loop then treats the
+    // current head as fresh and scans it once. See the module note.
+    try {
+        summary.lastPipelineId = await opts.checkpoints.last();
+    }
+    catch (e) {
+        summary.errors++;
+        emit({ type: "watch.error", application: opts.application, stage: "checkpoint", message: message(e) });
+    }
+    emit({
+        type: "watch.start",
+        application: opts.application,
+        ref,
+        lastPipelineId: summary.lastPipelineId,
+    });
+    while (!opts.signal?.aborted && (opts.maxPolls === undefined || summary.polls < opts.maxPolls)) {
+        summary.polls++;
+        let pipeline;
+        try {
+            pipeline = await opts.gitlab.latestFinishedPipeline(ref);
+        }
+        catch (e) {
+            summary.errors++;
+            emit({ type: "watch.error", application: opts.application, stage: "poll", message: message(e) });
+            await pause();
+            continue;
+        }
+        const fresh = !!pipeline && pipeline.id > summary.lastPipelineId;
+        emit({
+            type: "watch.poll",
+            application: opts.application,
+            ref,
+            pipelineId: pipeline?.id ?? 0,
+            status: pipeline?.status ?? TRIGGER_STATUS,
+            fresh,
+        });
+        if (!pipeline || !fresh) {
+            await pause();
+            continue;
+        }
+        // Originate, then record, then wait. Recording before the wait means a
+        // sandbox that dies mid-Scan does not re-originate the same Scan on
+        // restart; recording only after a successful launch means a refused launch
+        // is retried on the next poll instead of being silently skipped.
+        let missionId;
+        try {
+            missionId = await opts.scans.launch(pipeline);
+        }
+        catch (e) {
+            summary.errors++;
+            emit({ type: "watch.error", application: opts.application, stage: "scan", message: message(e) });
+            await pause();
+            continue;
+        }
+        summary.scans++;
+        emit({
+            type: "watch.scan",
+            application: opts.application,
+            pipelineId: pipeline.id,
+            commit: pipeline.sha,
+            missionId,
+        });
+        try {
+            await opts.checkpoints.record(pipeline);
+        }
+        catch (e) {
+            summary.errors++;
+            emit({ type: "watch.error", application: opts.application, stage: "record", message: message(e) });
+        }
+        summary.lastPipelineId = pipeline.id;
+        try {
+            const status = await opts.scans.wait(missionId);
+            emit({
+                type: "watch.scan.done",
+                application: opts.application,
+                pipelineId: pipeline.id,
+                missionId,
+                status,
+            });
+        }
+        catch (e) {
+            summary.errors++;
+            emit({ type: "watch.error", application: opts.application, stage: "scan", message: message(e) });
+        }
+        await pause();
+    }
+    return summary;
+    async function pause() {
+        if (opts.signal?.aborted)
+            return;
+        if (opts.maxPolls !== undefined && summary.polls >= opts.maxPolls)
+            return;
+        await sleep(interval);
+    }
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+// ---------------------------------------------------------------------------
+// The World-backed checkpoint
+// ---------------------------------------------------------------------------
+/**
+ * The checkpoint fact, in one parseable line.
+ *
+ * A memory is free text by design, so the loop writes a line it can read back
+ * without depending on which properties the projector chose to keep. The
+ * application is part of the line, so one tenant's several watches never read
+ * each other's checkpoints.
+ */
+export function checkpointText(application, p) {
+    return `${CHECKPOINT_KIND} application=${application} pipeline=${p.id} commit=${p.sha}`;
+}
+/** The checkpoint a line carries, or `undefined` when it is not one. */
+export function parseCheckpoint(text) {
+    if (!text.startsWith(CHECKPOINT_KIND))
+        return undefined;
+    const application = /\bapplication=(\S+)/.exec(text)?.[1] ?? "";
+    const pipelineId = Number(/\bpipeline=(\d+)/.exec(text)?.[1] ?? Number.NaN);
+    const commit = /\bcommit=(\S+)/.exec(text)?.[1] ?? "";
+    if (!application || !Number.isInteger(pipelineId) || pipelineId <= 0)
+        return undefined;
+    return { application, pipelineId, commit };
+}
+/**
+ * Checkpoints kept in the tenant World under the dispatch grant.
+ *
+ * The write is `Observe` with a memory shape, which the Taxonomy gate lands as
+ * an `Observation` node. The read is the graph query for those observations.
+ *
+ * DAEMON STATE, and why the loop is built to survive it: the SDK records that
+ * `QueryNodes` is declared but not wired at the daemon's registration site and
+ * answers `Unimplemented` on a live cluster (gibson#1186). Until that seam is
+ * wired, `last` reports 0 and the loop scans the current head once per restart
+ * rather than resuming — which is the same behaviour as a first run, and is why
+ * the loop never reads a backlog.
+ */
+export function worldCheckpoints(harness, application) {
+    const knowledge = taskKnowledge(harness);
+    return {
+        async last() {
+            const hits = await knowledge.query({
+                text: checkpointQueryText(application),
+                nodeTypes: ["Observation"],
+                topK: 50,
+            });
+            let max = 0;
+            for (const hit of hits) {
+                const parsed = parseCheckpoint(String(hit.content ?? ""));
+                if (parsed && parsed.application === application && parsed.pipelineId > max) {
+                    max = parsed.pipelineId;
+                }
+            }
+            return max;
+        },
+        record: (p) => remember(harness, {
+            text: checkpointText(application, p),
+            kind: CHECKPOINT_KIND,
+            tags: ["watch", `application:${application}`, `pipeline:${p.id}`],
+            sourceRef: p.webUrl,
+        }),
+    };
+}
+/** The recall text for an application's checkpoints. Exported so a test names it once. */
+export function checkpointQueryText(application) {
+    return `${CHECKPOINT_KIND} application=${application}`;
+}
+/**
+ * The Scan mission definition, as canonical proto JSON.
+ *
+ * A PLACEHOLDER WITH A REAL SHAPE. gibson#1660 owns the Scan mission proper —
+ * Trivy on the image, source analysis on the commit, and the runtime tools
+ * against the target, fanned out and joined. Until it lands, this originates
+ * the one node that exists today: zerocool's source-analysis task
+ * (zerocool-plugins#87) on the pipeline's commit. Everything the full fan-out
+ * needs is already carried in the node's task context, so gibson#1660 replaces
+ * the body of this one function and nothing else in the loop changes.
+ *
+ * The definition is built as protojson by hand rather than through the
+ * generated schema because the SDK's package exports only its index, and the
+ * mission schema is not re-exported from it.
+ */
+export function scanMissionDefinition(inputs) {
+    const { application, pipeline } = inputs;
+    const context = {
+        "zerocool.task": "source-analysis",
+        application,
+        "pipeline.id": String(pipeline.id),
+        "pipeline.url": pipeline.webUrl,
+        "repository.url": inputs.repositoryUrl,
+        "repository.ref": pipeline.ref,
+        "repository.commit": pipeline.sha,
+        ...(inputs.imageRef ? { "image.ref": inputs.imageRef } : {}),
+        ...(inputs.targetId ? { "target.id": inputs.targetId } : {}),
+    };
+    return {
+        name: scanMissionName(inputs),
+        description: `Scan ${application} at ${pipeline.sha.slice(0, 12)}, originated by the always-on agent ` +
+            `for pipeline ${pipeline.id}.`,
+        version: "1.0.0",
+        nodes: {
+            scan: {
+                id: "scan",
+                type: "NODE_TYPE_AGENT",
+                name: "scan",
+                description: "Source analysis of the commit the pipeline built.",
+                agentConfig: {
+                    agentName: "zerocool",
+                    task: {
+                        id: "scan",
+                        goal: `Scan the ${application} repository at commit ${pipeline.sha} and submit a Finding for ` +
+                            "every real weakness you can support with evidence.",
+                        context: typedContext(context),
+                    },
+                },
+            },
+        },
+        entryPoints: ["scan"],
+    };
+}
+/** The child mission's name, which is also how a person finds it in the dashboard. */
+export function scanMissionName(inputs) {
+    return `scan ${inputs.application} pipeline ${inputs.pipeline.id}`;
+}
+/**
+ * Render a string map as `map<string, gibson.common.v1.TypedValue>` in
+ * protojson. Every value the loop passes is a string, so every entry is a
+ * `stringValue`.
+ */
+export function typedContext(ctx) {
+    const out = {};
+    for (const [k, v] of Object.entries(ctx)) {
+        if (v !== "")
+            out[k] = { stringValue: v };
+    }
+    return out;
+}
+/**
+ * A {@link ScanLauncher} over the harness callbacks, on the dispatch grant.
+ *
+ * `CreateMission` here is the in-mission origination ADR-0063 permits: the
+ * daemon resolves the parent from this harness, so the Scan mission is a child
+ * of the watch mission and inherits its tenant. Nothing in the request names a
+ * parent, a tenant or an originator, so nothing here can widen them.
+ */
+export function harnessScanLauncher(harness, opts) {
+    const build = opts.definition ?? scanMissionDefinition;
+    const timeoutMs = BigInt(opts.scanTimeoutMs ?? DEFAULT_SCAN_TIMEOUT_MS);
+    return {
+        async launch(pipeline) {
+            const inputs = { ...opts.inputs, pipeline, targetId: opts.targetId };
+            const created = await harness.client.createMission({
+                context: harness.context,
+                missionDefinitionJson: new TextEncoder().encode(JSON.stringify(build(inputs))),
+                targetId: opts.targetId,
+                name: scanMissionName(inputs),
+            });
+            if (created.error) {
+                throw new Error(`CreateMission refused: ${created.error.message}`);
+            }
+            const missionId = created.mission?.id ?? "";
+            if (!missionId) {
+                throw new Error("CreateMission returned no mission id");
+            }
+            const run = await harness.client.runMission({
+                context: harness.context,
+                missionId,
+                wait: false,
+                timeoutMs: 0n,
+            });
+            if (run.error) {
+                throw new Error(`RunMission refused for ${missionId}: ${run.error.message}`);
+            }
+            return missionId;
+        },
+        async wait(missionId) {
+            const res = await harness.client.waitForMission({ context: harness.context, missionId, timeoutMs });
+            if (res.error) {
+                throw new Error(`WaitForMission failed for ${missionId}: ${res.error.message}`);
+            }
+            return String(res.result?.status ?? "");
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
   "license": "MIT",
   "repository": {