@basein/runner 0.1.0

package/dist/replay/controller.js

@@ -0,0 +1,807 @@
+/**
+ * controller — everything replay decides, in one place (docs/calculatedReplay.md).
+ *
+ * The control server owns runs, ordering and recording. This owns the *plan*:
+ * the gate ladder, the mode choice, arming, pinning, threading, direct
+ * execution, divergence recovery and the execution report. `ControlServer`
+ * delegates to it and stores one {@link ReplayState} per run.
+ *
+ * THE GOVERNING RULE IS UNCHANGED and outranks every optimisation here: the host
+ * session must never fail because of BaseInstRunner. Every method below either
+ * degrades to "run the turn normally" or returns something the session can
+ * ignore. Nothing throws at a hook.
+ */
+import { parseQualifiedName } from "../control/correlation.js";
+import { isHousekeeping } from "../record/housekeeping.js";
+import { redact } from "../record/redact.js";
+import { serializeCapped } from "../record/truncate.js";
+import { logDetail, logLine, errText } from "../util/log.js";
+import { MAX_REPLAY_REASON } from "./bundle.js";
+import { coverageOf, modeFor, reachOf } from "./coverage.js";
+import { deriveParameters } from "./derive.js";
+import { ProxyWorkQueue } from "./executor.js";
+import { ScenarioReplayPlan } from "./plan.js";
+import { PRICING_VERSION } from "./pricing.js";
+import { SourceRunOutputs } from "./source-run.js";
+import { toolResultError } from "./tool-error.js";
+import { OUTCOME_RANK, isReadyScenario, } from "./types.js";
+/** The first-party tool a `direct` plan is delivered through (§6.3). */
+export const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
+/** How long a `/proxy/poll` is held open before it answers empty. */
+export const POLL_HOLD_MS = 25_000;
+export const DEFAULT_BUDGETS = {
+    matchMs: 2_500,
+    deriveMs: 8_000,
+    planMs: 120_000,
+    stepMs: 60_000,
+};
+/** How many step verdicts one report carries. A chain longer than this is not
+ *  a chain anybody is reading step by step, and the report has to stay small. */
+const MAX_STEP_RESULTS = 200;
+/** Per-step error budget. The console shows these inline, under the step. */
+const MAX_STEP_ERROR_CHARS = 500;
+export class ReplayController {
+    enabled;
+    work = new ProxyWorkQueue();
+    budgets;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.enabled = opts.enabled;
+        this.budgets = { ...DEFAULT_BUDGETS, ...(opts.budgets ?? {}) };
+    }
+    /** The plan's own delivery vehicle is never a scenario step. */
+    isDirectTool(toolName) {
+        return toolName === DIRECT_TOOL_NAME;
+    }
+    /**
+     * Await a match under {@link ReplayBudgets.matchMs}.
+     *
+     * Budget expiry is not an error and never blocks the user: it means this turn
+     * runs normally, and the one `replay.decision` line says so. Resolving `null`
+     * covers both "no match" and "too slow", which are the same thing from here.
+     */
+    async awaitMatch(pending) {
+        let timer;
+        const budget = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), this.budgets.matchMs);
+            timer.unref?.();
+        });
+        try {
+            const match = (await Promise.race([pending, budget]));
+            return match ?? null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Run the gate ladder and, if every gate passes, arm a plan.
+     *
+     * Always returns a state — a declined match still has a ticket to redeem and a
+     * baseline sample to contribute, and losing that is how a savings ledger ends
+     * up with a denominator nobody measured.
+     */
+    arm(match, prompt, wrapped) {
+        const state = {
+            scenarioId: match.scenarioId,
+            ticket: match.executionTicket,
+            similarity: match.similarity,
+            matchedRunId: match.runId,
+            mode: "none",
+            wrapped,
+            pinned: new Map(),
+            outcome: "not_steered",
+            deriveCostUsd: 0,
+            fallbackCostUsd: 0,
+            stepsPlanned: 0,
+            stepsPinned: 0,
+            stepResults: new Map(),
+            armedAt: Date.now(),
+            reported: false,
+            retired: false,
+        };
+        const decline = (why) => {
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                run: match.runId,
+                scenario: match.scenarioId ?? undefined,
+                similarity: match.similarity.toFixed(3),
+                threshold: this.opts.minSimilarity,
+                why,
+            });
+            return state;
+        };
+        // Gate 2 — replay enabled.
+        if (!this.enabled)
+            return decline("BIR_REPLAY is not set");
+        // Gate 3 — a ready scenario with steps.
+        const scenario = match.scenario;
+        if (!match.scenarioId || !isReadyScenario(scenario)) {
+            return decline(match.scenarioId ? "scenario is not ready" : "no scenario for the matched run");
+        }
+        // Gate 4 — similarity. Detection decides "don't record this again"; steering
+        // decides "don't think about this again", which is a much stronger claim and
+        // deserves a stronger threshold.
+        if (match.similarity < this.opts.minSimilarity) {
+            return decline("similarity below threshold");
+        }
+        // Gate 5 — tool coverage.
+        const mode = modeFor(scenario.steps, wrapped, this.opts.allowServers);
+        if (mode === "none")
+            return decline("no step is executable");
+        const params = this.startDerivation(scenario, prompt, state);
+        state.plan = new ScenarioReplayPlan({ scenario, params, mode });
+        state.mode = mode;
+        state.stepsPlanned = scenario.steps.length;
+        if (this.opts.authUrl && this.opts.authToken) {
+            state.sourceRun = new SourceRunOutputs({
+                baseUrl: this.opts.authUrl,
+                runId: scenario.runId,
+                token: this.opts.authToken,
+                fetchImpl: this.opts.fetchImpl,
+            });
+        }
+        // The audit line precedes the action, always (§13.2, mitigation 4).
+        logLine("plan.armed", {
+            run: match.runId,
+            scenario: scenario.id,
+            mode,
+            steps: scenario.steps.length,
+            similarity: match.similarity.toFixed(3),
+            coverage: coverageOf(scenario.steps, wrapped, this.opts.allowServers).join(","),
+            tools: scenario.steps.map((s) => s.toolName).join(","),
+        });
+        return state;
+    }
+    /** The directive to inject via `additionalContext`, or undefined when declined. */
+    directiveFor(state) {
+        return state.plan?.steeringDirective(DIRECT_TOOL_NAME);
+    }
+    /**
+     * `PreToolUse`, while a plan is active.
+     *
+     * Three tiers (§8): pin the expected call; on divergence execute the remainder
+     * and hand it back through the best channel available; if even that fails,
+     * abort to an ordinary turn.
+     */
+    async preTool(state, toolName, toolUseId) {
+        const plan = state.plan;
+        if (!plan || state.retired)
+            return { kind: "passthrough" };
+        // The delivery vehicle for a direct plan is not a step in it.
+        if (this.isDirectTool(toolName))
+            return { kind: "passthrough" };
+        try {
+            await this.withBudget(plan.ready(), this.budgets.deriveMs, "derivation");
+        }
+        catch (err) {
+            logLine("replay.derive_failed", {
+                scenario: state.scenarioId ?? undefined,
+                why: "continuing with the scenario's recorded sample values",
+                error: errText(err),
+            });
+        }
+        // A direct plan does not steer individual calls: the model was asked for one
+        // tool call and made a different one. That is divergence.
+        const expected = plan.expectedTool();
+        if (state.mode === "steer" && toolName === expected && toolUseId) {
+            try {
+                const step = plan.currentStep();
+                const input = plan.toolInputForCurrentStep();
+                state.pinned.set(toolUseId, {
+                    stepIndex: plan.currentStepIndex,
+                    reach: this.reachFor(state, step),
+                    toolName,
+                    pinnedAt: Date.now(),
+                });
+                logDetail("replay.pin", { n: plan.currentStepIndex, tool: toolName });
+                return { kind: "pin", input, stepIndex: plan.currentStepIndex };
+            }
+            catch (err) {
+                // `toolInputLogic` threw: the pin is impossible, but the scenario may
+                // still be recoverable by executing the rest.
+                //
+                // Recorded before diverging, because `composeBundle` starts at this same
+                // step and will throw on the same logic — and its own report would then
+                // be the only trace, attributed to a re-execution rather than to the
+                // steered call that actually hit it first.
+                const step = plan.currentStep();
+                if (step) {
+                    this.recordStep(state, {
+                        step,
+                        outcome: "failed",
+                        stage: "tool_input_logic",
+                        error: errText(err),
+                    });
+                }
+                return await this.diverge(state, toolName, `toolInputLogic threw: ${errText(err)}`);
+            }
+        }
+        // HOUSEKEEPING IS NOT DIVERGENCE. See `record/housekeeping.ts`.
+        if (isHousekeeping(toolName)) {
+            logDetail("replay.housekeeping", {
+                tool: toolName,
+                step: `${plan.currentStepIndex}/${plan.stepCount}`,
+                why: "host bookkeeping, not task work — plan stays armed",
+            });
+            return { kind: "passthrough" };
+        }
+        return await this.diverge(state, toolName, `expected ${expected ?? "no more tools"}, model called ${toolName}`);
+    }
+    /**
+     * `PostToolUse` for a call this plan pinned.
+     *
+     * `output` must be serialized the way the step's output was **recorded**: for a
+     * wrapped MCP step that is the proxy's whole `CallToolResult`, which is why the
+     * server threads those from `/proxy/step` rather than from the hook (§7.2).
+     * Returns true when the plan is now complete.
+     */
+    postTool(state, toolUseId, output) {
+        const plan = state.plan;
+        const pin = state.pinned.get(toolUseId);
+        if (!plan || !pin || state.retired)
+            return false;
+        state.pinned.delete(toolUseId);
+        // The pin's own step, not `currentStep()`: `applyOutput` moves the cursor, so
+        // reading it after the call would judge the *next* step, and reading it
+        // before assumes no other pin ever moved it.
+        const step = plan.allSteps()[pin.stepIndex];
+        let derivedKeys = [];
+        try {
+            derivedKeys = plan.applyOutput(output);
+        }
+        catch (err) {
+            logLine("replay.thread_failed", {
+                scenario: state.scenarioId ?? undefined,
+                step: pin.stepIndex,
+                why: "toolOutputLogic threw — continuing as a normal run",
+                error: errText(err),
+            });
+            if (step) {
+                this.recordStep(state, {
+                    step,
+                    outcome: "failed",
+                    stage: "tool_output_logic",
+                    error: errText(err),
+                    ms: Date.now() - pin.pinnedAt,
+                });
+            }
+            this.retire(state, "failed");
+            return false;
+        }
+        // One more step ran under the plan. Counted here, as each pin threads, and
+        // not from `pinned.size` at pin time: a sequential chain never has more than
+        // one pin outstanding, so that size reported 1 whatever the chain's length.
+        state.stepsPinned += 1;
+        // The step ran in the live session and threaded. This is the only place a
+        // *steered* step is judged: `plan` never sees the call, the host did. A tool
+        // that ran and reported an error did not do the step's work, so the plan is
+        // retired as `failed` — a baseline sample, never a saving.
+        const toolError = step ? toolResultError(output) : undefined;
+        if (step && toolError) {
+            const info = {
+                step,
+                outcome: "failed",
+                stage: "tool_call",
+                error: toolError,
+                ms: Date.now() - pin.pinnedAt,
+            };
+            this.logStep(info);
+            this.recordStep(state, info);
+            this.retire(state, "failed");
+            return false;
+        }
+        if (step) {
+            this.recordStep(state, {
+                step,
+                outcome: "executed",
+                ms: Date.now() - pin.pinnedAt,
+            });
+        }
+        const done = plan.isDone();
+        logDetail("replay.thread", {
+            n: pin.stepIndex,
+            via: pin.reach === "direct" ? "proxy" : "hook",
+            emitted: derivedKeys.join(",") || undefined,
+            done,
+        });
+        if (done) {
+            this.upgrade(state, "steered_full");
+            this.retire(state, undefined);
+            logLine("replay.done", {
+                scenario: state.scenarioId ?? undefined,
+                mode: state.mode,
+                steps: `${plan.stepCount}/${plan.stepCount}`,
+                outcome: state.outcome,
+                ms: Date.now() - state.armedAt,
+            });
+        }
+        return done;
+    }
+    /** Whether a pinned call's output is threaded from the proxy's report (§7.2). */
+    threadsFromProxy(state, toolUseId) {
+        return state.pinned.get(toolUseId)?.reach === "direct";
+    }
+    /** True when this call belongs to the active plan. */
+    isPinned(state, toolUseId) {
+        return state.pinned.has(toolUseId);
+    }
+    /**
+     * `POST /scenario/run` — the whole of a `direct` plan, executed here.
+     *
+     * Every step runs through the proxy that already owns its upstream, so the
+     * model spends nothing beyond the turn that reads the results.
+     */
+    async runArmed(state) {
+        const plan = state.plan;
+        if (!plan || state.retired)
+            return { ok: false, why: "no_plan" };
+        try {
+            await this.withBudget(plan.ready(), this.budgets.deriveMs, "derivation");
+        }
+        catch (err) {
+            logLine("replay.derive_failed", {
+                scenario: state.scenarioId ?? undefined,
+                why: "continuing with the scenario's recorded sample values",
+                error: errText(err),
+            });
+        }
+        const deadline = Date.now() + this.budgets.planMs;
+        let result;
+        try {
+            result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state), deadline);
+        }
+        catch (err) {
+            // The scenario's own logic failed. Retire and let the model do the work.
+            logLine("replay.failed", {
+                scenario: state.scenarioId ?? undefined,
+                why: "scenario logic threw — continuing as a normal run",
+                error: errText(err),
+            });
+            this.retire(state, "failed");
+            return { ok: false, why: "not_ready" };
+        }
+        state.stepsPinned += result.executed + result.recorded;
+        let responseModel = {};
+        try {
+            responseModel = plan.responseModel();
+        }
+        catch (err) {
+            logDetail("replay.response_model_failed", { error: errText(err) });
+        }
+        // A plan whose tools errored ran to the end and did nothing. `steered_full`
+        // would book the largest saving available for it; `failed` books a baseline
+        // sample, which is what a replay that produced nothing is worth (mcpmark.md §13).
+        this.upgrade(state, result.errored > 0
+            ? "failed"
+            : result.partial || result.skipped > 0
+                ? "diverged"
+                : "steered_full");
+        this.retire(state, undefined);
+        logLine("replay.done", {
+            scenario: state.scenarioId ?? undefined,
+            mode: state.mode,
+            steps: `${result.executed + result.recorded}/${plan.stepCount}`,
+            recorded: result.recorded || undefined,
+            skipped: result.skipped || undefined,
+            errored: result.errored || undefined,
+            outcome: state.outcome,
+            partial: result.partial || undefined,
+            ms: Date.now() - state.armedAt,
+        });
+        return {
+            ok: true,
+            text: result.text,
+            responseModel,
+            steps: result.executed + result.recorded,
+            partial: result.partial,
+        };
+    }
+    /**
+     * Build the execution report for a sealed run, or undefined when there is
+     * nothing to report.
+     *
+     * `costUsd <= 0` on a decline is not worth sending: the service answers
+     * `202 { recorded: false }` for a baseline sample with no measured cost, and a
+     * report that books nothing is noise on both sides.
+     */
+    buildReport(state, d) {
+        if (state.reported || !state.scenarioId)
+            return undefined;
+        state.reported = true;
+        const total = state.deriveCostUsd + d.sessionCostUsd + state.fallbackCostUsd;
+        const steps = this.stepResultsOf(state);
+        const isBaseline = state.outcome === "not_steered" || state.outcome === "failed";
+        // A costless decline is noise on both sides — *unless* a step actually broke,
+        // which is the one thing the recording page cannot learn any other way. The
+        // service accepts a costless report that says why (its errorshandling.md).
+        if (isBaseline && total <= 0 && !steps?.some((s) => s.status === "failed")) {
+            return undefined;
+        }
+        const blame = this.blameStep(steps);
+        return {
+            scenarioId: state.scenarioId,
+            ticket: state.ticket,
+            outcome: state.outcome,
+            deriveCostUsd: state.deriveCostUsd,
+            sessionCostUsd: d.sessionCostUsd,
+            fallbackCostUsd: state.fallbackCostUsd,
+            durationMs: d.durationMs,
+            stepsPlanned: state.stepsPlanned,
+            stepsPinned: state.stepsPinned,
+            measured: d.measured,
+            pricingVersion: PRICING_VERSION,
+            prompt: d.prompt,
+            steps,
+            // The headline, lifted from the first step that broke. The console leads
+            // with this and shows the per-step verdicts underneath, so the two must
+            // name the same failure rather than being assembled independently.
+            error: blame?.error,
+            errorStage: blame?.stage,
+            errorStepIndex: blame?.stepIndex,
+            errorToolName: blame?.toolName,
+        };
+    }
+    /**
+     * The step a failed replay is fairly blamed on: the first whose own logic
+     * threw, or failing that the first that could not run at all.
+     *
+     * A `failed` step outranks a `skipped` one however early the skip came — a
+     * scenario whose logic throws is broken for everybody, while a step that could
+     * not run here says something about this machine.
+     */
+    blameStep(steps) {
+        if (!steps)
+            return undefined;
+        return (steps.find((s) => s.status === "failed") ?? steps.find((s) => s.status === "skipped"));
+    }
+    /**
+     * Run a scenario that no match armed — `bir replay` (§12.1).
+     *
+     * The same plan, the same executor, the same live proxies; only the trigger
+     * differs. It is how you test a scenario without a session, how a Tier 2 or
+     * non-Claude-Code client gets any replay at all, and the first thing to reach
+     * for when a steered turn behaves oddly.
+     *
+     * Deliberately outside the gate ladder: the operator typed the scenario id, so
+     * there is nothing to be similar *to* and nothing to decline. It books no
+     * execution either — there is no ticket, and inventing a saving for a manual
+     * invocation is exactly the kind of number a ledger must never contain.
+     */
+    async runAdHoc(scenario, prompt, wrapped) {
+        if (!isReadyScenario(scenario))
+            return { ok: false, why: "scenario is not ready" };
+        const mode = modeFor(scenario.steps, wrapped, this.opts.allowServers);
+        if (mode === "none")
+            return { ok: false, why: "no step is executable" };
+        const state = {
+            scenarioId: scenario.id,
+            similarity: 1,
+            matchedRunId: scenario.runId,
+            mode,
+            wrapped,
+            pinned: new Map(),
+            outcome: "not_steered",
+            deriveCostUsd: 0,
+            fallbackCostUsd: 0,
+            stepsPlanned: scenario.steps.length,
+            stepsPinned: 0,
+            stepResults: new Map(),
+            armedAt: Date.now(),
+            // No ticket, so nothing to redeem — and `buildReport` is never called for
+            // an ad-hoc run anyway.
+            reported: true,
+            retired: false,
+        };
+        const params = this.startDerivation(scenario, prompt, state);
+        const plan = new ScenarioReplayPlan({ scenario, params, mode });
+        state.plan = plan;
+        if (this.opts.authUrl && this.opts.authToken) {
+            state.sourceRun = new SourceRunOutputs({
+                baseUrl: this.opts.authUrl,
+                runId: scenario.runId,
+                token: this.opts.authToken,
+                fetchImpl: this.opts.fetchImpl,
+            });
+        }
+        logLine("plan.armed", {
+            scenario: scenario.id,
+            mode,
+            steps: scenario.steps.length,
+            coverage: coverageOf(scenario.steps, wrapped, this.opts.allowServers).join(","),
+            why: "bir replay — no match, an operator asked for it",
+        });
+        try {
+            await this.withBudget(plan.ready(), this.budgets.deriveMs, "derivation");
+        }
+        catch (err) {
+            logLine("replay.derive_failed", { scenario: scenario.id, error: errText(err) });
+        }
+        const trace = [];
+        try {
+            const result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, (info) => {
+                this.observeStep(state)(info);
+                trace.push({
+                    step: info.step.stepIndex,
+                    tool: info.step.toolName,
+                    input: info.input,
+                    outcome: info.outcome,
+                    ms: info.ms,
+                });
+            }, Date.now() + this.budgets.planMs);
+            let responseModel = {};
+            try {
+                responseModel = plan.responseModel();
+            }
+            catch (err) {
+                logDetail("replay.response_model_failed", { error: errText(err) });
+            }
+            return {
+                ok: true,
+                text: result.text,
+                responseModel,
+                steps: result.executed + result.recorded,
+                partial: result.partial,
+                trace,
+            };
+        }
+        catch (err) {
+            return { ok: false, why: errText(err), trace };
+        }
+    }
+    /** Release every parked poller. Called at control-server shutdown. */
+    close() {
+        this.work.close();
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    /**
+     * Kick off derivation without awaiting it (§10). The prompt hook returns the
+     * directive the moment the match lands; the first `PreToolUse` — or
+     * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
+     */
+    startDerivation(scenario, prompt, state) {
+        const derive = this.opts.deriveImpl ?? deriveParameters;
+        return derive({
+            prompt,
+            intent: scenario.intent ?? "",
+            paramsObject: scenario.paramsObject,
+            apiKey: this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+            fetchImpl: this.opts.fetchImpl,
+        })
+            .then((r) => {
+            state.deriveCostUsd += r.costUsd;
+            logLine("replay.derived", {
+                scenario: scenario.id,
+                params: Object.keys(r.params).length,
+                costUsd: r.costUsd.toFixed(4),
+                source: r.derived ? "prompt" : "recorded samples",
+            });
+            return r.params;
+        })
+            .catch((err) => {
+            logLine("replay.derive_failed", {
+                scenario: scenario.id,
+                why: "falling back to the scenario's recorded sample values",
+                error: errText(err),
+            });
+            const fallback = {};
+            for (const [key, entry] of Object.entries(scenario.paramsObject ?? {})) {
+                fallback[key] = entry.sampleValue;
+            }
+            return fallback;
+        });
+    }
+    /**
+     * Divergence (§8). Execute the remaining steps for real, then deliver.
+     *
+     * The plan is retired first: whatever happens next, this turn neither steers
+     * nor re-injects again.
+     */
+    async diverge(state, toolName, why) {
+        const plan = state.plan;
+        if (!plan)
+            return { kind: "passthrough" };
+        logLine("replay.diverge", {
+            scenario: state.scenarioId ?? undefined,
+            expected: plan.expectedTool() ?? "(none)",
+            called: toolName,
+            step: `${plan.currentStepIndex}/${plan.stepCount}`,
+            why,
+        });
+        this.retire(state, undefined);
+        let composed;
+        try {
+            composed = await plan.composeBundle(MAX_REPLAY_REASON, this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state));
+        }
+        catch (err) {
+            this.upgrade(state, "failed");
+            logLine("replay.compose_failed", {
+                scenario: state.scenarioId ?? undefined,
+                why: "re-execution threw — continuing as a normal run",
+                error: errText(err),
+            });
+            return { kind: "abort" };
+        }
+        // Same rule as `runArmed`: a recovered chain whose tools errored is `failed`.
+        this.upgrade(state, composed.errored > 0 ? "failed" : "diverged");
+        state.stepsPinned += composed.executed + composed.recorded;
+        // The headline number of this whole design: recovering from a divergence
+        // costs nothing, because the proxies were already connected.
+        logLine("replay.compose", {
+            scenario: state.scenarioId ?? undefined,
+            remaining: composed.executed + composed.recorded + composed.skipped,
+            executed: composed.executed,
+            recorded: composed.recorded,
+            skipped: composed.skipped,
+            errored: composed.errored || undefined,
+            bytes: composed.text.length,
+            costUsd: state.fallbackCostUsd.toFixed(2),
+        });
+        logLine("replay.done", {
+            scenario: state.scenarioId ?? undefined,
+            mode: state.mode,
+            steps: `${composed.executed + composed.recorded}/${plan.stepCount}`,
+            outcome: state.outcome,
+            ms: Date.now() - state.armedAt,
+        });
+        if (composed.executed + composed.recorded === 0) {
+            // Nothing survived; a bundle of nothing is worse than no bundle.
+            return { kind: "abort" };
+        }
+        // Bash-clean delivery: the model reaches for `Bash` when it cannot call a
+        // scripted tool, and a genuine command output is trusted where a `deny`
+        // reason is read as adversarial interception. Neutralise the delimiter first.
+        if (toolName === "Bash") {
+            const delimiter = "BIR_EOF";
+            const safe = composed.text.split(delimiter).join("BIR_EOF_");
+            logDetail("replay.inject", { channel: "bash", bytes: composed.text.length });
+            return { kind: "bash", command: `cat <<'${delimiter}'\n${safe}\n${delimiter}` };
+        }
+        logDetail("replay.inject", { channel: "deny", bytes: composed.text.length });
+        return { kind: "deny", reason: composed.text };
+    }
+    /**
+     * The executor handed to a plan: dispatch a step to the proxy that owns its
+     * upstream.
+     *
+     * Rejecting means "could not be run **here**" — which is the only condition
+     * under which a recorded output may stand in. A tool that ran and failed
+     * resolves with its failure as the response, exactly as it would in a session.
+     */
+    executeStep() {
+        return async (step, input) => {
+            const mcp = parseQualifiedName(step.toolName);
+            if (!mcp)
+                throw new Error(`${step.toolName} is not an MCP tool — it can only run in the session`);
+            const result = await this.work.call(mcp.serverName, mcp.toolName, input, this.budgets.stepMs);
+            // Serialize exactly as the proxy records it, or `toolOutputLogic` — which
+            // was authored against that shape — silently derives nothing (§7.2).
+            return serializeCapped(redact(result));
+        };
+    }
+    /**
+     * Where a pinned step's output will arrive from — the proxy's report, or the
+     * hook's `tool_response` (§7.2).
+     *
+     * NOT the same question as {@link reachOf}'s, and conflating them is a silent
+     * bug. `reachOf` answers "may *we* execute this step ourselves", which the
+     * allowlist restricts. This answers "will a `bir-proxy` see this call and
+     * report it", which depends only on whether the server is **wrapped** — a
+     * wrapped server the allowlist excludes is still proxied, still reported, and
+     * still recorded in the proxy's serialization. Threading such a step from the
+     * hook's differently-shaped view would derive nothing at all.
+     */
+    reachFor(state, step) {
+        return reachOf(step.toolName, state.wrapped);
+    }
+    /**
+     * Log a step and remember its verdict, in that order.
+     *
+     * Every driver passes this — direct, divergence recovery and ad-hoc alike — so
+     * there is exactly one place a step's fate is decided, and the console can
+     * never be told something the log does not also say.
+     */
+    observeStep(state) {
+        return (info) => {
+            this.logStep(info);
+            this.recordStep(state, info);
+        };
+    }
+    /** Upsert one step's verdict. Later news about a step replaces earlier news. */
+    recordStep(state, info) {
+        const status = info.outcome === "executed" ? "ok" : info.outcome;
+        if (state.stepResults.size >= MAX_STEP_RESULTS && !state.stepResults.has(info.step.stepIndex)) {
+            return;
+        }
+        const error = info.error
+            ? info.error.length > MAX_STEP_ERROR_CHARS
+                ? `${info.error.slice(0, MAX_STEP_ERROR_CHARS)}…`
+                : info.error
+            : undefined;
+        state.stepResults.set(info.step.stepIndex, {
+            stepIndex: info.step.stepIndex,
+            toolName: info.step.toolName,
+            status,
+            // A stage is only meaningful when something went wrong. `skipped` broke at
+            // the call itself — its tool could not run here.
+            stage: info.stage ?? (status === "skipped" ? "tool_call" : undefined),
+            error,
+            durationMs: info.ms,
+        });
+    }
+    /** The step verdicts, in chain order, for the execution report. */
+    stepResultsOf(state) {
+        if (state.stepResults.size === 0)
+            return undefined;
+        return [...state.stepResults.values()].sort((a, b) => a.stepIndex - b.stepIndex);
+    }
+    logStep(info) {
+        const mcp = parseQualifiedName(info.step.toolName);
+        if (info.outcome === "failed") {
+            logLine("replay.step_failed", {
+                n: info.step.stepIndex,
+                tool: info.step.toolName,
+                stage: info.stage,
+                why: info.stage === "tool_call"
+                    ? "its tool ran and reported an error — the step's work did not happen"
+                    : "the scenario's own logic threw — this step cannot work until it is recalculated",
+                error: info.error,
+            });
+            return;
+        }
+        if (info.outcome === "skipped") {
+            logLine("replay.step_skipped", {
+                n: info.step.stepIndex,
+                tool: info.step.toolName,
+                why: "its tool could not run here and it has no recorded output",
+                error: info.error,
+            });
+            return;
+        }
+        if (info.outcome === "recorded") {
+            logLine("replay.step_recorded", {
+                n: info.step.stepIndex,
+                tool: info.step.toolName,
+                why: "served its recorded output — its tool could not run here",
+                error: info.error,
+            });
+            return;
+        }
+        logLine("replay.step", {
+            n: info.step.stepIndex,
+            tool: mcp?.toolName ?? info.step.toolName,
+            server: mcp?.serverName,
+            ms: info.ms,
+            ok: true,
+            emitted: info.derivedKeys?.join(",") || undefined,
+        });
+    }
+    /** Outcomes only move forward; `not_steered` is the floor (§11.1). */
+    upgrade(state, outcome) {
+        if (OUTCOME_RANK[outcome] > OUTCOME_RANK[state.outcome])
+            state.outcome = outcome;
+    }
+    retire(state, outcome) {
+        if (outcome)
+            this.upgrade(state, outcome);
+        state.retired = true;
+        state.pinned.clear();
+    }
+    withBudget(p, ms, what) {
+        let timer;
+        const budget = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${what} exceeded ${ms}ms`)), ms);
+            timer.unref?.();
+        });
+        return Promise.race([p, budget]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        });
+    }
+}
+//# sourceMappingURL=controller.js.map