@wardby/cli 0.7.0 → 0.9.0

package/dist/core/run-steps/summarize.js

@@ -0,0 +1,304 @@
+/**
+ * Turns a tool call or a model message into the text a step's summary is cut from, and cuts it.
+ * Redaction runs on the control plane (stepSummarizer), on the raw step text, before anything is
+ * stored, for native and coding runs alike: whitespace is collapsed, then one pass of the shared
+ * redactor masks every form of every secret value together (secretForms) and any secret start the
+ * text ends in, then token shapes. The summary is cut only after redaction, so a cut never
+ * splits a secret and leaves half of it visible.
+ */
+import { CODING_PROTOCOL_VERSION } from "../../coding/protocol.js";
+import { REDACTED, redactSecrets } from "../../coding/redact.js";
+import { CLAUDE_MCP_TOOL_PREFIX, WORKER_MCP_SERVER_KEY } from "../../coding/mcp-token.js";
+import { MIN_REDACTABLE_SECRET_LENGTH, withEscapedForms } from "../secret-spans.js";
+import { MAX_STEP_TEXT_CHARS, SAID_SUMMARY_CHARS, STEP_TOOL_NAME, TOOL_SUMMARY_CHARS, } from "./types.js";
+/** Claude Code's one shell tool through the coding proxy (src/providers/coding-proxy/proxy.ts). */
+export const CLAUDE_COMMAND_TOOL = "mcp__wardby_tools__run_command";
+/** The namespace Codex gives the worker's MCP tools. */
+const CODEX_MCP_NAMESPACE = `mcp__${WORKER_MCP_SERVER_KEY}`;
+/** Arguments longer than this are not parsed whole; their leading field is read instead. */
+const MAX_PARSE_CHARS = 256 * 1024;
+export function bounded(text) {
+    return text.length > MAX_STEP_TEXT_CHARS
+        ? { text: text.slice(0, MAX_STEP_TEXT_CHARS), truncated: true }
+        : { text, truncated: false };
+}
+/**
+ * Codex's shell tools (unified exec and the older shell tools). Shown as Bash, the name Claude Code's
+ * shell tool has, so every coding agent's commands read and filter the same (CLAUDE.md, "Common
+ * interfaces for like systems"). Only the bare names: a namespaced tool is another server's.
+ */
+const CODEX_SHELL_TOOLS = new Set(["exec_command", "shell", "local_shell", "shell_command"]);
+/** A tool's name as a step shows it; anything that isn't a plain name becomes "tool". */
+export function displayToolName(name, namespace) {
+    let shown;
+    // Claude Code's one shell tool, and Codex's, show as the shell tool they stand for.
+    if (name === CLAUDE_COMMAND_TOOL || name === "run_command" || (!namespace && CODEX_SHELL_TOOLS.has(name))) {
+        shown = "Bash";
+    }
+    else if (name.startsWith(CLAUDE_MCP_TOOL_PREFIX))
+        shown = `mcp:${name.slice(CLAUDE_MCP_TOOL_PREFIX.length)}`;
+    else if (namespace === CODEX_MCP_NAMESPACE)
+        shown = `mcp:${name}`;
+    else if (namespace)
+        shown = `${namespace}.${name}`;
+    else
+        shown = name;
+    return STEP_TOOL_NAME.test(shown) ? shown : "tool";
+}
+const SHELLS = new Set(["bash", "sh", "zsh", "/bin/bash", "/bin/sh", "/bin/zsh", "/usr/bin/bash"]);
+const COMMAND_TOOLS = new Set(["run_command", "Bash", "shell", "exec_command", "local_shell", "shell_command"]);
+const PATH_KEYS = ["file_path", "path", "notebook_path"];
+const PATCH_FILE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+const CODE_MODE_CMD = /\bcmd\s*:\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\[[^\]]*\])/;
+const LEADING_FIELD = /"(?:command|cmd|file_path|path|pattern)"\s*:\s*"((?:[^"\\]|\\.)*)/;
+/** A command given as a string or an argv array; `bash -lc "<script>"` shows the script. */
+function commandText(value) {
+    if (typeof value === "string")
+        return value;
+    if (!Array.isArray(value) || !value.every((part) => typeof part === "string"))
+        return undefined;
+    const argv = value;
+    if (argv.length === 3 && SHELLS.has(argv[0]) && (argv[1] === "-lc" || argv[1] === "-c"))
+        return argv[2];
+    return argv.join(" ");
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A JavaScript string or array literal from Codex code mode, as a value; its inner text if it won't parse. */
+function parseLiteral(literal) {
+    if (literal.startsWith("'"))
+        return literal.slice(1, -1).replace(/\\'/g, "'");
+    return parseJson(literal) ?? literal.slice(1, -1);
+}
+/**
+ * A free-form tool input (a patch, Codex code-mode JavaScript, anything else). Otherwise its first
+ * non-blank line, `cut` when later lines are dropped: that line may be the start of a secret.
+ */
+function customInput(tool, input) {
+    if (tool === "apply_patch" || input.startsWith("*** Begin Patch")) {
+        const files = [...input.matchAll(PATCH_FILE)].map((match) => match[1].trim());
+        if (files.length > 0)
+            return { text: files.join(", "), cut: false };
+    }
+    const cmd = CODE_MODE_CMD.exec(input);
+    if (cmd) {
+        const command = commandText(parseLiteral(cmd[1]));
+        if (command !== undefined)
+            return { text: command, cut: false };
+    }
+    const lines = input.split("\n");
+    const first = lines.findIndex((line) => line.trim().length > 0);
+    if (first < 0)
+        return { text: "", cut: false };
+    return { text: lines[first].trim(), cut: lines.slice(first + 1).some((line) => line.trim().length > 0) };
+}
+/** The text a tool step's summary is cut from: the command, the path, the pattern, or the first argument. */
+export function toolInputText(tool, input) {
+    return toolInput(tool, input).text;
+}
+/** toolInputText, and whether part of a free-form input was dropped (customInput). */
+function toolInput(tool, input) {
+    if (typeof input === "string")
+        return customInput(tool, input);
+    if (tool === "apply_patch" && input && typeof input === "object" && !Array.isArray(input)) {
+        const patch = input.input;
+        if (typeof patch === "string")
+            return customInput(tool, patch);
+    }
+    return { text: plainInputText(tool, input), cut: false };
+}
+function plainInputText(tool, input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return "";
+    const args = input;
+    if (COMMAND_TOOLS.has(tool)) {
+        const command = commandText(args.command ?? args.cmd);
+        if (command !== undefined)
+            return command;
+    }
+    if (typeof args.pattern === "string") {
+        return typeof args.path === "string" ? `${args.pattern} in ${args.path}` : args.pattern;
+    }
+    for (const key of PATH_KEYS) {
+        const value = args[key];
+        if (typeof value === "string")
+            return value;
+    }
+    for (const value of Object.values(args)) {
+        if (typeof value === "string")
+            return value;
+        if (typeof value === "number" || typeof value === "boolean")
+            return String(value);
+    }
+    return "";
+}
+/**
+ * A string field of cut-off JSON (the first match of `field`, whose group 1 is the raw string
+ * body); `open` when the string never closed (it ran to the end of the input). Only an escape the
+ * cut left unfinished is dropped (an unpaired trailing backslash, or a partial `\\u` escape); a
+ * field that still won't decode is `undefined` text, never raw escapes.
+ */
+function stringField(json, field) {
+    const match = field.exec(json);
+    if (!match)
+        return undefined;
+    const open = json[match.index + match[0].length] !== '"';
+    const raw = match[1].replace(/(?<!\\)((?:\\\\)*)(?:\\u[0-9a-fA-F]{0,3}|\\)$/, "$1");
+    const decoded = parseJson(`"${raw}"`);
+    return { text: typeof decoded === "string" ? decoded : undefined, open };
+}
+/** The leading command, path or pattern field of cut-off tool arguments. */
+const leadingStringField = (json) => stringField(json, LEADING_FIELD);
+/** A tool step's text from its JSON arguments (complete or cut off). */
+export function toolStepText(tool, argsJson) {
+    const parsed = argsJson.length <= MAX_PARSE_CHARS ? parseJson(argsJson) : undefined;
+    if (parsed !== undefined) {
+        const input = toolInput(tool, parsed);
+        const out = bounded(input.text);
+        return { text: out.text, truncated: out.truncated || input.cut };
+    }
+    const leading = leadingStringField(argsJson.slice(0, MAX_STEP_TEXT_CHARS));
+    // A field that won't decode could show a secret in escaped form: nothing of it is shown.
+    if (leading && leading.text === undefined)
+        return { text: REDACTED, truncated: true };
+    const out = bounded(leading?.text ?? "");
+    return {
+        text: out.text,
+        // An unclosed string was cut off by the provider or by us: it may end in the start of a secret.
+        truncated: out.truncated || argsJson.length > MAX_STEP_TEXT_CHARS || !!leading?.open,
+    };
+}
+/** Claude Code's tool for a coding run's final answer (the coding proxy allows it by this name). */
+export const CLAUDE_RESULT_TOOL = "StructuredOutput";
+/** A final answer's step when it has no summary of its own. */
+export const FINISHED_STEP_TEXT = "Finished";
+const RESULT_VERSION_FIELD = new RegExp(`"schemaVersion"\\s*:\\s*${CODING_PROTOCOL_VERSION}(?![0-9.])`);
+const RESULT_SUMMARY_FIELD = /"summary"\s*:\s*"((?:[^"\\]|\\.)*)/;
+const FINISHED_BY_OUTCOME = new Map([
+    ["changes_ready", "Finished: changes ready"],
+    ["no_changes", "Finished: no changes"],
+    ["budget_exhausted", "Finished: budget exhausted"],
+]);
+const finishedLine = (outcome) => (typeof outcome === "string" ? FINISHED_BY_OUTCOME.get(outcome) : undefined) ?? FINISHED_STEP_TEXT;
+/**
+ * A coding run's final structured answer (`{"schemaVersion":1,...,"summary":"..."}`: Claude Code's
+ * StructuredOutput input, Codex's last message) as the text of one said step: the answer's own
+ * summary, else a fixed Finished line. `undefined` when the text is not such an answer. A cut answer
+ * gives its summary as far as it goes, marked truncated. The text is redacted later, with every
+ * other step's, by stepSummarizer.
+ */
+export function codingResultStepText(json) {
+    const text = json.trimStart();
+    if (!text.startsWith("{"))
+        return undefined;
+    const parsed = text.length <= MAX_PARSE_CHARS ? parseJson(text) : undefined;
+    if (parsed !== undefined) {
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const answer = parsed;
+        if (answer.schemaVersion !== CODING_PROTOCOL_VERSION)
+            return undefined;
+        if (typeof answer.summary === "string" && answer.summary.trim())
+            return bounded(answer.summary);
+        return { text: finishedLine(answer.outcome), truncated: false };
+    }
+    // Cut off (a block past 16 KiB, a reply that stopped early): an answer only if it says so.
+    const head = text.slice(0, MAX_STEP_TEXT_CHARS);
+    if (!RESULT_VERSION_FIELD.test(head))
+        return undefined;
+    const summary = stringField(head, RESULT_SUMMARY_FIELD);
+    if (!summary)
+        return { text: FINISHED_STEP_TEXT, truncated: false };
+    // A field that won't decode could show a secret in escaped form: nothing of it is shown.
+    if (summary.text === undefined)
+        return { text: REDACTED, truncated: true };
+    return { text: bounded(summary.text).text, truncated: true };
+}
+export const collapseWhitespace = (text) => text.replace(/\s+/g, " ").trim();
+/**
+ * Every form a secret value can take in a collapsed step text, longest first: each value as
+ * written and whitespace-collapsed (the model wrote it with other whitespace), each of those
+ * JSON-escaped (withEscapedForms: a value inside JSON text), and each of those collapsed.
+ */
+export function secretForms(secretValues) {
+    const forms = new Set();
+    for (const escaped of withEscapedForms(secretValues.flatMap((value) => [value, collapseWhitespace(value)]))) {
+        for (const form of [escaped, collapseWhitespace(escaped)])
+            if (form)
+                forms.add(form);
+    }
+    return [...forms].sort((a, b) => b.length - a.length);
+}
+/** KMP failure table of `pattern`: entry i is the longest proper border of pattern[0..i]. */
+function failureTable(pattern) {
+    const fail = new Int32Array(pattern.length);
+    for (let i = 1, k = 0; i < pattern.length; i++) {
+        while (k > 0 && pattern.charCodeAt(i) !== pattern.charCodeAt(k))
+            k = fail[k - 1];
+        if (pattern.charCodeAt(i) === pattern.charCodeAt(k))
+            k++;
+        fail[i] = k;
+    }
+    return fail;
+}
+/**
+ * The longest proper prefix of any form (at least the minimum length) that `text` ends with, or
+ * "" if none. Linear in the text per form (a KMP scan), whatever the forms look like. `tables`
+ * holds each form's failure table, built the first time a cut text needs it.
+ */
+export function secretTail(text, forms, tables) {
+    let best = 0;
+    for (const form of forms) {
+        // A form's proper prefixes; the text is never longer than the step text bound.
+        const pattern = form.length - 1 > MAX_STEP_TEXT_CHARS ? form.slice(0, MAX_STEP_TEXT_CHARS) : form.slice(0, -1);
+        if (pattern.length < MIN_REDACTABLE_SECRET_LENGTH || pattern.length <= best)
+            continue;
+        let fail = tables.get(form);
+        if (!fail)
+            tables.set(form, (fail = failureTable(pattern)));
+        let k = 0;
+        for (let i = Math.max(0, text.length - pattern.length); i < text.length; i++) {
+            if (k === pattern.length)
+                k = fail[k - 1];
+            while (k > 0 && text.charCodeAt(i) !== pattern.charCodeAt(k))
+                k = fail[k - 1];
+            if (text.charCodeAt(i) === pattern.charCodeAt(k))
+                k++;
+        }
+        if (k >= MIN_REDACTABLE_SECRET_LENGTH && k > best)
+            best = k;
+    }
+    return best > 0 ? text.slice(text.length - best) : "";
+}
+/**
+ * Summaries for one batch, against every secret value delivered to the run (the agent's and the
+ * run's own, such as its capability). The forms are built once per batch. Each step's text (at
+ * most 16 KiB) is whitespace collapsed, then redacted once with the shared redactor
+ * (redactSecrets: the union of every occurrence of every form, then token shapes), then cut to 100
+ * characters (tool) or 120 (said). Any text may end in the start of a secret (it was cut, or a
+ * stream stopped early without saying so), so on every step the longest such start (secretTail,
+ * on the collapsed text before any masking) is redacted in the same pass as one more exact value,
+ * so it merges with any whole secret it overlaps.
+ */
+export function stepSummarizer(secretValues) {
+    const forms = secretForms(secretValues);
+    const tables = new Map();
+    return (step) => {
+        const collapsed = collapseWhitespace(step.text.slice(0, MAX_STEP_TEXT_CHARS));
+        // Every step: a text can end mid-secret without being marked cut (a stream that stopped early).
+        const tail = secretTail(collapsed, forms, tables);
+        const text = redactSecrets(collapsed, tail ? [...forms, tail] : forms);
+        const limit = step.kind === "tool" ? TOOL_SUMMARY_CHARS : SAID_SUMMARY_CHARS;
+        return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+    };
+}
+/** One step's stored summary (stepSummarizer, for a single step). */
+export function stepSummary(step, secretValues) {
+    return stepSummarizer(secretValues)(step);
+}

package/dist/core/run-steps/sweep.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deletes run steps past RUN_STEP_RETENTION_DAYS (their expiresAt), in bounded batches. Runs on the
+ * scheduler leader's tick, at most every RUN_STEP_SWEEP_INTERVAL_MS, so one replica sweeps.
+ */
+import type { PrismaClient } from "#prisma";
+export declare const RUN_STEP_SWEEP_INTERVAL_MS: number;
+export declare function sweepExpiredRunSteps(db: Pick<PrismaClient, "$executeRaw">, now?: Date, opts?: {
+    batchSize?: number;
+    maxBatches?: number;
+}): Promise<number>;
+export declare class RunStepSweeper {
+    private readonly db;
+    private readonly options;
+    private lastAt;
+    constructor(db: Pick<PrismaClient, "$executeRaw">, options?: {
+        intervalMs?: number;
+        now?: () => Date;
+    });
+    /** Sweeps if the interval has passed since the last attempt. Never rejects. */
+    maybeSweep(): Promise<number>;
+}

package/dist/core/run-steps/sweep.js

@@ -0,0 +1,41 @@
+import { logger } from "../logger.js";
+const sweepLog = logger.child({ module: "run-steps" });
+export const RUN_STEP_SWEEP_INTERVAL_MS = 10 * 60_000;
+export async function sweepExpiredRunSteps(db, now = new Date(), opts = {}) {
+    const batchSize = opts.batchSize ?? 1_000;
+    const maxBatches = opts.maxBatches ?? 10;
+    let total = 0;
+    for (let batch = 0; batch < maxBatches; batch++) {
+        const deleted = await db.$executeRaw `
+      DELETE FROM "RunStep" WHERE "id" IN (
+        SELECT "id" FROM "RunStep" WHERE "expiresAt" < ${now} ORDER BY "expiresAt" LIMIT ${batchSize}
+      )`;
+        total += deleted;
+        if (deleted < batchSize)
+            break;
+    }
+    return total;
+}
+export class RunStepSweeper {
+    db;
+    options;
+    lastAt = Number.NEGATIVE_INFINITY;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.options = options;
+    }
+    /** Sweeps if the interval has passed since the last attempt. Never rejects. */
+    async maybeSweep() {
+        const now = (this.options.now ?? (() => new Date()))();
+        if (now.getTime() - this.lastAt < (this.options.intervalMs ?? RUN_STEP_SWEEP_INTERVAL_MS))
+            return 0;
+        this.lastAt = now.getTime();
+        try {
+            return await sweepExpiredRunSteps(this.db, now);
+        }
+        catch (err) {
+            sweepLog.warn({ event: "run_steps_sweep_failed", errorName: err instanceof Error ? err.name : typeof err }, "could not delete expired run steps; the next pass tries again");
+            return 0;
+        }
+    }
+}

package/dist/core/run-steps/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Run steps: one line per tool call (with its status once the result is back) or per model
+ * message. Every source (the native engine, the native gateways, the coding proxy) produces these
+ * shapes; only the control plane's RunStepWriter turns them into stored rows.
+ */
+/** A step as an extractor saw it: `text` is what the summary is cut from (at most MAX_STEP_TEXT_CHARS). */
+export type ExtractedStep = {
+    kind: "tool";
+    callId: string;
+    tool: string;
+    text: string;
+    truncated: boolean;
+    /** Detail level only: the tool's raw input (at most MAX_STEP_TEXT_CHARS). */
+    input?: string;
+    /** The input was cut (it may end in the start of a secret). */
+    inputTruncated?: boolean;
+} | {
+    kind: "said";
+    callId: string;
+    text: string;
+    truncated: boolean;
+};
+export type StepStatus = "ok" | "error" | `exit ${number}`;
+/** A tool call's status, matched to its step by callId. Never the result's content below the detail level. */
+export interface ExtractedResult {
+    callId: string;
+    status: StepStatus;
+    /** Detail level only: the end of the result's text output (at most MAX_RESULT_OUTPUT_CHARS). */
+    output?: string;
+    /** Text before `output` was dropped (it may start with the end of a secret). */
+    outputCut?: boolean;
+}
+export interface RunStepBatch {
+    steps: ExtractedStep[];
+    results: ExtractedResult[];
+}
+/**
+ * Where trusted code hands a run's steps: redacts by exact value, then writes. Never rejects.
+ * `extraSecretValues` are values the caller knows that the agent's own secrets do not cover (the
+ * native-sandbox gateway's run capability); they are redacted like the agent's.
+ */
+export interface RunStepSink {
+    record(runId: string, batch: RunStepBatch, extraSecretValues?: readonly string[]): Promise<void>;
+    /** Resolves when the writes queued so far settle (bounded; never rejects): before a shutdown disconnects. */
+    flush?(): Promise<void>;
+}
+/**
+ * The coding proxy's side: queues a batch for the control plane, for the run the capability belongs
+ * to (the listener refuses any other). The step text is sent unmasked: the control plane redacts it
+ * by exact value (stepSummarizer) before anything is stored. Synchronous; never throws.
+ */
+export interface RunStepSubmitter {
+    submit(capability: string, runId: string, batch: RunStepBatch): void;
+}
+/** The most text an extractor keeps for one step (a longer block is cut, not buffered). */
+export declare const MAX_STEP_TEXT_CHARS: number;
+/** The most steps one run records; later ones are counted in Run.stepsDropped. */
+export declare const MAX_RUN_STEPS = 2000;
+export declare const TOOL_SUMMARY_CHARS = 100;
+export declare const SAID_SUMMARY_CHARS = 120;
+/** The summary column's bound. */
+export declare const MAX_SUMMARY_CHARS = 300;
+/** The detail level's parts: a tool's input head, its output's tail, a model message's head. */
+export declare const DETAIL_INPUT_CHARS: number;
+export declare const DETAIL_OUTPUT_CHARS: number;
+export declare const DETAIL_SAID_CHARS: number;
+/** The detail column's bound. */
+export declare const MAX_STEP_DETAIL_CHARS: number;
+/** The most of a tool result's output a source sends (its end): more than DETAIL_OUTPUT_CHARS, so a secret across the cut is still whole. */
+export declare const MAX_RESULT_OUTPUT_CHARS: number;
+/** The end of `text`, at most `max` characters, and whether anything before it was dropped. */
+export declare function tailOf(text: string, max?: number): {
+    text: string;
+    cut: boolean;
+};
+/** Between a tool's input and its output in the detail text. */
+export declare const DETAIL_OUTPUT_HEADING = "\n\n--- output (end) ---\n";
+/** ok, error, or exit 1-999: fixed shapes only, so no free text can reach a status. */
+export declare const STEP_STATUS: RegExp;
+export declare const STEP_TOOL_NAME: RegExp;
+/** Printable ASCII, as the providers' and workers' ids are. */
+export declare const STEP_CALL_ID: RegExp;
+/** The control plane's run-steps listener route (WARDBY_RUN_STEPS_LISTEN). */
+export declare const RUN_STEPS_INGRESS_PATH = "/internal/run-steps";
+/** One POST's bounds; the forwarder splits larger batches. */
+export declare const MAX_STEPS_PER_POST = 64;
+export declare const MAX_RESULTS_PER_POST = 256;
+/** The most bytes one POST body may carry (the listener refuses a larger one); parts are split to fit. */
+export declare const MAX_RUN_STEPS_POST_BYTES: number;

package/dist/core/run-steps/types.js

@@ -0,0 +1,39 @@
+/**
+ * Run steps: one line per tool call (with its status once the result is back) or per model
+ * message. Every source (the native engine, the native gateways, the coding proxy) produces these
+ * shapes; only the control plane's RunStepWriter turns them into stored rows.
+ */
+/** The most text an extractor keeps for one step (a longer block is cut, not buffered). */
+export const MAX_STEP_TEXT_CHARS = 16 * 1024;
+/** The most steps one run records; later ones are counted in Run.stepsDropped. */
+export const MAX_RUN_STEPS = 2_000;
+export const TOOL_SUMMARY_CHARS = 100;
+export const SAID_SUMMARY_CHARS = 120;
+/** The summary column's bound. */
+export const MAX_SUMMARY_CHARS = 300;
+/** The detail level's parts: a tool's input head, its output's tail, a model message's head. */
+export const DETAIL_INPUT_CHARS = 4 * 1024;
+export const DETAIL_OUTPUT_CHARS = 2 * 1024;
+export const DETAIL_SAID_CHARS = 8 * 1024;
+/** The detail column's bound. */
+export const MAX_STEP_DETAIL_CHARS = 16 * 1024;
+/** The most of a tool result's output a source sends (its end): more than DETAIL_OUTPUT_CHARS, so a secret across the cut is still whole. */
+export const MAX_RESULT_OUTPUT_CHARS = 4 * 1024;
+/** The end of `text`, at most `max` characters, and whether anything before it was dropped. */
+export function tailOf(text, max = MAX_RESULT_OUTPUT_CHARS) {
+    return text.length > max ? { text: text.slice(text.length - max), cut: true } : { text, cut: false };
+}
+/** Between a tool's input and its output in the detail text. */
+export const DETAIL_OUTPUT_HEADING = "\n\n--- output (end) ---\n";
+/** ok, error, or exit 1-999: fixed shapes only, so no free text can reach a status. */
+export const STEP_STATUS = /^(?:ok|error|exit [1-9]\d{0,2})$/;
+export const STEP_TOOL_NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
+/** Printable ASCII, as the providers' and workers' ids are. */
+export const STEP_CALL_ID = /^[\x21-\x7e]{1,600}$/;
+/** The control plane's run-steps listener route (WARDBY_RUN_STEPS_LISTEN). */
+export const RUN_STEPS_INGRESS_PATH = "/internal/run-steps";
+/** One POST's bounds; the forwarder splits larger batches. */
+export const MAX_STEPS_PER_POST = 64;
+export const MAX_RESULTS_PER_POST = 256;
+/** The most bytes one POST body may carry (the listener refuses a larger one); parts are split to fit. */
+export const MAX_RUN_STEPS_POST_BYTES = 1 * 1024 * 1024;

package/dist/core/run-steps/wire.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The run-steps listener's request body: the run it is for, and the batch. Strict, bounded,
+ * fixed-shape statuses only (the forwarder's split keeps every POST within these bounds).
+ */
+import { z } from "zod";
+import { type RunStepBatch } from "./types.js";
+export declare const RunStepPostSchema: z.ZodObject<{
+    runId: z.ZodString;
+    steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"tool">;
+        callId: z.ZodString;
+        tool: z.ZodString;
+        text: z.ZodString;
+        truncated: z.ZodBoolean;
+        input: z.ZodOptional<z.ZodString>;
+        inputTruncated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"said">;
+        callId: z.ZodString;
+        text: z.ZodString;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>], "kind">>;
+    results: z.ZodArray<z.ZodObject<{
+        callId: z.ZodString;
+        status: z.ZodString;
+        output: z.ZodOptional<z.ZodString>;
+        outputCut: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export interface RunStepPost {
+    runId: string;
+    batch: RunStepBatch;
+}
+/** The POST's run and batch; undefined for any body outside the schema (never an error's text). */
+export declare function parseRunStepPost(value: unknown): RunStepPost | undefined;

package/dist/core/run-steps/wire.js

@@ -0,0 +1,47 @@
+/**
+ * The run-steps listener's request body: the run it is for, and the batch. Strict, bounded,
+ * fixed-shape statuses only (the forwarder's split keeps every POST within these bounds).
+ */
+import { z } from "zod";
+import { MAX_RESULT_OUTPUT_CHARS, MAX_RESULTS_PER_POST, MAX_STEP_TEXT_CHARS, MAX_STEPS_PER_POST, STEP_CALL_ID, STEP_STATUS, STEP_TOOL_NAME, } from "./types.js";
+const callId = z.string().regex(STEP_CALL_ID);
+const text = z.string().max(MAX_STEP_TEXT_CHARS);
+export const RunStepPostSchema = z
+    .object({
+    runId: z.string().min(1).max(200),
+    steps: z
+        .array(z.discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("tool"),
+            callId,
+            tool: z.string().regex(STEP_TOOL_NAME),
+            text,
+            truncated: z.boolean(),
+            input: text.optional(),
+            inputTruncated: z.boolean().optional(),
+        })
+            .strict(),
+        z.object({ kind: z.literal("said"), callId, text, truncated: z.boolean() }).strict(),
+    ]))
+        .max(MAX_STEPS_PER_POST),
+    results: z
+        .array(z
+        .object({
+        callId,
+        status: z.string().regex(STEP_STATUS),
+        output: z.string().max(MAX_RESULT_OUTPUT_CHARS).optional(),
+        outputCut: z.boolean().optional(),
+    })
+        .strict())
+        .max(MAX_RESULTS_PER_POST),
+})
+    .strict();
+/** The POST's run and batch; undefined for any body outside the schema (never an error's text). */
+export function parseRunStepPost(value) {
+    const parsed = RunStepPostSchema.safeParse(value);
+    if (!parsed.success)
+        return undefined;
+    const { runId, steps, results } = parsed.data;
+    return { runId, batch: { steps, results } };
+}

package/dist/core/run-steps/writer.d.ts

@@ -0,0 +1,49 @@
+import type { PrismaClient } from "#prisma";
+import { loadAgentSecretValues } from "../secret-guard.js";
+import { type RunStepsLevel } from "./config.js";
+import { type RunStepBatch, type RunStepSink } from "./types.js";
+/** How long flush() waits for queued writes at shutdown. */
+export declare const FLUSH_TIMEOUT_MS = 5000;
+export type RunStepWriterDb = Pick<PrismaClient, "run" | "runStep" | "$transaction">;
+export interface RunStepWriterDeps {
+    db: RunStepWriterDb;
+    /** Every secret value of the agent (already with JSON-escaped forms); rejects when any can't be read. */
+    secretValues: (agentId: string) => Promise<string[]>;
+    /** The process's ceiling: off stops this writer; otherwise used only for runs without a fixed level. */
+    level: RunStepsLevel;
+    retentionDays: number;
+    /** Tests only; MAX_RUN_STEPS otherwise. */
+    maxSteps?: number;
+    /** Tests only; the remembered-callId limits (per run, in all). */
+    droppedLimits?: {
+        perRun: number;
+        total: number;
+    };
+    now?: () => Date;
+    log?: {
+        warn(fields: Record<string, unknown>, message: string): void;
+    };
+}
+export declare class RunStepWriter implements RunStepSink {
+    private readonly deps;
+    private readonly queues;
+    /**
+     * Hashes of the callIds already counted in stepsDropped, so history resent past the cap is not
+     * counted again. Least recently used run first; bounded in total, whatever the ids' length.
+     */
+    private readonly droppedIds;
+    constructor(deps: RunStepWriterDeps);
+    record(runId: string, batch: RunStepBatch, extraSecretValues?: readonly string[]): Promise<void>;
+    /**
+     * Resolves when every write queued so far has settled, or after `timeoutMs`: called before the
+     * process disconnects from the database, so a run's last steps are not cut off. Never rejects.
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    private now;
+    private write;
+    private rememberDropped;
+    /** How many dropped callIds are remembered in all (tests). */
+    rememberedDroppedCount(): number;
+}
+/** The process's writer: settings from the environment (an invalid value throws, naming it). */
+export declare function buildRunStepWriter(db: PrismaClient, cipher: Parameters<typeof loadAgentSecretValues>[1], env?: NodeJS.ProcessEnv): RunStepWriter;