@wardby/cli 0.6.0 → 0.7.0

package/dist/core/schedule-start.d.ts

@@ -0,0 +1,12 @@
+import type { PrismaClient } from "#prisma";
+import { type ScheduleState } from "./cron.js";
+/**
+ * The `lastScheduledAt` to write with a schedule change: the database's
+ * clock when the change starts the schedule (see startsSchedule), nothing
+ * otherwise. The database's clock, not this process's, because the CLI and
+ * import can run on an operator's machine: a clock running ahead there would
+ * record a start after a window the scheduler has yet to fire, and skip it.
+ */
+export declare function scheduleStartFields(db: Pick<PrismaClient, "$queryRaw">, before: ScheduleState | null, after: ScheduleState): Promise<{
+    lastScheduledAt: Date;
+} | Record<string, never>>;

package/dist/core/schedule-start.js

@@ -0,0 +1,14 @@
+import { startsSchedule } from "./cron.js";
+/**
+ * The `lastScheduledAt` to write with a schedule change: the database's
+ * clock when the change starts the schedule (see startsSchedule), nothing
+ * otherwise. The database's clock, not this process's, because the CLI and
+ * import can run on an operator's machine: a clock running ahead there would
+ * record a start after a window the scheduler has yet to fire, and skip it.
+ */
+export async function scheduleStartFields(db, before, after) {
+    if (!startsSchedule(before, after))
+        return {};
+    const [{ now }] = await db.$queryRaw `SELECT now() AS now`;
+    return { lastScheduledAt: now };
+}

package/dist/core/secret-broker-config.d.ts

@@ -1,88 +1,24 @@
 import { z } from "zod";
 export declare const MIN_BROKERED_VALUE_LENGTH = 6;
 export declare const SecretBrokerConfigSchema: z.ZodObject<{
-    hosts: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">;
-    pathPrefixes: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    placement: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    hosts: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    pathPrefixes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"header">;
-        name: z.ZodEffects<z.ZodString, string, string>;
-        format: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
-    }, "strict", z.ZodTypeAny, {
-        name: string;
-        kind: "header";
-        format: string;
-    }, {
-        name: string;
-        kind: "header";
-        format: string;
-    }>, z.ZodObject<{
+        name: z.ZodString;
+        format: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"query">;
         name: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        name: string;
-        kind: "query";
-    }, {
-        name: string;
-        kind: "query";
-    }>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"body">;
         field: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        kind: "body";
-        field: string;
-    }, {
-        kind: "body";
-        field: string;
-    }>, z.ZodObject<{
+    }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"aws-sigv4">;
         region: z.ZodString;
         service: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        kind: "aws-sigv4";
-        service: string;
-        region: string;
-    }, {
-        kind: "aws-sigv4";
-        service: string;
-        region: string;
-    }>]>;
-}, "strict", z.ZodTypeAny, {
-    hosts: string[];
-    placement: {
-        name: string;
-        kind: "header";
-        format: string;
-    } | {
-        name: string;
-        kind: "query";
-    } | {
-        kind: "body";
-        field: string;
-    } | {
-        kind: "aws-sigv4";
-        service: string;
-        region: string;
-    };
-    pathPrefixes?: string[] | undefined;
-}, {
-    hosts: string[];
-    placement: {
-        name: string;
-        kind: "header";
-        format: string;
-    } | {
-        name: string;
-        kind: "query";
-    } | {
-        kind: "body";
-        field: string;
-    } | {
-        kind: "aws-sigv4";
-        service: string;
-        region: string;
-    };
-    pathPrefixes?: string[] | undefined;
-}>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
 export type SecretBrokerConfig = z.infer<typeof SecretBrokerConfigSchema>;
 export type SecretBrokerPlacement = SecretBrokerConfig["placement"];
 export declare function parseSecretBrokerConfig(input: unknown): SecretBrokerConfig;

package/dist/core/secret-guard.d.ts

@@ -0,0 +1,46 @@
+import type { PrismaClient } from "#prisma";
+import { buildSecretsAccessor } from "./secrets.js";
+export interface NamedSecretValues {
+    name: string;
+    values: string[];
+}
+type SecretGuardCipher = Parameters<typeof buildSecretsAccessor>[1];
+type SecretGuardDb = Parameters<typeof buildSecretsAccessor>[2] & Pick<PrismaClient, "agentSecret">;
+/** Every secret attached to the agent (readable and brokered), with every form to look for. Rejects if any read fails. */
+export declare function loadAgentSecretValues(db: SecretGuardDb, cipher: SecretGuardCipher, agentId: string): Promise<NamedSecretValues[]>;
+/** The sorted, unique names of the secrets whose value occurs anywhere in `value`. */
+export declare function secretNamesIn(value: unknown, named: readonly NamedSecretValues[]): string[];
+/** The agent-visible refusal: names the secrets, never a value. At most 1000 characters. */
+export declare function secretInValueMessage(names: readonly string[]): string;
+export declare const SECRET_CHECK_UNAVAILABLE_MESSAGE = "secret_check_unavailable: not stored. The agent's secrets could not be read to check this value; try again.";
+export declare const WITHHELD_TEXT_NOTICE = "[withheld: this text could not be checked for secret values]";
+export declare class SecretInValueError extends Error {
+    readonly code = "secret_in_value";
+    readonly secretNames: string[];
+    constructor(names: readonly string[]);
+}
+export declare class SecretCheckUnavailableError extends Error {
+    readonly code = "secret_check_unavailable";
+    constructor();
+}
+/** `text` with every value of every named secret masked. */
+export declare function maskNamedSecrets(text: string, named: readonly NamedSecretValues[]): string;
+export interface SecretWriteGuard {
+    assertNoSecrets(agentId: string, value: unknown): Promise<void>;
+}
+/** Refuses a value holding an attached secret's value; fails closed when the secrets cannot be read. */
+export declare function createSecretWriteGuard(source: {
+    load(agentId: string): Promise<NamedSecretValues[]>;
+}): SecretWriteGuard;
+export declare function createDbSecretWriteGuard(db: SecretGuardDb, cipher: SecretGuardCipher): SecretWriteGuard;
+/**
+ * Built-in tools whose arguments become text on a host, so their arguments are masked before
+ * the call. Review host: repo_publish_review (summary, body, inline comment bodies), repo_comment
+ * (body). Jira: jira_comment and jira_edit_own_comment (body), jira_update_fields (labels,
+ * components, priority, custom fields), jira_create_issue (summary, description, labels,
+ * components, custom fields, fingerprint), jira_set_property (a stored value), jira_transition
+ * (toStatus, which Jira may echo in an error). Read tools and jira_link_issues (a link type name
+ * checked against an allowlist) are left out.
+ */
+export declare const POSTING_TOOL_NAMES: ReadonlySet<string>;
+export {};

package/dist/core/secret-guard.js

@@ -0,0 +1,104 @@
+import { MIN_REDACTABLE_SECRET_LENGTH, redactExactSecretValues, withEscapedForms } from "./secret-spans.js";
+import { buildSecretsAccessor } from "./secrets.js";
+import { consoleRedactionValues } from "../sandbox/secret-broker.js";
+/** Every secret attached to the agent (readable and brokered), with every form to look for. Rejects if any read fails. */
+export async function loadAgentSecretValues(db, cipher, agentId) {
+    const rows = await db.agentSecret.findMany({ where: { agentId }, select: { boundName: true } });
+    if (rows.length === 0)
+        return [];
+    const accessor = buildSecretsAccessor(agentId, cipher, db);
+    return Promise.all(rows.map(async ({ boundName }) => {
+        const entry = await accessor.resolve(boundName);
+        return { name: boundName, values: entry ? withEscapedForms(consoleRedactionValues(entry)) : [] };
+    }));
+}
+function textOf(value) {
+    return typeof value === "string" ? value : (JSON.stringify(value) ?? "");
+}
+/** The sorted, unique names of the secrets whose value occurs anywhere in `value`. */
+export function secretNamesIn(value, named) {
+    const text = textOf(value);
+    const hits = new Set();
+    for (const { name, values } of named) {
+        if (values.some((v) => v.length >= MIN_REDACTABLE_SECRET_LENGTH && text.includes(v)))
+            hits.add(name);
+    }
+    return [...hits].sort();
+}
+const MAX_MESSAGE_LENGTH = 1000;
+function refusal(names, listed) {
+    const shown = names.slice(0, listed).map((n) => JSON.stringify(n));
+    const more = names.length - listed;
+    const list = shown.join(", ") + (more > 0 ? `, and ${more} more` : "");
+    const noun = names.length > 1 ? "secrets" : "secret";
+    const first = JSON.stringify(names[0]);
+    return `secret_in_value: not stored. The value contains the value of ${noun} ${list} attached to this agent, and secret values are never stored. Store the secret's name instead and read it when you need it: secrets.get(${first}), or fetch(url, { secrets: [${first}] }) if it is brokered.`;
+}
+/** The agent-visible refusal: names the secrets, never a value. At most 1000 characters. */
+export function secretInValueMessage(names) {
+    let listed = names.length;
+    while (listed > 1 && refusal(names, listed).length > MAX_MESSAGE_LENGTH)
+        listed--;
+    return refusal(names, listed);
+}
+export const SECRET_CHECK_UNAVAILABLE_MESSAGE = "secret_check_unavailable: not stored. The agent's secrets could not be read to check this value; try again.";
+export const WITHHELD_TEXT_NOTICE = "[withheld: this text could not be checked for secret values]";
+export class SecretInValueError extends Error {
+    code = "secret_in_value";
+    secretNames;
+    constructor(names) {
+        super(secretInValueMessage(names));
+        this.name = "SecretInValueError";
+        this.secretNames = [...names];
+    }
+}
+export class SecretCheckUnavailableError extends Error {
+    code = "secret_check_unavailable";
+    constructor() {
+        super(SECRET_CHECK_UNAVAILABLE_MESSAGE);
+        this.name = "SecretCheckUnavailableError";
+    }
+}
+/** `text` with every value of every named secret masked. */
+export function maskNamedSecrets(text, named) {
+    return redactExactSecretValues(text, named.flatMap((n) => n.values));
+}
+/** Refuses a value holding an attached secret's value; fails closed when the secrets cannot be read. */
+export function createSecretWriteGuard(source) {
+    return {
+        async assertNoSecrets(agentId, value) {
+            let named;
+            try {
+                named = await source.load(agentId);
+            }
+            catch {
+                throw new SecretCheckUnavailableError();
+            }
+            const names = secretNamesIn(value, named);
+            if (names.length > 0)
+                throw new SecretInValueError(names);
+        },
+    };
+}
+export function createDbSecretWriteGuard(db, cipher) {
+    return createSecretWriteGuard({ load: (id) => loadAgentSecretValues(db, cipher, id) });
+}
+/**
+ * Built-in tools whose arguments become text on a host, so their arguments are masked before
+ * the call. Review host: repo_publish_review (summary, body, inline comment bodies), repo_comment
+ * (body). Jira: jira_comment and jira_edit_own_comment (body), jira_update_fields (labels,
+ * components, priority, custom fields), jira_create_issue (summary, description, labels,
+ * components, custom fields, fingerprint), jira_set_property (a stored value), jira_transition
+ * (toStatus, which Jira may echo in an error). Read tools and jira_link_issues (a link type name
+ * checked against an allowlist) are left out.
+ */
+export const POSTING_TOOL_NAMES = new Set([
+    "repo_publish_review",
+    "repo_comment",
+    "jira_comment",
+    "jira_edit_own_comment",
+    "jira_update_fields",
+    "jira_create_issue",
+    "jira_set_property",
+    "jira_transition",
+]);

package/dist/core/secret-guarded-stores.d.ts

@@ -0,0 +1,12 @@
+import type { Datastore } from "../providers/datastore/types.js";
+import type { AgentMemoryStore } from "../providers/memory/types.js";
+import { type SecretWriteGuard } from "./secret-guard.js";
+/**
+ * Datastore that refuses a key or value holding an attached secret's value. Shared
+ * writes are checked against `opts.writerAgentId`; without it the writer is
+ * unknown, so the write is refused (fail closed). `writerAgentId` is stripped
+ * before the inner store sees it.
+ */
+export declare function guardDatastore(inner: Datastore, guard: SecretWriteGuard): Datastore;
+/** Agent memory that refuses a key or content holding an attached secret's value. */
+export declare function guardAgentMemory(inner: AgentMemoryStore, guard: SecretWriteGuard): AgentMemoryStore;

package/dist/core/secret-guarded-stores.js

@@ -0,0 +1,41 @@
+import { SecretCheckUnavailableError } from "./secret-guard.js";
+/**
+ * Datastore that refuses a key or value holding an attached secret's value. Shared
+ * writes are checked against `opts.writerAgentId`; without it the writer is
+ * unknown, so the write is refused (fail closed). `writerAgentId` is stripped
+ * before the inner store sees it.
+ */
+export function guardDatastore(inner, guard) {
+    return {
+        get: (agentId, key) => inner.get(agentId, key),
+        async set(agentId, key, value, opts) {
+            await guard.assertNoSecrets(agentId, [key, value]);
+            return inner.set(agentId, key, value, opts);
+        },
+        delete: (agentId, key) => inner.delete(agentId, key),
+        list: (agentId, prefix) => inner.list(agentId, prefix),
+        getShared: (datastoreId, key) => inner.getShared(datastoreId, key),
+        async setShared(datastoreId, key, value, opts) {
+            const { writerAgentId, ...rest } = opts ?? {};
+            if (!writerAgentId)
+                throw new SecretCheckUnavailableError();
+            await guard.assertNoSecrets(writerAgentId, [key, value]);
+            return inner.setShared(datastoreId, key, value, rest);
+        },
+        deleteShared: (datastoreId, key) => inner.deleteShared(datastoreId, key),
+        listShared: (datastoreId, prefix) => inner.listShared(datastoreId, prefix),
+    };
+}
+/** Agent memory that refuses a key or content holding an attached secret's value. */
+export function guardAgentMemory(inner, guard) {
+    return {
+        get: (agentId, key) => inner.get(agentId, key),
+        async set(agentId, key, content) {
+            await guard.assertNoSecrets(agentId, [key, content]);
+            return inner.set(agentId, key, content);
+        },
+        list: (agentId) => inner.list(agentId),
+        search: (agentId, query, limit) => inner.search(agentId, query, limit),
+        delete: (agentId, key) => inner.delete(agentId, key),
+    };
+}

package/dist/core/secret-spans.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one redactor for exact secret values: every site that masks values it knows (the sandbox
+ * console bridge, the native gateway's log, the native worker's stderr, a brokered response, a
+ * coding worker's debug trace, git output) goes through these functions. It masks the union of
+ * every occurrence of every value, overlapping occurrences included, so no character of any
+ * occurrence survives however occurrences overlap (a value such as `abcabcabc` in `abc` x 5).
+ *
+ * No imports: every worker image (native sandbox, coding driver, Claude coding worker) ships this
+ * file next to its callers.
+ */
+/** Below this length a "secret" is too likely to coincidentally match ordinary log text — not worth the false-positive risk of redacting it. */
+export declare const MIN_REDACTABLE_SECRET_LENGTH = 6;
+/** The marker that stands in for each masked span, unless a site passes its own. */
+export declare const REDACTED_MARKER = "[REDACTED]";
+export interface RedactOptions {
+    /** Replaces each merged span (default REDACTED_MARKER). */
+    marker?: string;
+    /** Values shorter than this are left alone (default MIN_REDACTABLE_SECRET_LENGTH; an empty value never matches). */
+    minLength?: number;
+}
+/**
+ * Each value plus its JSON-escaped forms, deduplicated: escaped once (`JSON.stringify(v).slice(1, -1)`)
+ * and twice. A value holding a quote, a backslash, a newline or a control character appears escaped
+ * once inside JSON text (a console line, a log line), and twice when that JSON text is itself
+ * logged as a string (`console.log(JSON.stringify({ key: value }))` through the console bridge, or
+ * a logger field that already holds JSON). The one expansion every redaction list goes through.
+ */
+export declare function withEscapedForms(values: Iterable<string>): string[];
+/**
+ * The merged, sorted [start, end) spans of `text` covered by any occurrence of any value, overlapping
+ * occurrences included (the search advances by one character, not by the value's length), so a
+ * self-overlapping value is covered wherever any occurrence of it lies. Values shorter than
+ * `minLength` are ignored. Overlapping or adjacent spans merge.
+ */
+export declare function secretSpans(text: string, values: Iterable<string>, minLength?: number): Array<[number, number]>;
+/** `spans` sorted and merged, overlapping or adjacent ones joined. */
+export declare function mergeSpans(spans: ReadonlyArray<readonly [number, number]>): Array<[number, number]>;
+/** `text` with each of the merged, sorted `spans` replaced by one `marker`. */
+export declare function maskSpans(text: string, spans: ReadonlyArray<readonly [number, number]>, marker?: string): string;
+/**
+ * `text` with the union of every occurrence of each value (secretSpans) replaced by the marker;
+ * values shorter than the minimum length are left alone.
+ */
+export declare function redactExactSecretValues(text: string, values: Iterable<string>, options?: RedactOptions): string;
+/**
+ * Whether `text` equals, contains, or is contained in any of `values`, under the same minimum
+ * length as redactExactSecretValues. For a short field that is sent whole or not at all (a native
+ * gateway error's cause code), where redacting part of it would still leave part of a value.
+ */
+export declare function overlapsSecretValue(text: string, values: Iterable<string>): boolean;

package/dist/core/secret-spans.js

@@ -0,0 +1,94 @@
+/**
+ * The one redactor for exact secret values: every site that masks values it knows (the sandbox
+ * console bridge, the native gateway's log, the native worker's stderr, a brokered response, a
+ * coding worker's debug trace, git output) goes through these functions. It masks the union of
+ * every occurrence of every value, overlapping occurrences included, so no character of any
+ * occurrence survives however occurrences overlap (a value such as `abcabcabc` in `abc` x 5).
+ *
+ * No imports: every worker image (native sandbox, coding driver, Claude coding worker) ships this
+ * file next to its callers.
+ */
+/** Below this length a "secret" is too likely to coincidentally match ordinary log text — not worth the false-positive risk of redacting it. */
+export const MIN_REDACTABLE_SECRET_LENGTH = 6;
+/** The marker that stands in for each masked span, unless a site passes its own. */
+export const REDACTED_MARKER = "[REDACTED]";
+/** `text` as it appears inside a JSON string literal (JSON.stringify without the quotes). */
+const jsonEscaped = (text) => JSON.stringify(text).slice(1, -1);
+/**
+ * Each value plus its JSON-escaped forms, deduplicated: escaped once (`JSON.stringify(v).slice(1, -1)`)
+ * and twice. A value holding a quote, a backslash, a newline or a control character appears escaped
+ * once inside JSON text (a console line, a log line), and twice when that JSON text is itself
+ * logged as a string (`console.log(JSON.stringify({ key: value }))` through the console bridge, or
+ * a logger field that already holds JSON). The one expansion every redaction list goes through.
+ */
+export function withEscapedForms(values) {
+    const out = new Set();
+    for (const value of values) {
+        const once = jsonEscaped(value);
+        out.add(value);
+        out.add(once);
+        out.add(jsonEscaped(once));
+    }
+    return [...out];
+}
+/**
+ * The merged, sorted [start, end) spans of `text` covered by any occurrence of any value, overlapping
+ * occurrences included (the search advances by one character, not by the value's length), so a
+ * self-overlapping value is covered wherever any occurrence of it lies. Values shorter than
+ * `minLength` are ignored. Overlapping or adjacent spans merge.
+ */
+export function secretSpans(text, values, minLength = MIN_REDACTABLE_SECRET_LENGTH) {
+    const spans = [];
+    const shortest = Math.max(1, minLength);
+    for (const value of new Set(values)) {
+        if (value.length < shortest)
+            continue;
+        for (let at = text.indexOf(value); at >= 0; at = text.indexOf(value, at + 1))
+            spans.push([at, at + value.length]);
+    }
+    return mergeSpans(spans);
+}
+/** `spans` sorted and merged, overlapping or adjacent ones joined. */
+export function mergeSpans(spans) {
+    const sorted = spans.filter(([start, end]) => end > start).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const merged = [];
+    for (const [start, end] of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            merged.push([start, end]);
+    }
+    return merged;
+}
+/** `text` with each of the merged, sorted `spans` replaced by one `marker`. */
+export function maskSpans(text, spans, marker = REDACTED_MARKER) {
+    let out = "";
+    let from = 0;
+    for (const [start, end] of spans) {
+        out += `${text.slice(from, start)}${marker}`;
+        from = end;
+    }
+    return out + text.slice(from);
+}
+/**
+ * `text` with the union of every occurrence of each value (secretSpans) replaced by the marker;
+ * values shorter than the minimum length are left alone.
+ */
+export function redactExactSecretValues(text, values, options = {}) {
+    return maskSpans(text, secretSpans(text, values, options.minLength), options.marker);
+}
+/**
+ * Whether `text` equals, contains, or is contained in any of `values`, under the same minimum
+ * length as redactExactSecretValues. For a short field that is sent whole or not at all (a native
+ * gateway error's cause code), where redacting part of it would still leave part of a value.
+ */
+export function overlapsSecretValue(text, values) {
+    for (const value of values) {
+        if (value.length < MIN_REDACTABLE_SECRET_LENGTH)
+            continue;
+        if (text.includes(value) || value.includes(text))
+            return true;
+    }
+    return false;
+}

package/dist/core/stop-run.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Stopping a run on request (the stop_run MCP tool). Every executor already owns the stop of the
+ * runs it executes (`Executor.stop`), and each makes the terminal write itself, conditional on the
+ * run still being pending or running, so the first terminal write wins and a finished run is never
+ * rewritten:
+ *
+ * - a native run in the control plane is recorded `cancelled` and stops at its next step boundary
+ *   (InProcessExecutor/DbosExecutor; a run that has not started never does);
+ * - a native run in the sandbox is recorded `cancelled`, its gateway session ends so the worker's
+ *   next call is refused, and after a short grace its worker is killed and removed
+ *   (NativeSandboxExecutor);
+ * - a coding run, queued for a slot or running, is recorded `cancelled` first (the fence that keeps
+ *   a finishing run from pushing or opening a pull request), then its proxy session is cancelled and
+ *   its job stopped and removed (ContainerExecutor).
+ *
+ * This module adds what a caller asks for on top: the run's in-flight delegated child runs are
+ * stopped too (depth-first, so nothing keeps spending for a parent that stopped), who stopped it
+ * and why is kept on the row (Run.stopRequestReason) and logged, and a run already finished is
+ * returned unchanged.
+ */
+import type { PrismaClient, RunStatus } from "#prisma";
+import type { Executor } from "../providers/executor/types.js";
+export type StopRunDb = Pick<PrismaClient, "run">;
+export interface StopRunOptions {
+    db: StopRunDb;
+    executor: Pick<Executor, "stop">;
+    runId: string;
+    /** Who asked (a principal id), recorded with the reason. */
+    stoppedBy: string;
+    /** The caller's own words, if any. */
+    reason?: string;
+}
+export interface StopRunResult {
+    runId: string;
+    /** The run's status before this call. */
+    previousStatus: RunStatus;
+    /** The run's status after it: `cancelled` once stopped, or whatever it had already ended as. */
+    status: RunStatus;
+    /** False when the run had already finished: nothing was changed. */
+    stopRequested: boolean;
+    /** In-flight delegated child runs this call stopped as well. */
+    stoppedChildRunIds: string[];
+}
+/** The text recorded on a stopped run: who stopped it and why. */
+export declare function stopRunReason(stoppedBy: string, reason?: string): string;
+export declare function stopRun(options: StopRunOptions): Promise<StopRunResult>;

package/dist/core/stop-run.js

@@ -0,0 +1,61 @@
+import { logger } from "./logger.js";
+const stopLog = logger.child({ module: "stop-run" });
+const DRIVABLE = ["pending", "running"];
+/** Delegation trees are shallow; this only bounds a malformed one. */
+const MAX_CHILD_DEPTH = 16;
+/** The text recorded on a stopped run: who stopped it and why. */
+export function stopRunReason(stoppedBy, reason) {
+    const why = reason?.trim();
+    return `Stopped by ${stoppedBy} with stop_run${why ? `: ${why}` : "."}`;
+}
+export async function stopRun(options) {
+    const { db, runId } = options;
+    const row = await db.run.findUnique({ where: { id: runId }, select: { status: true } });
+    if (!row)
+        throw new Error(`Unknown run "${runId}".`);
+    const previousStatus = row.status;
+    if (!DRIVABLE.includes(previousStatus)) {
+        return { runId, previousStatus, status: previousStatus, stopRequested: false, stoppedChildRunIds: [] };
+    }
+    const reason = stopRunReason(options.stoppedBy, options.reason);
+    stopLog.info({ runId, stoppedBy: options.stoppedBy, previousStatus, reason }, "stopping run");
+    const stoppedChildRunIds = [];
+    await stopOne(options, runId, reason, stoppedChildRunIds, 0, new Set());
+    const after = await db.run.findUniqueOrThrow({ where: { id: runId }, select: { status: true } });
+    return { runId, previousStatus, status: after.status, stopRequested: true, stoppedChildRunIds };
+}
+async function stopOne(options, runId, reason, stoppedChildRunIds, depth, visited) {
+    const { db, executor } = options;
+    visited.add(runId);
+    try {
+        await executor.stop(runId, reason);
+    }
+    catch (err) {
+        // Still stop the children and record the request: a failed stop is retried by calling again.
+        stopLog.warn({ err, runId }, "the executor failed to stop the run");
+    }
+    // A run that never started has nothing to interrupt: end it here if no executor did.
+    await db.run.updateMany({
+        where: { id: runId, status: "pending" },
+        data: { status: "cancelled", error: reason, finishedAt: new Date() },
+    });
+    // Kept for get_run; written only on a run this stop (or another) cancelled, never on one that
+    // finished some other way meanwhile. stopRequestedAt stays null: it is the native sandbox
+    // gateway's deferred-stop marker, which the scheduler leader drains.
+    await db.run.updateMany({
+        where: { id: runId, status: "cancelled", stopRequestReason: null },
+        data: { stopRequestReason: reason },
+    });
+    if (depth >= MAX_CHILD_DEPTH)
+        return;
+    const children = await db.run.findMany({
+        where: { parentRunId: runId, status: { in: [...DRIVABLE] } },
+        select: { id: true },
+    });
+    for (const child of children) {
+        if (visited.has(child.id))
+            continue;
+        stoppedChildRunIds.push(child.id);
+        await stopOne(options, child.id, `Parent run ${runId} was stopped. ${reason}`, stoppedChildRunIds, depth + 1, visited);
+    }
+}

package/dist/core/workflow-events.d.ts

@@ -1,7 +1,13 @@
-export declare const WORKFLOW_EVENT_KINDS: readonly ["issue_picked_up", "run_failed", "pr_opened", "review_posted", "review_fix", "pr_closed"];
+import type { PackageAuditDigest, PackageAuditMode } from "../coding/registry/audit-mode.js";
+import type { RegistryRefusalSummary } from "../coding/registry/report.js";
+export declare const WORKFLOW_EVENT_KINDS: readonly ["issue_picked_up", "run_failed", "run_blocked", "pr_opened", "review_posted", "review_fix", "pr_closed", "packages_audited"];
 export type WorkflowEventKind = (typeof WORKFLOW_EVENT_KINDS)[number];
 /** Template inputs per kind. Every string here may be shown in Slack (escaped). */
 export type WorkflowPayload = {
+    kind: "run_blocked";
+    agentName: string;
+    packageRefusals: RegistryRefusalSummary[];
+} | {
     kind: "issue_picked_up";
     agentName: string;
     trigger: string;
@@ -34,7 +40,11 @@ export type WorkflowPayload = {
     prUrl: string;
     merged: boolean;
     movedTo: string | null;
-};
+} | ({
+    kind: "packages_audited";
+    agentName: string;
+    mode: PackageAuditMode;
+} & PackageAuditDigest);
 /** What a thread's parent message shows about its subject. */
 export interface ThreadSubject {
     /** "PAY-241" or "org/repo#212" or "run abc123". */
@@ -44,11 +54,13 @@ export interface ThreadSubject {
 }
 export declare const dedupeKeys: {
     issuePickedUp: (runId: string) => string;
+    runBlocked: (runId: string) => string;
     runFailed: (runId: string) => string;
     prOpened: (codeProvider: string, repository: string, n: number) => string;
     reviewPosted: (runId: string) => string;
     reviewFix: (repository: string, n: number, round: number, state: "started" | "capped") => string;
     prClosed: (codeProvider: string, repository: string, n: number) => string;
+    packagesAudited: (runId: string) => string;
 };
 export declare const threadKeys: {
     issue: (provider: string, key: string) => string;

package/dist/core/workflow-events.js

@@ -2,18 +2,22 @@ import { logger } from "./logger.js";
 export const WORKFLOW_EVENT_KINDS = [
     "issue_picked_up",
     "run_failed",
+    "run_blocked",
     "pr_opened",
     "review_posted",
     "review_fix",
     "pr_closed",
+    "packages_audited",
 ];
 export const dedupeKeys = {
     issuePickedUp: (runId) => `issue_picked_up:${runId}`,
+    runBlocked: (runId) => `run_blocked:${runId}`,
     runFailed: (runId) => `run_failed:${runId}`,
     prOpened: (codeProvider, repository, n) => `pr_opened:${codeProvider}:${repository}#${n}`,
     reviewPosted: (runId) => `review_posted:${runId}`,
     reviewFix: (repository, n, round, state) => `review_fix:${repository}#${n}:${round}:${state}`,
     prClosed: (codeProvider, repository, n) => `pr_closed:${codeProvider}:${repository}#${n}`,
+    packagesAudited: (runId) => `packages_audited:${runId}`,
 };
 export const threadKeys = {
     issue: (provider, key) => `issue:${provider}:${key}`,