@wardby/cli 0.8.0 → 0.9.0

package/deploy/local/docker-compose.quickstart-coding.yml

@@ -20,6 +20,11 @@ services:
       # by default: the proxy then answers /mcp with 503 and coding agents simply
       # get no MCP tools.
       # WARDBY_MCP_GATEWAY_URL: http://wardby-native-gateway:8790
+      # Optional: the server's run-steps listener (WARDBY_RUN_STEPS_LISTEN), so coding runs record
+      # their steps (docs/debugging-agent-runs.md#run-steps), for example
+      # http://host.docker.internal:8792 with the server listening on 127.0.0.1:8792 (Docker Desktop).
+      # Unset by default: coding runs then record no steps.
+      WARDBY_RUN_STEPS_URL: ${WARDBY_RUN_STEPS_URL:-}
       # Run dependency cache. Off unless WARDBY_DEPENDENCY_CACHE=true is in the
       # quickstart env file (.wardby/.env) or the shell: then the proxy keeps
       # snapshots on the named volume below. The flag alone switches it; the

package/dist/claude-plugin/command.d.ts

@@ -1,7 +1,10 @@
 export declare const PLUGIN = "wardby-runs";
 export declare const DEFAULT_MARKETPLACE = "wardby/wardby";
 export declare const MCP_SERVER = "wardby";
-/** The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it changes a run. */
+/**
+ * The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it
+ * changes a run. get_run_steps backs Recent steps and Steps; against an older server the rule is harmless.
+ */
 export declare function paneTools(server: string): string[];
 export declare const PANE_TOOLS: string[];
 export declare const CLAUDE_PLUGIN_USAGE = "usage: wardby claude-plugin install [--marketplace <owner/repo|path>] [--server-url <url>]\n                                   [--allow-tools | --no-allow-tools] [--fullscreen] [--yes]\n       wardby claude-plugin uninstall\n       wardby claude-plugin status\n\nSet up the wardby-runs Claude Code plugin: a pane listing your wardby runs.\n\n  --server-name <name> The MCP server the pane uses, as /mcp lists it (default wardby); its\n                       allow rules follow the name\n  --marketplace <src>  Where to install it from (default wardby/wardby; an operator's own\n                       marketplace repository or a local folder works too)\n  --server-url <url>   Register the wardby MCP server at this URL first (for example\n                       https://wardby.example.com/mcp) when Claude Code has none named wardby\n  --allow-tools        Allow the pane's read-only wardby tools for auto mode without asking\n  --no-allow-tools     Leave permission rules alone\n  --fullscreen         Also switch Claude Code's terminal to its fullscreen view, where the pane\n                       is a side bar that takes clicks (applies to every session)\n  --yes, -y            Answer yes to every question";

package/dist/claude-plugin/command.js

@@ -19,9 +19,12 @@ import { parseArgs } from "node:util";
 export const PLUGIN = "wardby-runs";
 export const DEFAULT_MARKETPLACE = "wardby/wardby";
 export const MCP_SERVER = "wardby";
-/** The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it changes a run. */
+/**
+ * The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it
+ * changes a run. get_run_steps backs Recent steps and Steps; against an older server the rule is harmless.
+ */
 export function paneTools(server) {
-    return ["list_runs", "list_agents", "get_run", "get_run_transcript"].map((tool) => `mcp__${server}__${tool}`);
+    return ["list_runs", "list_agents", "get_run", "get_run_transcript", "get_run_steps"].map((tool) => `mcp__${server}__${tool}`);
 }
 export const PANE_TOOLS = paneTools(MCP_SERVER);
 /** How long one `claude` call may take: `claude mcp get` can check its server, which shouldn't stall doctor. */
@@ -289,7 +292,7 @@ export function pluginStatus(deps, serverName = MCP_SERVER) {
     deps.out(`${server ? "✓" : "✗"} ${serverName} MCP server ${server ? "configured" : "not configured"}`);
     deps.out(missing.length === 0
         ? `✓ the pane's tools are allowed in ${settingsPath}`
-        : `! not allowed in ${settingsPath} (auto mode refuses them): ${missing.join(", ")}`);
+        : `! not allowed in ${settingsPath} (auto mode refuses them): ${missing.join(", ")}. Re-run \`wardby claude-plugin install --allow-tools\` to add them.`);
     return plugin && server ? 0 : 1;
 }
 /**
@@ -334,7 +337,7 @@ export function claudePluginDoctorLines(deps, serverName = MCP_SERVER) {
     }
     lines.push(missing.length === 0
         ? "✓ the pane's tools are allowed for auto mode"
-        : `! not allowed for auto mode in ${settingsPath}: ${missing.join(", ")} (needed only in auto mode)`);
+        : `! not allowed for auto mode in ${settingsPath}: ${missing.join(", ")} (needed only in auto mode; re-run \`claude-plugin install --allow-tools\` to add them)`);
     return lines;
 }
 export async function claudePluginCommand(args, deps = claudePluginDeps()) {

package/dist/cli.js

@@ -53,6 +53,8 @@ import { scheduleStartFields } from "./core/schedule-start.js";
 import { assertAgentModelAvailable } from "./core/run-pricing.js";
 import { markRunFailedFromExecutorError } from "./core/dispatch.js";
 import { startScheduler } from "./core/scheduler.js";
+import { RunStepSweeper } from "./core/run-steps/sweep.js";
+import { buildRunStepWriter } from "./core/run-steps/writer.js";
 import { startReconciler } from "./core/reconciler.js";
 import { startNotifications } from "./core/notifications.js";
 import { NativeEngine } from "./core/engine-native.js";
@@ -118,6 +120,19 @@ function buildDatastore(cipher) {
 function buildMemory(cipher) {
     return guardAgentMemory(new PostgresAgentMemory(prisma), createDbSecretWriteGuard(prisma, cipher));
 }
+/** The run-steps writers this process built; each is flushed before the database disconnects. */
+const runStepWriters = [];
+/** The process's run-steps writer; an invalid WARDBY_RUN_STEPS or RUN_STEP_RETENTION_DAYS stops the command with the loader's message. */
+function buildRunSteps(cipher) {
+    try {
+        const writer = buildRunStepWriter(prisma, cipher);
+        runStepWriters.push(writer);
+        return writer;
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+}
 function buildSecrets() {
     const config = loadProviderConfig();
     try {
@@ -624,6 +639,7 @@ async function run(name) {
     const secrets = buildSecrets();
     const datastore = buildDatastore(secrets);
     const memory = buildMemory(secrets);
+    const runSteps = buildRunSteps(secrets);
     let run;
     // Ctrl-C (or a SIGTERM) records the run as cancelled rather than leaving a
     // `running` row behind.
@@ -637,6 +653,7 @@ async function run(name) {
             memory,
             reviewHosts: buildReviewHosts(process.env, prisma),
             issueTrackers: buildIssueTrackers(),
+            runSteps,
         }, prisma, (delta) => {
             process.stdout.write(delta);
         }, (created) => {
@@ -793,6 +810,7 @@ async function scheduler(args) {
     const secrets = buildSecrets();
     const datastore = buildDatastore(secrets);
     const memory = buildMemory(secrets);
+    const runSteps = buildRunSteps(secrets);
     const reviewHosts = buildReviewHosts(process.env, prisma);
     const issueTrackers = buildIssueTrackers();
     const chat = buildChatProviders();
@@ -810,6 +828,7 @@ async function scheduler(args) {
         reviewHosts,
         issueTrackers,
         repoAccess,
+        runSteps,
     };
     const nativeExecutor = buildExecutor(config, nativeProviders, prisma);
     const power = buildPower({ env: process.env, db: prisma });
@@ -845,6 +864,7 @@ async function scheduler(args) {
     });
     const notifications = await startNotifications({ db: prisma, chat });
     const selfDefects = { db: prisma, issueTrackers };
+    const runStepSweeper = new RunStepSweeper(prisma);
     const sched = startScheduler({
         executor,
         db: prisma,
@@ -860,6 +880,7 @@ async function scheduler(args) {
                 onStartFailed: (runId, err) => markRunFailedFromExecutorError(prisma, runId, err, selfDefects),
             });
             await power.sleepIfIdle().catch((err) => cliLog.warn({ err }, "power_sleep_failed"));
+            await runStepSweeper.maybeSweep();
         },
     });
     console.log(`wardby scheduler started (scope "${scope}"). Press Ctrl+C to stop.`);
@@ -916,6 +937,7 @@ async function nativeGateway() {
         issueTrackers: buildIssueTrackers(),
         repoAccess: createRepoAccessGate({ db: prisma, hosts: reviewHosts }),
         executor: new DeferredExecutor(prisma),
+        runSteps: buildRunSteps(secrets),
     };
     const server = await startGatewayServer(listen, {
         db: prisma,
@@ -1081,6 +1103,8 @@ async function main() {
         }
     }
     finally {
+        // A run's last steps are written before the connection goes (bounded: flush never rejects).
+        await Promise.all(runStepWriters.map((writer) => writer.flush()));
         await prisma.$disconnect();
     }
 }

package/dist/coding/transcript/recorder.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
 import { BlobStoreError } from "../../providers/storage/types.js";
+import { loadRetentionDays } from "../../core/retention-days.js";
 import { withEscapedForms } from "../../core/secret-spans.js";
 import { REDACTED, redactSecrets } from "../redact.js";
 import { sanitizeClaudeTranscript } from "./claude-code.js";
@@ -26,14 +27,7 @@ export function loadTranscriptMaxBytes(env = process.env) {
     return bytes;
 }
 export function loadTranscriptRetentionDays(env = process.env) {
-    const raw = env.RUN_TRANSCRIPT_RETENTION_DAYS?.trim();
-    if (!raw)
-        return 30;
-    const days = Number(raw);
-    if (!Number.isInteger(days) || days < 1 || days > 3650) {
-        throw new Error("RUN_TRANSCRIPT_RETENTION_DAYS must be a whole number of days from 1 to 3650.");
-    }
-    return days;
+    return loadRetentionDays(env, "RUN_TRANSCRIPT_RETENTION_DAYS", 30);
 }
 /**
  * Stores a coding run's session transcript for local resume. The worker's file is not trusted: it is

package/dist/core/dispatch.js

@@ -16,6 +16,7 @@ import { logger } from "./logger.js";
 import { CodingModelProviderMismatchError, resolveCodingEntry } from "./run-pricing.js";
 import { resolveCodingRepository, } from "./coding-repository.js";
 import { CONTENDED_TX_MAX_WAIT_MS } from "./timing.js";
+import { dispatchRunStepsLevel } from "./run-steps/config.js";
 import { fileSelfDefectForRun } from "./self-defects.js";
 const dispatchLog = logger.child({ module: "dispatch" });
 /** SQLSTATEs worth retrying the persist transaction for: serialization failure, deadlock. */
@@ -539,6 +540,8 @@ export async function dispatchRun(options) {
                 executionManaged: true,
                 // Fixed for the run's life: the executor routes on this, never on the agent's current setting.
                 nativeExecutionMode: agent.kind === "native" ? agent.nativeExecutionMode : null,
+                // Fixed for the run's life, like nativeExecutionMode: a later runSteps change reaches only later runs.
+                runStepsLevel: dispatchRunStepsLevel(agent),
                 parentRunId: options.parentRunId,
                 parentCallId: options.parentCallId,
                 grantedParentMemoryKeys: options.grantedParentMemoryKeys ?? [],

package/dist/core/engine-native.d.ts

@@ -16,6 +16,8 @@ export declare class NativeEngine implements Engine {
      * without it — either way the terminal status is `budget_exhausted`.
      */
     private windDown;
+    /** Builds an event (only when ctx.onTurn is set) and hands it to ctx.onTurn. A failing hook is logged by name and never affects the run. */
+    private emitTurn;
     private finish;
     /**
      * One turn's tool calls, results in call order. The calls are split into

package/dist/core/engine-native.js

@@ -116,8 +116,10 @@ export class NativeEngine {
             if (turn.toolCalls.length > 0)
                 assistantMessage.toolCalls = turn.toolCalls;
             messages.push(assistantMessage);
+            this.emitTurn(ctx, () => ({ kind: "turn", turn: turns, text: turn.text, toolCalls: turn.toolCalls }));
             if (turn.toolCalls.length > 0) {
                 const results = await this.runToolCalls(ctx, step, turns, turn.toolCalls);
+                this.emitTurn(ctx, () => ({ kind: "results", turn: turns, toolCalls: turn.toolCalls, results }));
                 for (const [index, toolCall] of turn.toolCalls.entries()) {
                     messages.push({
                         role: "tool",
@@ -159,6 +161,17 @@ export class NativeEngine {
         }
         return this.finish("budget_exhausted", turn.text || lastText, turns + 1, finalUsage);
     }
+    /** Builds an event (only when ctx.onTurn is set) and hands it to ctx.onTurn. A failing hook is logged by name and never affects the run. */
+    emitTurn(ctx, build) {
+        if (!ctx.onTurn)
+            return;
+        try {
+            ctx.onTurn(build());
+        }
+        catch (err) {
+            engineLog.warn({ event: "run_steps_hook_failed", errorName: err instanceof Error ? err.name : typeof err }, "run steps hook failed; the run goes on");
+        }
+    }
     finish(status, finalText, turns, usage, error) {
         return { status, finalText, turns, usage, ...(error ? { error } : {}) };
     }

package/dist/core/error-code.js

@@ -74,6 +74,7 @@ export const CHILD_RUN_FAILURE_CODES = new Set([
     "coding_failure_cancelled",
     "coding_failure_executor",
     "coding_failure_mcp_pins_unavailable",
+    "coding_failure_mcp_gateway_unavailable",
     "coding_provider_quota",
     "coding_provider_rate_limited",
     "coding_provider_unavailable",

package/dist/core/listen-address.d.ts

@@ -0,0 +1,10 @@
+/** A listener's bind address, from a `host:port` or `:port` environment variable. */
+export interface ListenAddress {
+    host: string;
+    port: number;
+}
+/**
+ * Parses a listen variable (`host:port`, or `:port` for every interface); unset or blank =
+ * undefined. Anything else throws, naming the variable.
+ */
+export declare function parseListenAddress(variable: string, value: string | undefined): ListenAddress | undefined;

package/dist/core/listen-address.js

@@ -0,0 +1,14 @@
+/**
+ * Parses a listen variable (`host:port`, or `:port` for every interface); unset or blank =
+ * undefined. Anything else throws, naming the variable.
+ */
+export function parseListenAddress(variable, value) {
+    if (!value?.trim())
+        return undefined;
+    const match = /^(.*):(\d{1,5})$/.exec(value.trim());
+    const port = match ? Number(match[2]) : NaN;
+    if (!match || !Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error(`${variable} must be host:port or :port (got "${value}").`);
+    }
+    return { host: match[1] || "0.0.0.0", port };
+}

package/dist/core/power-idle.d.ts

@@ -2,7 +2,9 @@
  * Low-power mode's idle rules: whether the coding proxy or native gateway has
  * had work since `since`. A target is busy while any of its runs is pending
  * (queued included) or running, or finished at or after `since`; the gateway
- * is also busy while any gateway session is active. powerBlockers lists the
+ * is also busy while any gateway session is active. The gateway's runs are
+ * sandboxed native runs plus coding runs with MCP tools: a coding run's MCP
+ * calls go coding proxy -> gateway, so it needs both. powerBlockers lists the
  * run ids that keep a target busy right now (recent finishes do not count).
  */
 import type { PrismaClient } from "#prisma";
@@ -10,5 +12,9 @@ import type { PowerTarget } from "./power.js";
 export declare function proxyBusy(db: PrismaClient, since: Date): Promise<boolean>;
 export declare function gatewayBusy(db: PrismaClient, since: Date): Promise<boolean>;
 export declare function powerBusy(db: PrismaClient): (target: PowerTarget, since: Date) => Promise<boolean>;
-/** Run ids keeping `target` busy right now: active or queued runs (plus active gateway sessions for the gateway). */
+/**
+ * Run ids keeping `target` busy right now: active or queued runs (plus, for the gateway, active
+ * gateway sessions and active or queued coding runs with MCP tools). "Active" for a coding run is
+ * the proxy's rule: its run is pending or running.
+ */
 export declare function powerBlockers(db: PrismaClient, target: PowerTarget): Promise<string[]>;

package/dist/core/power-idle.js

@@ -1,4 +1,6 @@
 const ACTIVE = { in: ["pending", "running"] };
+/** A coding run whose proxy session holds an MCP token: it has MCP tools, served through the gateway. */
+const WITH_MCP_TOOLS = { proxySession: { is: { mcpTokenHash: { not: null } } } };
 export async function proxyBusy(db, since) {
     const n = await db.codingRun.count({
         where: { run: { OR: [{ status: ACTIVE }, { finishedAt: { gte: since } }] } },
@@ -11,20 +13,32 @@ export async function gatewayBusy(db, since) {
     });
     if (runs > 0)
         return true;
+    const mcpCodingRuns = await db.codingRun.count({
+        where: { ...WITH_MCP_TOOLS, run: { OR: [{ status: ACTIVE }, { finishedAt: { gte: since } }] } },
+    });
+    if (mcpCodingRuns > 0)
+        return true;
     return (await db.nativeGatewaySession.count({ where: { status: "active" } })) > 0;
 }
 export function powerBusy(db) {
     return (target, since) => (target === "proxy" ? proxyBusy(db, since) : gatewayBusy(db, since));
 }
-/** Run ids keeping `target` busy right now: active or queued runs (plus active gateway sessions for the gateway). */
+/**
+ * Run ids keeping `target` busy right now: active or queued runs (plus, for the gateway, active
+ * gateway sessions and active or queued coding runs with MCP tools). "Active" for a coding run is
+ * the proxy's rule: its run is pending or running.
+ */
 export async function powerBlockers(db, target) {
     if (target === "proxy") {
         const rows = await db.codingRun.findMany({ where: { run: { status: ACTIVE } }, select: { runId: true } });
         return [...new Set(rows.map((r) => r.runId))].sort();
     }
-    const [runs, sessions] = await Promise.all([
+    const [runs, sessions, mcpCodingRuns] = await Promise.all([
         db.run.findMany({ where: { nativeExecutionMode: "sandbox", status: ACTIVE }, select: { id: true } }),
         db.nativeGatewaySession.findMany({ where: { status: "active" }, select: { runId: true } }),
+        db.codingRun.findMany({ where: { ...WITH_MCP_TOOLS, run: { status: ACTIVE } }, select: { runId: true } }),
     ]);
-    return [...new Set([...runs.map((r) => r.id), ...sessions.map((s) => s.runId)])].sort();
+    return [
+        ...new Set([...runs.map((r) => r.id), ...sessions.map((s) => s.runId), ...mcpCodingRuns.map((r) => r.runId)]),
+    ].sort();
 }

package/dist/core/power.d.ts

@@ -4,6 +4,11 @@ export type PowerTarget = "proxy" | "gateway";
 export declare const LOW_POWER_WAKE_TIMEOUT = "low_power_wake_timeout";
 export declare const LOW_POWER_SCALE_FORBIDDEN = "low_power_scale_forbidden";
 export declare const LOW_POWER_DISABLED = "low_power_disabled";
+/**
+ * A coding run with MCP tools could not wake the native gateway that serves them: the run fails
+ * before its worker launches (category mcp_gateway_unavailable).
+ */
+export declare const CODING_MCP_GATEWAY_UNAVAILABLE = "coding_mcp_gateway_unavailable";
 /** ISO-8601 time the control plane last scaled the Deployment up from zero. */
 export declare const POWER_WOKE_AT = "wardby.io/power-woke-at";
 /**

package/dist/core/power.js

@@ -4,6 +4,11 @@ const powerLog = logger.child({ module: "power" });
 export const LOW_POWER_WAKE_TIMEOUT = "low_power_wake_timeout";
 export const LOW_POWER_SCALE_FORBIDDEN = "low_power_scale_forbidden";
 export const LOW_POWER_DISABLED = "low_power_disabled";
+/**
+ * A coding run with MCP tools could not wake the native gateway that serves them: the run fails
+ * before its worker launches (category mcp_gateway_unavailable).
+ */
+export const CODING_MCP_GATEWAY_UNAVAILABLE = "coding_mcp_gateway_unavailable";
 /** ISO-8601 time the control plane last scaled the Deployment up from zero. */
 export const POWER_WOKE_AT = "wardby.io/power-woke-at";
 /**

package/dist/core/retention-days.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reads a retention setting in whole days (1 to 3650) from the environment. An unset or blank value
+ * gives `defaultDays`; anything else out of range stops start-up, naming the variable.
+ */
+export declare function loadRetentionDays(env: NodeJS.ProcessEnv, name: string, defaultDays: number): number;

package/dist/core/retention-days.js

@@ -0,0 +1,14 @@
+/**
+ * Reads a retention setting in whole days (1 to 3650) from the environment. An unset or blank value
+ * gives `defaultDays`; anything else out of range stops start-up, naming the variable.
+ */
+export function loadRetentionDays(env, name, defaultDays) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return defaultDays;
+    const days = Number(raw);
+    if (!Number.isInteger(days) || days < 1 || days > 3650) {
+        throw new Error(`${name} must be a whole number of days from 1 to 3650.`);
+    }
+    return days;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Run steps settings, read at start-up by every process that records or serves steps (the server,
+ * `wardby scheduler`, the native gateway). An invalid value stops start-up, naming the variable.
+ */
+export type RunStepsLevel = "off" | "summary" | "detail";
+export declare const RUN_STEPS_LEVELS: readonly RunStepsLevel[];
+/** WARDBY_RUN_STEPS: the instance's ceiling. Default summary. */
+export declare function loadRunStepsLevel(env?: NodeJS.ProcessEnv): RunStepsLevel;
+/** A run's level: min(the instance's ceiling, the agent's setting); an unset agent is at summary. */
+export declare function runStepsLevelFor(ceiling: RunStepsLevel, agentSetting: RunStepsLevel | null | undefined): RunStepsLevel;
+/**
+ * The level a run records: the one fixed at dispatch, never above this process's current ceiling
+ * (lowering the ceiling stops detail for in-flight runs too). A run from before the field is at
+ * most summary.
+ */
+export declare function recordedRunStepsLevel(runLevel: RunStepsLevel | null | undefined, ceiling: RunStepsLevel): RunStepsLevel;
+/** The level to fix on a run being created for `agent` (dispatch, createRun, delegation). */
+export declare function dispatchRunStepsLevel(agent: {
+    runSteps: RunStepsLevel | null;
+}, env?: NodeJS.ProcessEnv): RunStepsLevel;
+/** update_agent / get_agent: the agent asks for more than the instance records (not a refusal). */
+export declare function runStepsAboveCeilingWarning(agentSetting: RunStepsLevel | null | undefined, ceiling: RunStepsLevel): string | undefined;
+export declare const DEFAULT_RUN_STEP_RETENTION_DAYS = 30;
+/** RUN_STEP_RETENTION_DAYS: days a step is kept after it is written. Applies to steps written after a change. */
+export declare function loadRunStepRetentionDays(env?: NodeJS.ProcessEnv): number;

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

@@ -0,0 +1,40 @@
+import { loadRetentionDays } from "../retention-days.js";
+export const RUN_STEPS_LEVELS = ["off", "summary", "detail"];
+const RANK = { off: 0, summary: 1, detail: 2 };
+/** WARDBY_RUN_STEPS: the instance's ceiling. Default summary. */
+export function loadRunStepsLevel(env = process.env) {
+    const raw = env.WARDBY_RUN_STEPS?.trim();
+    if (!raw)
+        return "summary";
+    if (!RUN_STEPS_LEVELS.includes(raw))
+        throw new Error("WARDBY_RUN_STEPS must be off, summary or detail.");
+    return raw;
+}
+/** A run's level: min(the instance's ceiling, the agent's setting); an unset agent is at summary. */
+export function runStepsLevelFor(ceiling, agentSetting) {
+    const asked = agentSetting ?? "summary";
+    return RANK[asked] <= RANK[ceiling] ? asked : ceiling;
+}
+/**
+ * The level a run records: the one fixed at dispatch, never above this process's current ceiling
+ * (lowering the ceiling stops detail for in-flight runs too). A run from before the field is at
+ * most summary.
+ */
+export function recordedRunStepsLevel(runLevel, ceiling) {
+    return runStepsLevelFor(ceiling, runLevel);
+}
+/** The level to fix on a run being created for `agent` (dispatch, createRun, delegation). */
+export function dispatchRunStepsLevel(agent, env = process.env) {
+    return runStepsLevelFor(loadRunStepsLevel(env), agent.runSteps);
+}
+/** update_agent / get_agent: the agent asks for more than the instance records (not a refusal). */
+export function runStepsAboveCeilingWarning(agentSetting, ceiling) {
+    if (!agentSetting || RANK[agentSetting] <= RANK[ceiling])
+        return undefined;
+    return `runSteps is ${agentSetting} but this instance allows up to ${ceiling} (WARDBY_RUN_STEPS), so its runs record ${ceiling}. See the run-steps help article.`;
+}
+export const DEFAULT_RUN_STEP_RETENTION_DAYS = 30;
+/** RUN_STEP_RETENTION_DAYS: days a step is kept after it is written. Applies to steps written after a change. */
+export function loadRunStepRetentionDays(env = process.env) {
+    return loadRetentionDays(env, "RUN_STEP_RETENTION_DAYS", DEFAULT_RUN_STEP_RETENTION_DAYS);
+}

package/dist/core/run-steps/control-chars.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Step text as plain text: tool output and input are untrusted (repository content, command
+ * output), and a reader may show them in a terminal. Whole ANSI escape sequences are removed (CSI
+ * such as colour codes; OSC, DCS, SOS, PM and APC strings ended by BEL or ST, such as OSC 8 links
+ * and OSC 52 clipboard writes), then every other C0 and C1 control character except `\n` and `\t`.
+ * Only a well-formed sequence is removed whole: a bare or malformed ESC (or C1 byte) is removed
+ * alone and never takes a printable character after it (`ESC Z` leaves `Z`), so it cannot eat
+ * the first character of a secret value. A well-formed CSI can still end in a letter (`ESC [ Z`),
+ * which is why the writer masks secret values on the raw text before this runs.
+ * `\r\n` becomes `\n`; a lone `\r` is dropped. Removing characters can only join text, never split
+ * it, so a secret split by colour codes is whole again for redaction, which runs after this.
+ *
+ * No imports: dependency-free, so any reader of step text can share it.
+ */
+/** `text` without terminal control sequences or control characters other than `\n` and `\t`. */
+export declare function stripControlSequences(text: string): string;

package/dist/core/run-steps/control-chars.js

@@ -0,0 +1,26 @@
+/**
+ * Step text as plain text: tool output and input are untrusted (repository content, command
+ * output), and a reader may show them in a terminal. Whole ANSI escape sequences are removed (CSI
+ * such as colour codes; OSC, DCS, SOS, PM and APC strings ended by BEL or ST, such as OSC 8 links
+ * and OSC 52 clipboard writes), then every other C0 and C1 control character except `\n` and `\t`.
+ * Only a well-formed sequence is removed whole: a bare or malformed ESC (or C1 byte) is removed
+ * alone and never takes a printable character after it (`ESC Z` leaves `Z`), so it cannot eat
+ * the first character of a secret value. A well-formed CSI can still end in a letter (`ESC [ Z`),
+ * which is why the writer masks secret values on the raw text before this runs.
+ * `\r\n` becomes `\n`; a lone `\r` is dropped. Removing characters can only join text, never split
+ * it, so a secret split by colour codes is whole again for redaction, which runs after this.
+ *
+ * No imports: dependency-free, so any reader of step text can share it.
+ */
+/* eslint-disable no-control-regex -- matching control characters is this file's purpose */
+/** OSC, DCS, SOS, PM, APC (7-bit or C1 introducer), up to BEL or ST (ESC \ or C1 ST). */
+const STRING_SEQUENCE = /(?:\x1b[\]PX^_]|[\x90\x98\x9d\x9e\x9f])[^\x07\x1b\x9c]*(?:\x07|\x1b\\|\x9c)/g;
+/** CSI (7-bit or C1): parameter bytes, intermediate bytes, one final byte. */
+const CSI_SEQUENCE = /(?:\x1b\[|\x9b)[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g;
+/** C0 except \t and \n (\r included), DEL, and C1. */
+const CONTROL = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+/* eslint-enable no-control-regex */
+/** `text` without terminal control sequences or control characters other than `\n` and `\t`. */
+export function stripControlSequences(text) {
+    return text.replace(STRING_SEQUENCE, "").replace(CSI_SEQUENCE, "").replace(/\r\n/g, "\n").replace(CONTROL, "");
+}

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

@@ -0,0 +1,32 @@
+import { type ExtractedResult, type ExtractedStep } from "./types.js";
+/**
+ * `text` collapsed as summaries are (collapseWhitespace: runs of whitespace become one space,
+ * trimmed), with each collapsed character's [from, to) span in `text`.
+ */
+export declare function collapseWithMap(text: string): {
+    collapsed: string;
+    from: number[];
+    to: number[];
+};
+/** The most a cut head's partial first line drop takes (afterCutHead). */
+export declare const CUT_HEAD_DROP_CHARS = 256;
+/** A tool step's stored detail with its output appended, within MAX_STEP_DETAIL_CHARS. */
+export declare function joinDetail(existing: string | null, suffix: string): string;
+export interface StepDetailer {
+    /**
+     * `raw` (untrusted text before control sequences are stripped) with every form of every secret
+     * value, the secret start it ends in, the secret end it starts with when its head was cut, and
+     * both at every line and ellipsis boundary, each replaced by `marker`: so a stripped escape
+     * sequence cannot take a character of a secret, whole or partial, and hide the rest of it.
+     */
+    premask(raw: string, headWasCut: boolean, marker: string): string;
+    /** A step's detail: a tool's input (or its summary text when no input was sent), or a said step's text. */
+    step(step: ExtractedStep): string;
+    /** The text appended to a tool step's detail when its result arrives: the heading and the output's redacted end. */
+    output(result: Required<Pick<ExtractedResult, "output">> & Pick<ExtractedResult, "outputCut">): string;
+}
+/**
+ * Detail texts for one batch, against every secret value delivered to the run (the agent's and the
+ * run's own). The forms, and each form's KMP table for the edge checks, are built once per batch.
+ */
+export declare function stepDetailer(secretValues: readonly string[]): StepDetailer;