@boardwalk-labs/runner 0.1.2

package/dist/runtime/agent/budget.d.ts

@@ -0,0 +1,123 @@
+import type { Budget } from "../wire/manifest.js";
+/** Per-million-token rates. */
+export interface ModelRate {
+    /** USD per million input tokens. */
+    inputPerMillion: number;
+    /** USD per million output tokens. */
+    outputPerMillion: number;
+    /** USD per million cache-read tokens (Anthropic). Defaults to inputPerMillion / 10. */
+    cacheReadPerMillion?: number;
+    /** USD per million cache-write tokens (Anthropic). Defaults to inputPerMillion * 1.25. */
+    cacheWritePerMillion?: number;
+}
+export interface UsageDelta {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/**
+ * Cumulative usage carried forward from PRIOR worker sessions of the same run. Seeded from the
+ * checkpoint on resume so budget caps bound the WHOLE run, not just the current session — a run
+ * that sleeps / waits on a child / recovers from a crash must not get a fresh budget each time
+ * (review #2). Zero for a fresh run.
+ */
+export interface PriorUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalUsd: number;
+    /**
+     * Active execution time from prior sessions (ms). Only on-CPU turn time counts toward the
+     * duration cap — sleep/wait pauses don't burn it (a run intentionally parked for a day must
+     * not blow its duration budget on resume).
+     */
+    activeMs: number;
+}
+export interface BudgetMeterOptions {
+    budget?: Budget;
+    /** Rate for the model the agent is configured with. */
+    rate: ModelRate;
+    /** This SESSION's start time (ms). Per-session active duration is measured from here. */
+    startedAt: number;
+    /** The RUN's original start time (ms) — the basis for `deadline_seconds`, a WALL-CLOCK cap that
+     *  INCLUDES suspended idle (unlike max_duration_seconds, which is active compute). Omit to leave
+     *  the deadline cap unenforced (e.g. a run that hasn't started yet). */
+    deadlineStartedAt?: number;
+    /** Cumulative usage from prior sessions of this run (resume). Defaults to zero. */
+    priorUsage?: PriorUsage;
+    /** Injected clock for tests. */
+    now?: () => number;
+}
+export interface BudgetSnapshot {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    totalUsd: number;
+    elapsedMs: number;
+}
+export declare class BudgetMeter {
+    private readonly budget;
+    private readonly rate;
+    private readonly startedAt;
+    private readonly deadlineStartedAt;
+    private readonly prior;
+    private readonly now;
+    private inputTokens;
+    private outputTokens;
+    private cacheReadTokens;
+    private cacheWriteTokens;
+    private totalUsd;
+    constructor(opts: BudgetMeterOptions);
+    /**
+     * Add a usage delta to the accumulator + recompute USD. `realCostUsd`, when provided, is the EXACT
+     * upstream cost the broker observed for this turn (OpenRouter's per-request `usage.cost`) — used
+     * verbatim so the `max_usd` cap tracks ACTUAL spend (already cache-discounted, model-correct).
+     * Omitted for a BYO turn (no upstream price) or a managed turn whose cost the broker couldn't read,
+     * which fall back to the representative-rate {@link costFor} estimate. Token counts accumulate on
+     * both paths (they drive the `max_tokens` cap + the snapshot); only the USD basis differs.
+     */
+    addUsage(delta: UsageDelta, realCostUsd?: number): void;
+    /**
+     * THIS SESSION's accumulator snapshot (excludes prior-session usage). Read by per-session token
+     * metering — which reports token deltas to Stripe (deferred; not yet wired into the brokered
+     * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
+     */
+    snapshot(): BudgetSnapshot;
+    /**
+     * RUN-CUMULATIVE snapshot: this session's usage PLUS the prior sessions' usage seeded at
+     * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
+     * this so a run that resumes after a sleep/wait/crash is bounded by its declared caps across
+     * the whole run — not once per session (review #2). `snapshot()` stays session-local because
+     * per-session token metering reports token deltas; seeding it would double-report to Stripe.
+     */
+    cumulative(): BudgetSnapshot;
+    /**
+     * Throws `AppError(BUDGET_EXCEEDED)` when any cap is breached. Call BETWEEN
+     * turns (after `addUsage` reflects the latest delta) — that way the meter
+     * tears the loop down before another LLM call is dispatched.
+     */
+    assertWithinCaps(): void;
+    /**
+     * Predicate variant for callers that prefer to handle the cap-hit path
+     * inline (e.g., the sleep tool rejects a sleep that would breach the
+     * duration cap). Returns the first breach reason or null.
+     */
+    capBreachReason(): "tokens" | "usd" | "duration" | "deadline" | null;
+    /**
+     * The declared `max_duration_seconds` cap, or null when unset. Lets callers that
+     * reason about wall-clock ahead of time (e.g. the sleep tool rejecting a sleep that
+     * would overrun the run) read the cap without reaching into the meter's internals.
+     */
+    durationCapSeconds(): number | null;
+    /**
+     * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports
+     * no real upstream cost for the turn (a BYO-provider turn, or a managed turn whose cost tap missed).
+     * Managed turns instead carry OpenRouter's exact `usage.cost` through to {@link addUsage}. Public so
+     * the loop can stamp the per-step `cost_usd` column on `run_steps` without re-deriving the rate table.
+     */
+    costFor(delta: UsageDelta): number;
+}

package/dist/runtime/agent/budget.js

@@ -0,0 +1,174 @@
+// BudgetMeter — enforces token / USD / duration caps declared in the manifest.
+//
+// One meter per run. The agent loop calls `addUsage()` after each LLM turn and
+// `assertWithinCaps()` between turns. When a cap is exceeded the meter throws
+// `AppError(BUDGET_EXCEEDED)` and the loop tears down with a `turn_ended
+// reason='error'` event.
+//
+// USD here tracks the bill closely: for a MANAGED turn the meter is fed OpenRouter's exact per-request
+// `usage.cost` (already cache-discounted + model-correct), so the `max_usd` cap reflects real spend —
+// not a hand-rolled token estimate. Only a BYO turn (no upstream price) or a managed turn whose cost
+// the broker couldn't read falls back to a single flat representative rate
+// (`model_rates.ts::BUDGET_GUARDRAIL_RATE`), since a per-`agent()`-model run has no one model. Actual
+// billing remains per-request cost pass-through via Stripe meters (MASTER_SPEC §15.2). The meter takes
+// the fallback rate as a constructor arg so tests inject a fixed rate.
+import { AppError, ErrorCode } from "../support/index.js";
+const ZERO_PRIOR = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    totalUsd: 0,
+    activeMs: 0,
+};
+export class BudgetMeter {
+    budget;
+    rate;
+    startedAt;
+    deadlineStartedAt;
+    prior;
+    now;
+    inputTokens = 0;
+    outputTokens = 0;
+    cacheReadTokens = 0;
+    cacheWriteTokens = 0;
+    totalUsd = 0;
+    constructor(opts) {
+        if (opts.budget !== undefined)
+            this.budget = opts.budget;
+        this.rate = opts.rate;
+        this.startedAt = opts.startedAt;
+        this.deadlineStartedAt = opts.deadlineStartedAt ?? null;
+        this.prior = opts.priorUsage ?? ZERO_PRIOR;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Add a usage delta to the accumulator + recompute USD. `realCostUsd`, when provided, is the EXACT
+     * upstream cost the broker observed for this turn (OpenRouter's per-request `usage.cost`) — used
+     * verbatim so the `max_usd` cap tracks ACTUAL spend (already cache-discounted, model-correct).
+     * Omitted for a BYO turn (no upstream price) or a managed turn whose cost the broker couldn't read,
+     * which fall back to the representative-rate {@link costFor} estimate. Token counts accumulate on
+     * both paths (they drive the `max_tokens` cap + the snapshot); only the USD basis differs.
+     */
+    addUsage(delta, realCostUsd) {
+        this.inputTokens += delta.inputTokens ?? 0;
+        this.outputTokens += delta.outputTokens ?? 0;
+        this.cacheReadTokens += delta.cacheReadTokens ?? 0;
+        this.cacheWriteTokens += delta.cacheWriteTokens ?? 0;
+        this.totalUsd += realCostUsd ?? this.costFor(delta);
+    }
+    /**
+     * THIS SESSION's accumulator snapshot (excludes prior-session usage). Read by per-session token
+     * metering — which reports token deltas to Stripe (deferred; not yet wired into the brokered
+     * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
+     */
+    snapshot() {
+        return {
+            inputTokens: this.inputTokens,
+            outputTokens: this.outputTokens,
+            cacheReadTokens: this.cacheReadTokens,
+            cacheWriteTokens: this.cacheWriteTokens,
+            totalTokens: this.inputTokens + this.outputTokens,
+            totalUsd: this.totalUsd,
+            elapsedMs: this.now() - this.startedAt,
+        };
+    }
+    /**
+     * RUN-CUMULATIVE snapshot: this session's usage PLUS the prior sessions' usage seeded at
+     * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
+     * this so a run that resumes after a sleep/wait/crash is bounded by its declared caps across
+     * the whole run — not once per session (review #2). `snapshot()` stays session-local because
+     * per-session token metering reports token deltas; seeding it would double-report to Stripe.
+     */
+    cumulative() {
+        const s = this.snapshot();
+        return {
+            inputTokens: s.inputTokens + this.prior.inputTokens,
+            outputTokens: s.outputTokens + this.prior.outputTokens,
+            cacheReadTokens: s.cacheReadTokens + this.prior.cacheReadTokens,
+            cacheWriteTokens: s.cacheWriteTokens + this.prior.cacheWriteTokens,
+            totalTokens: s.inputTokens + this.prior.inputTokens + s.outputTokens + this.prior.outputTokens,
+            totalUsd: s.totalUsd + this.prior.totalUsd,
+            elapsedMs: s.elapsedMs + this.prior.activeMs,
+        };
+    }
+    /**
+     * Throws `AppError(BUDGET_EXCEEDED)` when any cap is breached. Call BETWEEN
+     * turns (after `addUsage` reflects the latest delta) — that way the meter
+     * tears the loop down before another LLM call is dispatched.
+     */
+    assertWithinCaps() {
+        if (this.budget === undefined)
+            return;
+        // Cumulative across resume sessions — caps bound the whole run, not each session (review #2).
+        const snap = this.cumulative();
+        // `max_tokens` deliberately bounds CONVERSATION tokens (input + output) only; cache-read /
+        // cache-write tokens are tracked + fully billed via costFor() and are bounded by `max_usd`,
+        // not by this cap (review #19). totalTokens (snapshot/cumulative) reflects that choice.
+        if (this.budget.max_tokens !== undefined && snap.totalTokens > this.budget.max_tokens) {
+            throw new AppError(ErrorCode.BUDGET_EXCEEDED, `Token cap exceeded: ${snap.totalTokens.toString()} > ${this.budget.max_tokens.toString()}`, { kind: "tokens", used: snap.totalTokens, cap: this.budget.max_tokens });
+        }
+        if (this.budget.max_usd !== undefined && snap.totalUsd > this.budget.max_usd) {
+            throw new AppError(ErrorCode.BUDGET_EXCEEDED, `USD cap exceeded: $${snap.totalUsd.toFixed(4)} > $${this.budget.max_usd.toFixed(4)}`, { kind: "usd", used: snap.totalUsd, cap: this.budget.max_usd });
+        }
+        if (this.budget.max_duration_seconds !== undefined) {
+            const elapsedSeconds = Math.floor(snap.elapsedMs / 1000);
+            if (elapsedSeconds > this.budget.max_duration_seconds) {
+                throw new AppError(ErrorCode.BUDGET_EXCEEDED, `Duration cap exceeded: ${elapsedSeconds.toString()}s > ${this.budget.max_duration_seconds.toString()}s`, { kind: "duration", used: elapsedSeconds, cap: this.budget.max_duration_seconds });
+            }
+        }
+        // deadline_seconds: WALL-CLOCK from the run's original start, INCLUDING suspended idle (a run
+        // resumed past its deadline trips on its first cap check; a long-running one trips per turn).
+        // Distinct from max_duration_seconds (active compute) — a long sleep / human-input wait does not
+        // burn that, but DOES count here.
+        if (this.budget.deadline_seconds !== undefined && this.deadlineStartedAt !== null) {
+            const wallSeconds = Math.floor((this.now() - this.deadlineStartedAt) / 1000);
+            if (wallSeconds > this.budget.deadline_seconds) {
+                throw new AppError(ErrorCode.BUDGET_EXCEEDED, `Deadline exceeded: ${wallSeconds.toString()}s > ${this.budget.deadline_seconds.toString()}s (wall-clock)`, { kind: "deadline", used: wallSeconds, cap: this.budget.deadline_seconds });
+            }
+        }
+    }
+    /**
+     * Predicate variant for callers that prefer to handle the cap-hit path
+     * inline (e.g., the sleep tool rejects a sleep that would breach the
+     * duration cap). Returns the first breach reason or null.
+     */
+    capBreachReason() {
+        try {
+            this.assertWithinCaps();
+            return null;
+        }
+        catch (err) {
+            if (err instanceof AppError &&
+                typeof err.detail === "object" &&
+                err.detail !== null &&
+                "kind" in err.detail) {
+                return err.detail.kind;
+            }
+            throw err;
+        }
+    }
+    /**
+     * The declared `max_duration_seconds` cap, or null when unset. Lets callers that
+     * reason about wall-clock ahead of time (e.g. the sleep tool rejecting a sleep that
+     * would overrun the run) read the cap without reaching into the meter's internals.
+     */
+    durationCapSeconds() {
+        return this.budget?.max_duration_seconds ?? null;
+    }
+    /**
+     * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports
+     * no real upstream cost for the turn (a BYO-provider turn, or a managed turn whose cost tap missed).
+     * Managed turns instead carry OpenRouter's exact `usage.cost` through to {@link addUsage}. Public so
+     * the loop can stamp the per-step `cost_usd` column on `run_steps` without re-deriving the rate table.
+     */
+    costFor(delta) {
+        const inputCost = ((delta.inputTokens ?? 0) * this.rate.inputPerMillion) / 1_000_000;
+        const outputCost = ((delta.outputTokens ?? 0) * this.rate.outputPerMillion) / 1_000_000;
+        const cacheReadRate = this.rate.cacheReadPerMillion ?? this.rate.inputPerMillion / 10;
+        const cacheWriteRate = this.rate.cacheWritePerMillion ?? this.rate.inputPerMillion * 1.25;
+        const cacheReadCost = ((delta.cacheReadTokens ?? 0) * cacheReadRate) / 1_000_000;
+        const cacheWriteCost = ((delta.cacheWriteTokens ?? 0) * cacheWriteRate) / 1_000_000;
+        return inputCost + outputCost + cacheReadCost + cacheWriteCost;
+    }
+}

package/dist/runtime/agent/events.d.ts

@@ -0,0 +1,46 @@
+export { runEventSchema, CHANNELS, DEFAULT_CHANNELS, channelOf, matchesChannels, makeCursor, TURN_CURSOR_STRIDE, type RunEvent, type RunEventKind, type Channel, type EventEnvelope, type TokenUsage, type ToolReturn, } from "@boardwalk-labs/workflow";
+import type { RunEvent } from "@boardwalk-labs/workflow";
+/** Error shape on `tool_call_error` and `turn_ended` (reason='error') — the SDK's event error. */
+export interface AgentApiError {
+    code: string;
+    message: string;
+}
+/** Distributive omit that preserves the discriminated union. */
+type BodyOf<E> = E extends RunEvent ? Omit<E, "runId" | "turnId" | "seq" | "t"> : never;
+/**
+ * A run event WITHOUT its envelope — what producers (the normalizer, the phase tracker, the log
+ * capture) build. The shared emitter stamps the envelope + computes the cursor.
+ */
+export type RunEventBody = BodyOf<RunEvent>;
+/** The published/stored row: the run-global cursor + the full enveloped event (engine parity). */
+export interface RunEventRow {
+    cursor: number;
+    event: RunEvent;
+}
+/**
+ * Minimal Redis publisher surface (publish only). We depend only on `publish` so tests inject a
+ * fake without pulling in ioredis; production wires the broker telemetry publisher.
+ */
+export interface RedisPublisher {
+    publish(channel: string, message: string): Promise<number>;
+}
+/**
+ * The shared per-run emitter surface a turn stamps through (the worker's WorkerRunEventEmitter
+ * satisfies it). `emit` stamps the envelope + cursor on a body and rides the current stride block;
+ * `beginTurn` opens a new agent stride block, then emits its opening frame (the caller supplies
+ * `turn_started`).
+ */
+export interface TurnEventSink {
+    emit(body: RunEventBody, turnId?: string): RunEvent;
+    beginTurn(turnId: string, started: RunEventBody): void;
+}
+/**
+ * Identity of one agent() leaf — stamped on its `turn_started`/`turn_ended` frames so a stream
+ * consumer can tell concurrent agents apart. `agentId` is stable + run-unique (worker-assigned);
+ * `agentName` is the author's `AgentOptions.name`, present only when set. Mirrors the engine's
+ * `AgentIdentity` shape so the platform's wire matches `boardwalk dev` and the self-hosted server.
+ */
+export interface AgentIdentity {
+    agentId: string;
+    agentName?: string;
+}

package/dist/runtime/agent/events.js

@@ -0,0 +1,8 @@
+// Run-event wire format — ADOPTED from the published SDK (flip item, 2026-06-12).
+//
+// The contract lives in `@boardwalk-labs/workflow` (`runEventSchema`, CHANNELS, cursors): one
+// typed, ordered stream per run, identical in every engine. This module re-exports the SDK
+// contract and defines the BODY shape producers build (the envelope — runId / turnId / seq / t —
+// is stamped centrally by the worker's shared RunEventEmitter, which owns the run-global
+// `cursor = turn * TURN_CURSOR_STRIDE + seq` counter exactly like the OSS engine's supervisor).
+export { runEventSchema, CHANNELS, DEFAULT_CHANNELS, channelOf, matchesChannels, makeCursor, TURN_CURSOR_STRIDE, } from "@boardwalk-labs/workflow";

package/dist/runtime/agent/model_rates.d.ts

@@ -0,0 +1,7 @@
+import type { ModelRate } from "./budget.js";
+/**
+ * The flat representative rate (USD / million tokens) the BudgetMeter applies to the `max_usd` cap
+ * ONLY as the fallback for a turn with no real upstream cost (BYO / unavailable); a managed turn caps
+ * on its exact `usage.cost`. Sonnet-class list pricing — a model-agnostic backstop, not the billed price.
+ */
+export declare const BUDGET_GUARDRAIL_RATE: ModelRate;

package/dist/runtime/agent/model_rates.js

@@ -0,0 +1,21 @@
+// The flat budget-guardrail rate — the FALLBACK basis for the in-run `max_usd` cap (BudgetMeter).
+//
+// A MANAGED turn now caps on OpenRouter's EXACT per-request `usage.cost`, forwarded from the broker to
+// the worker (inference_proxy result frame → BudgetMeter.addUsage `realCostUsd`), so the cap tracks
+// real spend — already cache-discounted + model-correct. This flat rate is used ONLY when a turn has
+// no upstream cost: a BYO-provider turn (the org pays its own key), or a managed turn whose cost the
+// broker couldn't read. It bounds runaway loops; it is NOT the bill. Actual billing is per-request
+// COST PASS-THROUGH (OpenRouter's reported cost × margin) via Stripe meters (domain/billing +
+// run_usage_service). MASTER_SPEC §15.2.
+//
+// Deliberately NOT a per-model table with a silent fallback: a lookup that returns a Sonnet-class
+// default for any unknown id only created the ILLUSION of precision. The real per-request cost (above)
+// is the precise path; this rate is just the model-agnostic backstop. Un-metered managed models are
+// rejected fail-closed at resolution (domain/inference/model_resolver), so the cap never has to price
+// a model we don't support.
+/**
+ * The flat representative rate (USD / million tokens) the BudgetMeter applies to the `max_usd` cap
+ * ONLY as the fallback for a turn with no real upstream cost (BYO / unavailable); a managed turn caps
+ * on its exact `usage.cost`. Sonnet-class list pricing — a model-agnostic backstop, not the billed price.
+ */
+export const BUDGET_GUARDRAIL_RATE = { inputPerMillion: 3, outputPerMillion: 15 };

package/dist/runtime/agent/secret_redactor.d.ts

@@ -0,0 +1,42 @@
+/** Replacement token substituted for any known secret value. Generic on purpose — it must not
+ *  reveal WHICH secret matched. */
+export declare const REDACTION_PLACEHOLDER = "[REDACTED]";
+/**
+ * Values shorter than this are NOT recorded. A 1–3 char "secret" would match common substrings and
+ * shred unrelated text; real credentials are long. Mirrors GitHub Actions' masking floor. A value
+ * this short should not be a secret in the first place — and the structural guarantee (secrets never
+ * flow to the LLM by construction) still holds for it; only the belt-and-suspenders scrub is skipped.
+ */
+export declare const MIN_REDACTABLE_LENGTH = 4;
+export interface SecretRedactorOptions {
+    placeholder?: string;
+    minLength?: number;
+}
+export declare class SecretRedactor {
+    /** Recorded secret values, kept sorted longest-first so a longer secret is replaced before any
+     *  shorter secret that is its substring. */
+    private recorded;
+    private readonly seen;
+    private readonly placeholder;
+    private readonly minLength;
+    constructor(opts?: SecretRedactorOptions);
+    /** Number of distinct values currently being redacted. */
+    get size(): number;
+    /** A snapshot of the recorded secret values (longest-first). Read by the worker to seed a fresh
+     *  engine `Redactor` per leaf so the engine loop scrubs the SAME values out of model-bound content. */
+    get values(): readonly string[];
+    /**
+     * Record a resolved secret value so future LLM-bound content has it scrubbed. No-op for values
+     * below the length floor or already known. Idempotent.
+     */
+    record(value: string): void;
+    /** Replace every occurrence of every known secret value in `text` with the placeholder. */
+    redactText(text: string): string;
+    /**
+     * Deep-redact a JSON-shaped value: strings are scrubbed, arrays/objects recursed. Non-string
+     * primitives pass through (a secret is always a string). Returns the input unchanged when nothing
+     * is recorded, so the common no-secrets case is allocation-free.
+     */
+    redactValue(value: unknown): unknown;
+    private redactAt;
+}

package/dist/runtime/agent/secret_redactor.js

@@ -0,0 +1,98 @@
+// SecretRedactor — scrubs known secret values from everything bound for an LLM (MASTER_SPEC §12,
+// docs/WORKFLOW_RUNTIME.md §6.2, plan #9).
+//
+// The architectural guarantee is structural: secrets live ONLY in the workflow PROGRAM (the trusted
+// deterministic tool layer), which holds them via `secrets.get` / `ctx.secrets.resolve`. The
+// `agent()` leaf never receives a secret by design — so prompt injection can't reach one. This
+// redactor is DEFENSE-IN-DEPTH for the path where a program (or a tool result) inadvertently
+// carries a known secret value into LLM context (prompt, system prompt, tool args/results,
+// transcript): every value the run resolves is recorded here, and the leaf scrubs known values out
+// of LLM-bound text before the model ever sees them.
+//
+// Pure logic by design (no I/O, no deps) so it can be tested exhaustively — the platform's secret
+// boundary lives here.
+/** Replacement token substituted for any known secret value. Generic on purpose — it must not
+ *  reveal WHICH secret matched. */
+export const REDACTION_PLACEHOLDER = "[REDACTED]";
+/**
+ * Values shorter than this are NOT recorded. A 1–3 char "secret" would match common substrings and
+ * shred unrelated text; real credentials are long. Mirrors GitHub Actions' masking floor. A value
+ * this short should not be a secret in the first place — and the structural guarantee (secrets never
+ * flow to the LLM by construction) still holds for it; only the belt-and-suspenders scrub is skipped.
+ */
+export const MIN_REDACTABLE_LENGTH = 4;
+/** Bound on recursion into nested tool results. JSON has no cycles, but a pathological structure
+ *  shouldn't blow the stack; beyond this depth a value can't realistically still be a secret. */
+const MAX_REDACT_DEPTH = 100;
+export class SecretRedactor {
+    /** Recorded secret values, kept sorted longest-first so a longer secret is replaced before any
+     *  shorter secret that is its substring. */
+    recorded = [];
+    seen = new Set();
+    placeholder;
+    minLength;
+    constructor(opts = {}) {
+        this.placeholder = opts.placeholder ?? REDACTION_PLACEHOLDER;
+        this.minLength = opts.minLength ?? MIN_REDACTABLE_LENGTH;
+    }
+    /** Number of distinct values currently being redacted. */
+    get size() {
+        return this.recorded.length;
+    }
+    /** A snapshot of the recorded secret values (longest-first). Read by the worker to seed a fresh
+     *  engine `Redactor` per leaf so the engine loop scrubs the SAME values out of model-bound content. */
+    get values() {
+        return [...this.recorded];
+    }
+    /**
+     * Record a resolved secret value so future LLM-bound content has it scrubbed. No-op for values
+     * below the length floor or already known. Idempotent.
+     */
+    record(value) {
+        if (value.length < this.minLength)
+            return;
+        if (this.seen.has(value))
+            return;
+        this.seen.add(value);
+        this.recorded.push(value);
+        // Longest-first: replacing the longer match first keeps a shorter substring secret from
+        // fragmenting the longer one (e.g. "abc" before "abcdef" would leave "[REDACTED]def").
+        this.recorded.sort((a, b) => b.length - a.length);
+    }
+    /** Replace every occurrence of every known secret value in `text` with the placeholder. */
+    redactText(text) {
+        if (this.recorded.length === 0)
+            return text;
+        let out = text;
+        for (const v of this.recorded) {
+            if (out.includes(v))
+                out = out.split(v).join(this.placeholder);
+        }
+        return out;
+    }
+    /**
+     * Deep-redact a JSON-shaped value: strings are scrubbed, arrays/objects recursed. Non-string
+     * primitives pass through (a secret is always a string). Returns the input unchanged when nothing
+     * is recorded, so the common no-secrets case is allocation-free.
+     */
+    redactValue(value) {
+        if (this.recorded.length === 0)
+            return value;
+        return this.redactAt(value, 0);
+    }
+    redactAt(value, depth) {
+        if (typeof value === "string")
+            return this.redactText(value);
+        if (depth >= MAX_REDACT_DEPTH)
+            return value;
+        if (Array.isArray(value))
+            return value.map((v) => this.redactAt(v, depth + 1));
+        if (value !== null && typeof value === "object") {
+            const out = {};
+            for (const [k, v] of Object.entries(value))
+                out[k] = this.redactAt(v, depth + 1);
+            return out;
+        }
+        return value;
+    }
+}

package/dist/runtime/broker_artifact_store.d.ts

@@ -0,0 +1,17 @@
+import type { ArtifactCommitInput, ArtifactPresignInput, ArtifactPresignResult, ArtifactSignResult, ArtifactStore, ArtifactSummary, ArtifactWriteInput, ArtifactWriteResult } from "./tools/artifacts.js";
+/** The broker surface the store needs (RunnerControlClient satisfies it). */
+export interface ArtifactBrokerTransport {
+    writeArtifact(input: ArtifactWriteInput): Promise<ArtifactWriteResult>;
+    presignArtifact(input: ArtifactPresignInput): Promise<ArtifactPresignResult>;
+    uploadBytes(url: string, headers: Record<string, string>, body: Uint8Array): Promise<void>;
+    commitArtifact(input: ArtifactCommitInput): Promise<ArtifactWriteResult>;
+    listArtifacts(): Promise<ArtifactSummary[]>;
+    signArtifactUrl(artifactId: string, ttlSeconds: number): Promise<ArtifactSignResult>;
+}
+export declare class BrokerArtifactStore implements ArtifactStore {
+    private readonly broker;
+    constructor(broker: ArtifactBrokerTransport);
+    write(input: ArtifactWriteInput): Promise<ArtifactWriteResult>;
+    list(): Promise<ArtifactSummary[]>;
+    signedUrl(artifactId: string, ttlSeconds: number): Promise<ArtifactSignResult>;
+}

package/dist/runtime/broker_artifact_store.js

@@ -0,0 +1,46 @@
+// BrokerArtifactStore — the ArtifactStore the `artifacts` tool uses under the Runner Credential
+// Broker (docs/RUNNER_BROKER.md §4 — Artifacts). It forwards every op to the Runner Control API:
+// the broker computes the S3 key, neutralizes the served content type (review #32), PUTs with its
+// own creds, and records the catalog row — so the untrusted runner holds no S3 credential and can't
+// bypass those server-side rules. A thin adapter over the run-bound RunnerControlClient.
+//
+// Writes route by size (docs/RUNNER_BROKER.md §7 step 4): a SMALL body is proxied inline through the
+// broker (`POST .../artifacts`); a LARGE one takes the presigned-PUT path — the broker signs an S3
+// PUT (still owning the key + content-type neutralization + catalog row) and the runner streams the
+// bytes straight to S3, so they never pass through the control plane (no body cap).
+import { decodeArtifactBody, shouldPresignArtifact } from "./wire/artifact_storage.js";
+export class BrokerArtifactStore {
+    broker;
+    constructor(broker) {
+        this.broker = broker;
+    }
+    async write(input) {
+        const bytes = decodeArtifactBody(input.body, input.encoding);
+        if (!shouldPresignArtifact(bytes.length)) {
+            // Small: proxy the bytes inline (the broker neutralizes + PUTs + catalogs in one round trip).
+            return this.broker.writeArtifact(input);
+        }
+        // Large: presign → PUT bytes straight to S3 → commit. The broker owns the key, content-type
+        // neutralization, and the catalog row; only the byte transfer skips the control plane. The row is
+        // registered at commit, AFTER the PUT — so a failed upload (uploadBytes throws here) leaves none.
+        const presign = await this.broker.presignArtifact({
+            name: input.name,
+            contentType: input.contentType,
+            sizeBytes: bytes.length,
+        });
+        await this.broker.uploadBytes(presign.uploadUrl, presign.uploadHeaders, bytes);
+        return this.broker.commitArtifact({
+            s3Key: presign.s3Key,
+            name: input.name,
+            contentType: input.contentType,
+            sizeBytes: bytes.length,
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+        });
+    }
+    list() {
+        return this.broker.listArtifacts();
+    }
+    signedUrl(artifactId, ttlSeconds) {
+        return this.broker.signArtifactUrl(artifactId, ttlSeconds);
+    }
+}

package/dist/runtime/broker_child_dispatcher.d.ts

@@ -0,0 +1,31 @@
+import type { CallOptions } from "@boardwalk-labs/workflow/runtime";
+import type { ChildDispatcher, ChildResult, ScheduleOptions } from "./workflow_host.js";
+import type { RunnerControlClient } from "./runner_control_client.js";
+export interface BrokerChildDispatcherDeps {
+    client: RunnerControlClient;
+    /** Wait between polls. Injected so tests don't sleep on real time. Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    pollIntervalMs?: number;
+}
+export declare class BrokerChildDispatcher implements ChildDispatcher {
+    private readonly deps;
+    private readonly sleep;
+    private readonly pollIntervalMs;
+    constructor(deps: BrokerChildDispatcherDeps);
+    /** Create (or re-attach to) the child, then hold + poll to terminal and return its output. An
+     *  abort (`signal`) stops the hold within one poll interval and throws RunAbortedError. */
+    call(slug: string, input: unknown, _opts: CallOptions | undefined, signal?: AbortSignal): Promise<unknown>;
+    /** Start (or idempotently re-attach to) the child and resolve its CURRENT state — no hold. The
+     *  durable callWorkflow seam decides whether to suspend (non-terminal) or return (terminal). */
+    start(slug: string, input: unknown, _opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildResult>;
+    /** Poll a child's current state by id (the resume path), or null when it isn't this run's child. */
+    poll(childRunId: string): Promise<ChildResult | null>;
+    /** Fire-and-forget: create (or re-attach to) the child and return its id without holding. */
+    run(slug: string, input: unknown, _opts: CallOptions | undefined): Promise<string>;
+    /** Provision a durable schedule via the broker; returns the new schedule's id. A `Date` `at` is
+     *  normalized to an ISO string (the broker spec carries string | number, not Date). */
+    schedule(slug: string, input: unknown, opts: ScheduleOptions): Promise<string>;
+    private pollToCompletion;
+    /** A completed child returns its output; a failed/cancelled child rejects the parent's await. */
+    private childOutput;
+}