@basein/runner 0.2.12 → 0.3.0

package/dist/replay/controller.d.ts

@@ -23,17 +23,160 @@ import { type ExecutionOutcome, type ExecutionStepResult, type FallbackKind, typ
 export declare const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
 /** How long a `/proxy/poll` is held open before it answers empty. */
 export declare const POLL_HOLD_MS = 25000;
+/**
+ * The longest a prompt ever waits for a steer plan's parameters so that its
+ * directive can preview them ({@link ReplayController.settleForPreview}).
+ * `UserPromptSubmit` is on the user's critical path: a preview is worth a
+ * little of it, never the derivation's whole budget.
+ */
+export declare const PREVIEW_SETTLE_MAX_MS = 1200;
 export interface ReplayBudgets {
     /** How long `/session/prompt` waits for the match. */
     matchMs: number;
-    /** How long the first `PreToolUse` waits for derivation. */
+    /** How long `/scenario/run` waits for derivation, which has no hook timeout. */
     deriveMs: number;
-    /** Ceiling on a whole direct plan. */
+    /**
+     * Ceiling on a whole direct plan. 100 s, so that `deriveMs + planMs` plus the
+     * last step's `MIN_STEP_MS` and its logic stays under Claude Code's 2-minute
+     * auto-background of an MCP tool call: a backgrounded `run_scenario` leaves
+     * the model doing the task while this keeps starting its steps.
+     * `BIR_REPLAY_PLAN_BUDGET_MS` (120 000 was the old default; past about
+     * 110 000 a long run may be backgrounded).
+     */
     planMs: number;
     /** Ceiling on one direct `tools/call`. */
     stepMs: number;
+    /**
+     * How long a *hook* waits for derivation: arming inside `UserPromptSubmit`
+     * (whose whole answer, match included, must land within the control server's
+     * prompt deadline) and the first `PreToolUse`. Capped by `deriveMs`.
+     * `BIR_HOOK_DERIVE_BUDGET_MS`.
+     */
+    hookDeriveMs: number;
+    /**
+     * Everything replay does inside one `PreToolUse`: the wait for the
+     * parameters and, on a divergence, executing the rest of the plan. The host
+     * gives the hook 15 s and the control server answers by 12 s whatever
+     * happens, so this stays below both: a step started after the host stopped
+     * waiting is a side effect the model is never told about.
+     * `BIR_PRETOOL_REPLAY_BUDGET_MS`, held at or under
+     * {@link MAX_PRETOOL_REPLAY_MS} whatever is asked.
+     */
+    preToolMs: number;
 }
 export declare const DEFAULT_BUDGETS: ReplayBudgets;
+/**
+ * The most {@link ReplayBudgets.preToolMs} may be: the last step started at the
+ * budget's end still gets its {@link MIN_STEP_MS} and the margin before the
+ * route's deadline answers the host. Past it, a divergence kept starting steps
+ * — writes, unattended — after the model had been told to carry on itself.
+ */
+export declare const MAX_PRETOOL_REPLAY_MS: number;
+/** What the caller's hook knows about its own deadline (see {@link ReplayController.preTool}). */
+export interface PreToolOptions {
+    /**
+     * When the caller answers the host whatever happens (epoch ms). No step is
+     * started later than {@link MIN_STEP_MS} and a margin before it.
+     */
+    answerBy?: number;
+    /**
+     * Aborted once the host has been answered without this call's action — the
+     * route's deadline guard spoke first. No further step is started.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * What the caller knows about how a pinned call ended, beyond its error text
+ * ({@link ReplayController.postTool}). Both optional: without them the text
+ * and the output are read (`pinFailure`).
+ */
+export interface PostToolOptions {
+    /**
+     * The call was sent and never answered — its proxy abandoned it (the
+     * upstream closed or restarted, the host cancelled it) or its answer could
+     * not be delivered. It may or may not have done its work.
+     */
+    uncertain?: boolean;
+    /** The call was never sent: its upstream was already gone. Nothing of it happened. */
+    notSent?: boolean;
+}
+/**
+ * The longest a direct run may take by its budgets, end to end.
+ *
+ * `bir-scenario` gives `/scenario/run` 290 s (`BIR_SCENARIO_RUN_TIMEOUT_MS`),
+ * just under Claude Code's 5-minute idle timeout for an MCP call, and a run
+ * that answers after its client stopped waiting is a replay thrown away with
+ * its steps already done. So the budgets are held to 270 s, and the defaults
+ * sit far below it: 8 s of derivation + 100 s of plan (more only when an
+ * operator sets `BIR_REPLAY_BUDGET_MS` or `BIR_REPLAY_PLAN_BUDGET_MS`) + 12 s
+ * of slack (one last step's 1 s, six 1 s logic bodies, a 5 s margin —
+ * {@link clampDirectRun}) = 120 s.
+ *
+ * Only `/scenario/run` is held to it. `bir replay` (`runAdHoc`) answers the
+ * operator's own command, which no MCP client times out, and keeps the budgets
+ * the environment asked for.
+ */
+export declare const DIRECT_RUN_CEILING_MS = 270000;
+/**
+ * The direct-run budgets, held under {@link DIRECT_RUN_CEILING_MS}.
+ *
+ * The worst case is `deriveMs + planMs` plus what can happen past the plan's
+ * deadline: one last step's {@link MIN_STEP_MS}, {@link LOGIC_BODIES_OUTSIDE_PLAN}
+ * logic bodies, and the margin. `stepMs` never adds to it — each step is
+ * clipped to what the plan has left. Budgets that would pass the ceiling are
+ * brought under it — the derivation wait first to {@link MAX_DIRECT_DERIVE_MS},
+ * then the plan — and `clamped` says what changed, for the log.
+ */
+export declare function clampDirectRun(budgets: ReplayBudgets, logicMs?: number): {
+    budgets: ReplayBudgets;
+    clamped?: {
+        deriveMs?: [number, number];
+        planMs?: [number, number];
+    };
+};
+/**
+ * What `/scenario/run` answers — {@link ReplayController.runArmed}'s result,
+ * sent as the response body as it is. `bir-scenario` renders it (bin/
+ * bir-scenario.ts, `toolResult`); these are the shapes it can meet:
+ *
+ *  - **ok** — the plan ran to its end: `{ ok: true, text, responseModel, steps,
+ *    partial: false }`. `text` is the bundle; `responseModel` what the
+ *    scenario's own logic built from it (`{}` when it has none).
+ *  - **partial** — the plan stopped part-way after running steps here: `{ ok:
+ *    true, text, responseModel: {}, steps, partial }`. `text` opens with the
+ *    hand-over note (text beginning `[BaseInstRunner calculated replay]`) and
+ *    carries the bundle of what ran below it. `partial` is true only when the
+ *    time budget, or the caller leaving, cut it short; a step that broke says
+ *    so in the note instead.
+ *  - **hand-over note** — nothing ran here, and the model does the task: `{ ok:
+ *    false, why: <note>, note: true }`. `why` is written for the model and
+ *    opens with `[BaseInstRunner calculated replay]`; `note` marks it so, for
+ *    a client that should pass it through rather than say something of its own.
+ *  - **no_plan** — nothing is armed for this call, or the plan retired before
+ *    it ran: `{ ok: false, why: "no_plan" }`. The common case, never an error.
+ *  - **not run** — the run itself threw, or the scenario's logic did: `{ ok:
+ *    false, why }` with a short reason for the log (`"not_ready"`, `"the
+ *    scenario could not be run"`), never written for the model.
+ *  - **already running** — a second `runArmed` for a plan that is running is
+ *    handed the first one's promise and so the first one's result, whichever
+ *    shape it takes: the plan is never driven twice. (At HTTP, the control
+ *    server answers a second `/scenario/run` for a running plan itself, with
+ *    `{ ok: false, why: <its ALREADY_RUNNING text> }`, before it reaches here.)
+ *
+ * Only `ok: true` results carry `text`; only `ok: false` ones carry `why`.
+ */
+export interface RunArmedResult {
+    ok: boolean;
+    why?: string;
+    /** Set on a hand-over: `why` is a note written for the model, not a reason for the log. */
+    note?: boolean;
+    text?: string;
+    responseModel?: Record<string, unknown>;
+    steps?: number;
+    partial?: boolean;
+}
+/** The `why` of a {@link RunArmedResult} with nothing armed to run. */
+export declare const RUN_NO_PLAN = "no_plan";
 export interface ReplayOptions {
     /** On unless `BIR_REPLAY=0`. Everything here is inert when false. */
     enabled: boolean;
@@ -65,6 +208,15 @@ export interface ReplayOptions {
     fetchImpl?: typeof fetch;
     /** Anthropic key for derivation. Absent → recorded sample values, free. */
     apiKey?: string;
+    /**
+     * Let a step whose tool could not be *sent* here — a built-in during
+     * divergence recovery, a server with no proxy — stand on its recorded output,
+     * labelled `(recorded)`, instead of stopping the plan there. Off by default:
+     * a recorded "INSERT 0 1" is last week's write, not this turn's
+     * (plan.ts, `DriveOptions`). `BIR_REPLAY_RECORDED_OUTPUTS=1` when omitted.
+     * Never applies to a step that was sent and failed or did not answer.
+     */
+    recordedFallback?: boolean;
     /**
      * Intent matching in the ReAct loop (fallbk.md §Runner 4): while the model is
      * driving, each tool call's reasoning is matched against scenario intents.
@@ -113,6 +265,14 @@ interface PinnedCall {
     toolName: string;
     /** When it was pinned — a steered step's duration is measured across hooks. */
     pinnedAt: number;
+    /**
+     * When the host said the call finished (`PostToolUse`), if the control
+     * server told us ({@link ReplayController.hostCompleted}). A wrapped step
+     * threads only when the proxy's report lands, which can be up to the
+     * server's 1.5 s fallback later: until then the *next* call is sequential,
+     * not concurrent, and is worth waiting for.
+     */
+    hostDoneAt?: number;
 }
 /**
  * Per-run replay state. Created on every match — including declined ones,
@@ -130,6 +290,13 @@ export interface ReplayState {
     plan?: ScenarioReplayPlan;
     /** `tool_use_id` → the step it pinned. */
     pinned: Map<string, PinnedCall>;
+    /**
+     * Pins still in flight when the plan handed over because another call ran
+     * beside them. The plan is retired, but those calls were pinned (and
+     * approved) under it: their results are still read when they land, so the
+     * step's verdict is recorded and the ledger counts work that happened.
+     */
+    lingering?: Map<string, PinnedCall>;
     outcome: ExecutionOutcome;
     deriveCostUsd: number;
     fallbackCostUsd: number;
@@ -214,6 +381,25 @@ export interface ReplayState {
      */
     retiredMark?: unknown;
     retiredAt?: number;
+    /**
+     * The one `/scenario/run` executing this plan. A second call — a retry after
+     * a client timeout, a double call — waits for its answer rather than driving
+     * the same cursor a second time.
+     */
+    running?: Promise<RunArmedResult>;
+    /** The model called `run_scenario` for this plan (its `PreToolUse` was seen). */
+    directRequested?: boolean;
+    /**
+     * The direct run's caller went away mid-run — Esc on `run_scenario`, or its
+     * client timing out. The turn it cut short is no measurement of the task, so
+     * the execution report says `measured: false`.
+     */
+    callerCancelled?: boolean;
+    /**
+     * The derivation is the service's to answer (no key here), so waiting on it
+     * is waiting on the service, and obeys its breaker (util/service-health.ts).
+     */
+    deriveOnService?: boolean;
 }
 /**
  * Why a match did not arm. One code per gate of the ladder, so the caller can
@@ -249,9 +435,26 @@ export type PreToolAction =
 export declare class ReplayController {
     readonly enabled: boolean;
     readonly work: ProxyWorkQueue;
+    /** The budgets every path runs on, a direct run's held under {@link DIRECT_RUN_CEILING_MS}. */
     readonly budgets: ReplayBudgets;
+    /**
+     * `bir replay`'s derivation wait and plan budget: what the environment asked
+     * for, unclamped — no MCP client times that run out (see
+     * {@link DIRECT_RUN_CEILING_MS}).
+     */
+    readonly adHocBudgets: Readonly<Pick<ReplayBudgets, "deriveMs" | "planMs">>;
     readonly intentMatch: IntentMatchOptions;
     private readonly opts;
+    /** See {@link ReplayOptions.recordedFallback}. */
+    private readonly recordedFallback;
+    /** Calls waiting for a plan's pins to change (see `awaitPins`). */
+    private readonly pinWaiters;
+    /**
+     * Set the first time the control server reports a host completion
+     * ({@link hostCompleted}). From then on a pin the host has not finished is a
+     * call really running beside the next one, and nothing waits for it.
+     */
+    private hostSignals;
     constructor(opts: ReplayOptions);
     /**
      * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
@@ -279,8 +482,39 @@ export declare class ReplayController {
      * up with a denominator nobody measured.
      */
     arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext): Promise<ReplayState>;
-    /** The directive to inject via `additionalContext`, or undefined when declined. */
-    directiveFor(state: ReplayState): string | undefined;
+    /**
+     * The directive to inject via `additionalContext`, or undefined when declined.
+     *
+     * A steer directive previews each step's arguments (plan.ts,
+     * `previewArguments`), which can take up to {@link PREVIEW_BUDGET_MS}.
+     * `previewMs` — the time the caller's hook has left — lowers that bound,
+     * never raises it; under ~10 ms nothing is previewed and the directive keeps
+     * its old wording.
+     */
+    directiveFor(state: ReplayState, opts?: {
+        previewMs?: number;
+    }): string | undefined;
+    /**
+     * Give a steer plan's parameters a short, bounded chance to settle before its
+     * directive is written, so {@link directiveFor} can show the arguments the
+     * steps run with. Resolves true when they are settled.
+     *
+     * Without it a derivation the service answers — nearly every one, since a
+     * signed-in runner has no key of its own — has never answered by the time
+     * `arm` returns (it waits one turn of the loop, on purpose), the directive
+     * says "the system supplies the exact arguments", the model writes a guessed
+     * command, the pin guard declines it, and the plan retires having run
+     * nothing.
+     *
+     * Only for the steps the pin guard holds to their exact shape — a shell
+     * command, a file write (control/pin-guard.ts) — and never longer than
+     * {@link PREVIEW_SETTLE_MAX_MS} or `budgetMs`, whichever is less: the caller
+     * passes what its prompt hook has left, less what the preview itself needs.
+     * Not at all while the service is cooling down. A late answer is not an
+     * overrun of anything, so it marks nothing against the service. `arm`
+     * itself still never waits (integ-replay R2).
+     */
+    settleForPreview(state: ReplayState, budgetMs: number): Promise<boolean>;
     /**
      * A hand-over note not yet delivered, claimed for delivery (fallbk.md D4).
      * Returns it once and marks it delivered; undefined when there is none.
@@ -298,10 +532,46 @@ export declare class ReplayController {
      * 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.
+     *
+     * `hook` is optional and only ever tightens the work: `answerBy` lowers the
+     * deadline to the caller's own, and `signal` stops a divergence from
+     * starting another step once the host has been answered without it.
      */
     preTool(state: ReplayState, toolName: string, toolUseId: string, 
     /** The call's `tool_input`: whether a `Bash` call is only `bir` is read from it (D13). */
-    toolInput?: unknown): Promise<PreToolAction>;
+    toolInput?: unknown, hook?: PreToolOptions): Promise<PreToolAction>;
+    /**
+     * A call arrived while another pinned call's output has not threaded yet
+     * (see `preTool`). The plan stops here rather than pin a step twice.
+     */
+    private concurrentCall;
+    /**
+     * Wait until the plan's outstanding pins thread, or until waiting is no
+     * longer worth it (see `preTool`, ONE CALL AT A TIME).
+     *
+     * Always bounded by the hook's `deadline`. Within it:
+     *  - every pin finished by the host ({@link hostCompleted}): until
+     *    {@link PIN_THREAD_WAIT_MS} after the last of them finished — the
+     *    server's fallback has threaded it by then, if anything will;
+     *  - the server is known to report host completions and a pin is not
+     *    finished: a call really running beside this one, which may run for
+     *    minutes, so only {@link HOST_RACE_MS} in case its completion is racing
+     *    this hook;
+     *  - otherwise (a server that reports nothing): {@link PIN_THREAD_WAIT_MS}.
+     */
+    private awaitPins;
+    /** Resolves on the next change to a plan's pins, or after `ms`. */
+    private pinChange;
+    /** Wake every call waiting on this plan's pins. */
+    private notifyPins;
+    /**
+     * The host finished a call (`PostToolUse` / `PostToolUseFailure`) — whether
+     * or not its output has threaded yet. The control server calls this for
+     * every pinned call; it is what tells the model's next, sequential call
+     * apart from one running beside a pin (see `awaitPins`). Optional: without
+     * it every such call waits the bounded {@link PIN_THREAD_WAIT_MS}.
+     */
+    hostCompleted(state: ReplayState | undefined, toolUseId: string): void;
     /**
      * `PostToolUse` for a call this plan pinned.
      *
@@ -309,26 +579,60 @@ export declare class ReplayController {
      * 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: ReplayState, toolUseId: string, output: string): boolean;
+     *
+     * `failed` is the host's verdict that the call failed — `PostToolUseFailure`,
+     * or a proxy report with `isError` — with its error text when there is one.
+     * It outranks anything read from `output`: a built-in's response is Claude
+     * Code's rendering and is never judged here, so for an `Edit` whose
+     * `old_string` moved since the recording this is the only word there is. A
+     * step that failed must never thread as if it worked: the next step would be
+     * pinned, and auto-approved, on top of it.
+     *
+     * Not every failure is one. A call its proxy *abandoned* — the upstream
+     * closed, restarted or was cancelled mid-call, reported with `isError` and
+     * no result — may well have done its work, and so may one the host says
+     * timed out or was interrupted: the note says "may or may not have
+     * completed", never "failed", or the model runs a write a second time
+     * ({@link pinFailure}). `how` lets the caller say so outright.
+     */
+    postTool(state: ReplayState, toolUseId: string, output: string, failed?: string, how?: PostToolOptions): boolean;
+    /**
+     * The result of a call pinned under a plan that has since handed over
+     * because another call ran beside it (`concurrentCall`). Nothing threads —
+     * the plan is retired and the model is doing the rest — but the step's
+     * verdict is recorded, and a step that did its work is counted: the outcome
+     * moves from `failed` to `fell_back` when it is the first that did.
+     */
+    private lateThread;
     /** Whether a pinned call's output is threaded from the proxy's report (§7.2). */
     threadsFromProxy(state: ReplayState, toolUseId: string): boolean;
-    /** True when this call belongs to the active plan. */
+    /**
+     * True when this call belongs to the plan: pinned by it and not yet
+     * threaded — including a pin still in flight when the plan handed over, so
+     * its result still reaches `postTool` (see `lateThread`).
+     */
     isPinned(state: ReplayState, toolUseId: string): boolean;
     /**
      * `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.
+     *
+     * `signal` aborts when the caller is gone — `bir-scenario`'s request was
+     * cancelled (Esc) or timed out — so no further step is started (C4). The
+     * worst case this can take is `deriveMs + planMs` plus one step's
+     * `MIN_STEP_MS`, six logic bodies at their full limit and a 5 s margin —
+     * 120 s by default, more only for a plan budget an operator raised
+     * ({@link clampDirectRun}) — which `bir-scenario`'s own timeout (290 s) must
+     * exceed, and which is held under {@link DIRECT_RUN_CEILING_MS} whatever the
+     * environment asks for. That bound counts every body at its limit; a run
+     * that does not stall ends well inside its plan budget.
+     *
+     * One run per plan: a second call while the first is running gets the first
+     * one's answer, never a second execution of the same steps.
      */
-    runArmed(state: ReplayState): Promise<{
-        ok: boolean;
-        why?: string;
-        text?: string;
-        responseModel?: Record<string, unknown>;
-        steps?: number;
-        partial?: boolean;
-    }>;
+    runArmed(state: ReplayState, signal?: AbortSignal): Promise<RunArmedResult>;
+    private runArmedOnce;
     /**
      * Build the execution report for a sealed run, or undefined when there is
      * nothing to report.
@@ -383,6 +687,13 @@ export declare class ReplayController {
             outcome: string;
             ms: number;
         }>;
+        /** Where the run stopped short of its end, and why, when it did. */
+        stopped?: {
+            step: number;
+            tool: string;
+            reason: string;
+            error?: string;
+        };
     }>;
     /** Release every parked poller. Called at control-server shutdown. */
     close(): void;
@@ -408,8 +719,18 @@ export declare class ReplayController {
      *
      * The plan is retired first: whatever happens next, this turn neither steers
      * nor re-injects again.
+     *
+     * This runs inside the diverging call's `PreToolUse`, so `deadline` bounds
+     * it: no step is started after it, and none is waited on past it. The bundle
+     * then says exactly what ran, and hands the rest over.
      */
     private diverge;
+    /**
+     * The note for a divergence bundle that stopped at a step, recorded as this
+     * plan's hand-over (already delivered — it goes out with the bundle), so the
+     * model's own work from here is recorded as a fragment.
+     */
+    private stopNote;
     /**
      * Hand the rest of the task to the model (fallbk.md D4/D5).
      *
@@ -431,11 +752,40 @@ export declare class ReplayController {
      * 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.
+     * A tool that ran and failed resolves with its failure as the response,
+     * exactly as it would in a session. A rejection is a {@link StepRunError}
+     * saying what happened to the call — not sent, sent and unanswered, or
+     * refused — because the model is told differently about each (plan.ts).
+     *
+     * `deadline` is the whole run's: no step is waited on past it (but each gets
+     * at least {@link MIN_STEP_MS}). `adHoc` is `bir replay`, which the operator
+     * asked for by id and which the allowlist does not gate.
      */
     private executeStep;
+    /** Where recorded outputs come from, when they may stand in at all. */
+    private recordedSource;
+    /**
+     * Wait for a plan's parameters within `budgetMs`, then judge whether the plan
+     * may run on them. Never throws.
+     *
+     * Out of time, the parameters settle without the derivation
+     * (`useFallbackParams`: settings at their samples, targets null) — never on
+     * `{}` — and the plan runs only if it needs no target it was not given. A
+     * `paramsLogic` that throws, or a value too dangerous to template into a
+     * command (safety.ts), stops it. `adHoc` keeps `bir replay`'s contract: the
+     * operator named the scenario, so neither judgement applies.
+     */
+    private readyFor;
+    /**
+     * Wait for something the derivation decides, within `budgetMs`. Resolves
+     * undefined when the time ran out.
+     *
+     * When the service is the one deriving, this is a service wait on a hot path
+     * (C1): it does not wait at all while the service is cooling down, and an
+     * overrun is reported to the breaker so the next hook does not wait either.
+     * Even a zero wait lets an answer that has already arrived through.
+     */
+    private waitDerivation;
     /**
      * Where a pinned step's output will arrive from — the proxy's report, or the
      * hook's `tool_response` (§7.2).
@@ -465,7 +815,6 @@ export declare class ReplayController {
     /** Outcomes only move forward; `not_steered` is the floor (§11.1). */
     private upgrade;
     private retire;
-    private withBudget;
 }
 /** The subset of `RunMatch` replay consumes. Structural, so tests need no recorder. */
 export interface RunMatchLike {