@basein/runner 0.2.12 → 0.3.0

package/dist/replay/logic.d.ts

@@ -2,8 +2,7 @@
  * logic — the four stored-JS evaluators (docs/calculatedReplay.md §9).
  *
  * A calculated scenario carries JavaScript function *bodies*, one per hook
- * point, each ending in `return { … }`. They are compiled with `new Function`
- * and run here.
+ * point, each ending in `return { … }`. They are compiled and run here.
  *
  * PORTED FROM THE SERVICE, DELIBERATELY. BaseIn's `src/scenarios/logic.ts` is
  * the copy the service itself evaluates in a dry replay, so it is the one that
@@ -12,18 +11,71 @@
  * another way here — an untestable difference. Argument order and the
  * plain-object guard both match the service exactly.
  *
- * THERE IS NO SANDBOX, and the doc says so plainly (§13.1). A `new Function`
- * body gets its declared arguments and the global scope: `require`/`import` are
- * unreachable under ESM, but `fetch`, `process` and `globalThis` are not. What
- * makes this acceptable is provenance, not containment — the payload arrives
- * only in an authenticated response from the configured `BIR_AUTH_URL`,
- * describing the caller's own recorded runs — and replay is opt-in for exactly
- * this reason.
+ * THERE IS NO SANDBOX, and the doc says so plainly (§13.1). A body gets its
+ * declared arguments and the global scope: `require`/`import` are unreachable
+ * under ESM, but `fetch`, `process` and `globalThis` are not. What makes this
+ * acceptable is provenance, not containment — the payload arrives only in an
+ * authenticated response from the configured `BIR_AUTH_URL`, describing the
+ * caller's own recorded runs — and replay is opt-in for exactly this reason.
+ *
+ * THERE IS A CLOCK. Every body runs inside the one process that answers every
+ * hook of the project, on its only thread. The service ran the same body under
+ * a time limit — but on the *recording's* values, and a regex written against a
+ * 2 KB output can backtrack for minutes on a 2 MB one, or a hand edit saved with
+ * `--force` can loop. Without a limit that froze the event loop, and every
+ * `PreToolUse`, `PostToolUse` and prompt hook of every session in the project
+ * waited out its timeout on every call until someone killed `bir-hooks`.
+ *
+ * So each body runs through `vm.Script#runInThisContext` with a `timeout`
+ * ({@link logicTimeoutMs}). *This* context, not a new one: the body keeps the
+ * realm, the globals and the argument objects it always had — `instanceof
+ * Array` still holds for a value `JSON.parse` made outside, a body that writes
+ * into `respParams` still writes into the plan's own — so the only behaviour
+ * that changes is that a runaway body throws instead of hanging. That throw is
+ * an ordinary logic failure, and the plan hands over at that step. The limit
+ * covers synchronous work, which is all a body returning a plain object does;
+ * it does not bound memory.
+ *
+ * WHAT THE CLOCK DOES NOT COVER. `runInThisContext`'s timeout ends when the
+ * body returns. A continuation the body *queues* — `Promise.resolve().then(…)`,
+ * `queueMicrotask`, `setTimeout` — runs afterwards, outside it, on the same
+ * thread, and nothing here bounds it. A body that returns a promise is refused
+ * (it is no plain object, and it is the shape such work comes in); one that
+ * queues work and still returns a plain object is not caught. Bounding that
+ * would take a separate context (`microtaskMode: "afterEvaluate"`), which gives
+ * up the realm and the shared argument objects this relies on. The threat the
+ * clock answers — a backtracking regex, a loop saved with `--force` — is
+ * synchronous; a body written to get around it already has the process (see
+ * THERE IS NO SANDBOX above).
+ */
+/** How long one logic body may run before it is stopped. */
+export declare const DEFAULT_LOGIC_TIMEOUT_MS = 1000;
+/**
+ * The most `BIR_LOGIC_TIMEOUT_MS` may ask for. A body runs on the only thread
+ * of the process that answers every hook of the project, so each second it is
+ * allowed is a second every session's hooks can stand still; and a direct run
+ * adds a few of them past its own deadline (controller.ts, `clampDirectRun`).
  */
+export declare const MAX_LOGIC_TIMEOUT_MS = 10000;
+/** `BIR_LOGIC_TIMEOUT_MS` (at most {@link MAX_LOGIC_TIMEOUT_MS}), or {@link DEFAULT_LOGIC_TIMEOUT_MS}. */
+export declare function logicTimeoutMs(): number;
+/** A body stopped by its time limit — as opposed to one that threw on its own. */
+export declare class LogicTimeoutError extends Error {
+    constructor(label: string, timeoutMs: number);
+}
+/** Per-call options for an evaluator. */
+export interface LogicRunOptions {
+    /**
+     * A tighter limit than {@link logicTimeoutMs} for this one evaluation — for
+     * a look-ahead nobody waits on the answer of, such as the directive's
+     * preview of a step's arguments. Never raises the limit.
+     */
+    timeoutMs?: number;
+}
 /** Transform the derived parameters once, before any step runs. */
 export declare function evalParamsLogic(code: string, parameters: Record<string, unknown>, intent: string): Record<string, unknown>;
 /** Derive one step's tool input from params, intent and the accumulated respParams. */
-export declare function evalToolInputLogic(code: string, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>): Record<string, unknown>;
+export declare function evalToolInputLogic(code: string, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>, opts?: LogicRunOptions): Record<string, unknown>;
 /** Extract keys from a step's real output, to merge into respParams for later steps. */
 export declare function evalToolOutputLogic(code: string, toolOutput: string, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>): Record<string, unknown>;
 /** Build the final response model from everything the steps accumulated. */

package/dist/replay/logic.js

@@ -2,8 +2,7 @@
  * logic — the four stored-JS evaluators (docs/calculatedReplay.md §9).
  *
  * A calculated scenario carries JavaScript function *bodies*, one per hook
- * point, each ending in `return { … }`. They are compiled with `new Function`
- * and run here.
+ * point, each ending in `return { … }`. They are compiled and run here.
  *
  * PORTED FROM THE SERVICE, DELIBERATELY. BaseIn's `src/scenarios/logic.ts` is
  * the copy the service itself evaluates in a dry replay, so it is the one that
@@ -12,40 +11,152 @@
  * another way here — an untestable difference. Argument order and the
  * plain-object guard both match the service exactly.
  *
- * THERE IS NO SANDBOX, and the doc says so plainly (§13.1). A `new Function`
- * body gets its declared arguments and the global scope: `require`/`import` are
- * unreachable under ESM, but `fetch`, `process` and `globalThis` are not. What
- * makes this acceptable is provenance, not containment — the payload arrives
- * only in an authenticated response from the configured `BIR_AUTH_URL`,
- * describing the caller's own recorded runs — and replay is opt-in for exactly
- * this reason.
+ * THERE IS NO SANDBOX, and the doc says so plainly (§13.1). A body gets its
+ * declared arguments and the global scope: `require`/`import` are unreachable
+ * under ESM, but `fetch`, `process` and `globalThis` are not. What makes this
+ * acceptable is provenance, not containment — the payload arrives only in an
+ * authenticated response from the configured `BIR_AUTH_URL`, describing the
+ * caller's own recorded runs — and replay is opt-in for exactly this reason.
+ *
+ * THERE IS A CLOCK. Every body runs inside the one process that answers every
+ * hook of the project, on its only thread. The service ran the same body under
+ * a time limit — but on the *recording's* values, and a regex written against a
+ * 2 KB output can backtrack for minutes on a 2 MB one, or a hand edit saved with
+ * `--force` can loop. Without a limit that froze the event loop, and every
+ * `PreToolUse`, `PostToolUse` and prompt hook of every session in the project
+ * waited out its timeout on every call until someone killed `bir-hooks`.
+ *
+ * So each body runs through `vm.Script#runInThisContext` with a `timeout`
+ * ({@link logicTimeoutMs}). *This* context, not a new one: the body keeps the
+ * realm, the globals and the argument objects it always had — `instanceof
+ * Array` still holds for a value `JSON.parse` made outside, a body that writes
+ * into `respParams` still writes into the plan's own — so the only behaviour
+ * that changes is that a runaway body throws instead of hanging. That throw is
+ * an ordinary logic failure, and the plan hands over at that step. The limit
+ * covers synchronous work, which is all a body returning a plain object does;
+ * it does not bound memory.
+ *
+ * WHAT THE CLOCK DOES NOT COVER. `runInThisContext`'s timeout ends when the
+ * body returns. A continuation the body *queues* — `Promise.resolve().then(…)`,
+ * `queueMicrotask`, `setTimeout` — runs afterwards, outside it, on the same
+ * thread, and nothing here bounds it. A body that returns a promise is refused
+ * (it is no plain object, and it is the shape such work comes in); one that
+ * queues work and still returns a plain object is not caught. Bounding that
+ * would take a separate context (`microtaskMode: "afterEvaluate"`), which gives
+ * up the realm and the shared argument objects this relies on. The threat the
+ * clock answers — a backtracking regex, a loop saved with `--force` — is
+ * synchronous; a body written to get around it already has the process (see
+ * THERE IS NO SANDBOX above).
+ */
+import { Script } from "node:vm";
+/** How long one logic body may run before it is stopped. */
+export const DEFAULT_LOGIC_TIMEOUT_MS = 1_000;
+/**
+ * The most `BIR_LOGIC_TIMEOUT_MS` may ask for. A body runs on the only thread
+ * of the process that answers every hook of the project, so each second it is
+ * allowed is a second every session's hooks can stand still; and a direct run
+ * adds a few of them past its own deadline (controller.ts, `clampDirectRun`).
+ */
+export const MAX_LOGIC_TIMEOUT_MS = 10_000;
+/** `BIR_LOGIC_TIMEOUT_MS` (at most {@link MAX_LOGIC_TIMEOUT_MS}), or {@link DEFAULT_LOGIC_TIMEOUT_MS}. */
+export function logicTimeoutMs() {
+    const n = Number(process.env.BIR_LOGIC_TIMEOUT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.min(n, MAX_LOGIC_TIMEOUT_MS) : DEFAULT_LOGIC_TIMEOUT_MS;
+}
+/** A body stopped by its time limit — as opposed to one that threw on its own. */
+export class LogicTimeoutError extends Error {
+    constructor(label, timeoutMs) {
+        super(`${label} ran longer than ${timeoutMs} ms and was stopped`);
+        this.name = "LogicTimeoutError";
+    }
+}
+/**
+ * Where a call's arguments wait for the script to pick them up. Set and cleared
+ * around one synchronous evaluation, so no two calls can ever see each other's.
  */
+const ARGS_SLOT = "__bir_logic_args__";
+/** Compiled bodies, by argument list and source. A plan evaluates each many times. */
+const compiled = new Map();
+const MAX_COMPILED = 256;
+function compile(argNames, code) {
+    const key = `${argNames.join(",")}\u0000${code}`;
+    const hit = compiled.get(key);
+    if (hit)
+        return hit;
+    // Parsed on its own first, exactly as it always was: a body that is not
+    // valid JavaScript fails with the same SyntaxError as before, and one that
+    // tries to close the wrapper below early cannot parse at all.
+    new Function(...argNames, code);
+    const script = new Script(`(function(){var __bir_a=globalThis[${JSON.stringify(ARGS_SLOT)}];` +
+        `return (function(${argNames.join(",")}){\n${code}\n}).apply(this,__bir_a);}).call(this)`, { filename: "bir-scenario-logic.js" });
+    if (compiled.size >= MAX_COMPILED)
+        compiled.clear();
+    compiled.set(key, script);
+    return script;
+}
+/** Run one body with `args`, under the time limit. Throws what the body throws. */
+function run(label, argNames, code, args, opts = {}) {
+    const script = compile(argNames, code);
+    const slot = globalThis;
+    const previous = slot[ARGS_SLOT];
+    slot[ARGS_SLOT] = args;
+    const asked = opts.timeoutMs;
+    const timeout = typeof asked === "number" && Number.isFinite(asked) && asked > 0
+        ? Math.max(1, Math.min(Math.floor(asked), logicTimeoutMs()))
+        : logicTimeoutMs();
+    try {
+        return script.runInThisContext({ timeout, displayErrors: false });
+    }
+    catch (err) {
+        if (err?.code === "ERR_SCRIPT_EXECUTION_TIMEOUT") {
+            throw new LogicTimeoutError(label, timeout);
+        }
+        throw err;
+    }
+    finally {
+        if (previous === undefined)
+            delete slot[ARGS_SLOT];
+        else
+            slot[ARGS_SLOT] = previous;
+    }
+}
 /** Every logic body must return a plain object; anything else is a bug upstream. */
 function assertPlainObject(result, label) {
     if (typeof result !== "object" || result === null || Array.isArray(result)) {
         throw new Error(`${label} must return a plain object`);
     }
+    // A promise is an object too, and used to pass. It is also the one shape of
+    // body whose work outlives its clock: what it queues runs after the time
+    // limit has stopped counting (see the file comment).
+    if (typeof result.then === "function") {
+        throw new Error(`${label} must return a plain object, not a promise`);
+    }
     return result;
 }
 /** Transform the derived parameters once, before any step runs. */
 export function evalParamsLogic(code, parameters, intent) {
-    const fn = new Function("parameters", "intent", code);
-    return assertPlainObject(fn(parameters, intent), "paramsLogic");
+    return assertPlainObject(run("paramsLogic", ["parameters", "intent"], code, [parameters, intent]), "paramsLogic");
 }
 /** Derive one step's tool input from params, intent and the accumulated respParams. */
-export function evalToolInputLogic(code, parameters, intent, respParams = {}) {
-    const fn = new Function("parameters", "intent", "respParams", code);
-    return assertPlainObject(fn(parameters, intent, respParams), "toolInputLogic");
+export function evalToolInputLogic(code, parameters, intent, respParams = {}, opts) {
+    return assertPlainObject(run("toolInputLogic", ["parameters", "intent", "respParams"], code, [parameters, intent, respParams], opts), "toolInputLogic");
 }
 /** Extract keys from a step's real output, to merge into respParams for later steps. */
 export function evalToolOutputLogic(code, toolOutput, parameters, intent, respParams = {}) {
-    const fn = new Function("toolOutput", "parameters", "intent", "respParams", code);
-    return assertPlainObject(fn(toolOutput, parameters, intent, respParams), "toolOutputLogic");
+    return assertPlainObject(run("toolOutputLogic", ["toolOutput", "parameters", "intent", "respParams"], code, [
+        toolOutput,
+        parameters,
+        intent,
+        respParams,
+    ]), "toolOutputLogic");
 }
 /** Build the final response model from everything the steps accumulated. */
 export function evalResponseParamsLogic(code, respParams, parameters, intent) {
-    const fn = new Function("respParams", "parameters", "intent", code);
-    return assertPlainObject(fn(respParams, parameters, intent), "responseParamsLogic");
+    return assertPlainObject(run("responseParamsLogic", ["respParams", "parameters", "intent"], code, [
+        respParams,
+        parameters,
+        intent,
+    ]), "responseParamsLogic");
 }
 /**
  * The two mapping bodies of a call (segmented.md R-CALL-20).
@@ -57,11 +168,18 @@ export function evalResponseParamsLogic(code, respParams, parameters, intent) {
  * two of them.
  */
 export function evalParamMapLogic(code, parameters, intent, respParams = {}) {
-    const fn = new Function("parameters", "intent", "respParams", code);
-    return assertPlainObject(fn(parameters, intent, respParams), "paramMapLogic");
+    return assertPlainObject(run("paramMapLogic", ["parameters", "intent", "respParams"], code, [
+        parameters,
+        intent,
+        respParams,
+    ]), "paramMapLogic");
 }
 export function evalResultMapLogic(code, out, parameters, intent, respParams = {}) {
-    const fn = new Function("out", "parameters", "intent", "respParams", code);
-    return assertPlainObject(fn(out, parameters, intent, respParams), "resultMapLogic");
+    return assertPlainObject(run("resultMapLogic", ["out", "parameters", "intent", "respParams"], code, [
+        out,
+        parameters,
+        intent,
+        respParams,
+    ]), "resultMapLogic");
 }
 //# sourceMappingURL=logic.js.map

package/dist/replay/plan.d.ts

@@ -22,15 +22,61 @@
  */
 import { type FlatEntry } from "./flatten.js";
 import type { ReplayMode } from "./coverage.js";
-import type { ExecutionStage, FallbackKind, SerializedScenario, SerializedScenarioStep } from "./types.js";
+import type { HandoverStopReason } from "./handover.js";
+import type { ExecutionStage, FallbackKind, ParamsSchema, SerializedScenario, SerializedScenarioStep } from "./types.js";
 /**
  * Runs one step's tool and returns its output as a string.
  *
  * Resolving with a failure message is a *result* — a tool that ran and failed.
- * Rejecting means the step could not be **run here at all**, which is the only
- * case a recorded output may stand in for.
+ * Rejecting means the step produced **no result here**: it could not be sent
+ * (`not_run`), it was sent and never answered (`uncertain`), or the upstream
+ * refused it (`failed`). Reject with a {@link StepRunError} to say which; any
+ * other rejection reads as `not_run`, the old contract.
  */
 export type ExecuteStep = (step: SerializedScenarioStep, input: Record<string, unknown>) => Promise<string>;
+/** Why a step's call produced no result. */
+export type StepRejection = "not_run" | "uncertain" | "failed";
+/** A rejection from an {@link ExecuteStep} that says what happened to the call. */
+export declare class StepRunError extends Error {
+    readonly rejection: StepRejection;
+    constructor(message: string, rejection: StepRejection);
+}
+/** What a rejection means for the step — see {@link ExecuteStep}. */
+export declare function rejectionOf(err: unknown): StepRejection;
+/**
+ * How a plan driver treats the steps it cannot get a real result for.
+ *
+ * THE RULE: a result shown to the model is a result that happened, here, now.
+ * A step that could not run, did not answer or was refused is never replaced by
+ * the output recorded for it last week — "INSERT 0 1" under a header that says
+ * the work is done is how a user is told a write happened that did not. The run
+ * stops at that step, the steps before it are shown as they are, and the rest
+ * of the task is handed back with a note that names the step and what may be
+ * assumed about it (fallbk.md).
+ */
+export interface DriveOptions {
+    /**
+     * Stop at the first step that breaks — its logic throws, or its tool reports
+     * an error — instead of threading the error on (fallbk.md §Runner 3). A step
+     * after a failed one computes on a result that does not exist. Off keeps the
+     * old contract: a logic throw propagates, a tool error is threaded and
+     * counted. A step with *no* result stops the run either way.
+     */
+    stopOnFailure?: boolean;
+    /**
+     * Serve the recorded output of a step whose tool could not be *sent* here
+     * (`not_run`: a built-in, a server with no proxy), labelled `(recorded)`.
+     * `BIR_REPLAY_RECORDED_OUTPUTS=1`, and `bir replay`. Never for a step that
+     * was sent and failed or did not answer.
+     */
+    recordedFallback?: boolean;
+    /**
+     * The caller went away — `bir-scenario`'s request was cancelled or timed out
+     * (C4). No further step is *started*; one already sent runs to its own end,
+     * so what the run reports about it is the truth.
+     */
+    signal?: AbortSignal;
+}
 /**
  * Supplies a step's recorded output when its tool cannot run here (§8.1).
  *
@@ -69,10 +115,30 @@ export interface StepInfo {
     toolMissing?: boolean;
 }
 export type StepObserver = (info: StepInfo) => void;
+/**
+ * One step's input logic, evaluated only to show its arguments, runs no longer
+ * than this (nor than `logicTimeoutMs()`).
+ *
+ * The limit is wall-clock time (a `vm` timeout), so it must tolerate a busy
+ * machine: with ten CPU-bound processes on eight cores, a trivial
+ * `return { command: 'ls ' + parameters.x }` took up to ~170 ms, and a 50 ms
+ * limit stopped more than half of them — ending the preview, and every
+ * argument with it, whenever the machine was loaded. At 250 ms none was
+ * stopped. A body stopped at this limit really is slow, and ends the preview.
+ */
+export declare const PREVIEW_LOGIC_MS = 250;
+/**
+ * All of a directive's argument previews together: it is written inside the
+ * prompt hook, so this is the most the preview adds to it, a stopped body
+ * included — each body's limit is clipped to what is left of it. A caller with
+ * less time left passes less (`steeringDirective`'s `previewBudgetMs`).
+ */
+export declare const PREVIEW_BUDGET_MS = 500;
 export interface ComposeResult {
     text: string;
     executed: number;
     recorded: number;
+    /** Steps whose call produced no result. The run stopped at the first. */
     skipped: number;
     /**
      * Of `executed`, how many tools ran and reported an error. Counted separately
@@ -80,6 +146,8 @@ export interface ComposeResult {
      * and yet the work did not happen, and an outcome must not say it did.
      */
     errored: number;
+    /** Where, and why, the run stopped short of its end, when it did. */
+    stopped?: PlanStop;
 }
 /** Where, and why, a run stopped short of the chain's end (fallbk.md). */
 export interface PlanStop {
@@ -90,11 +158,28 @@ export interface PlanStop {
     flatIndex?: number;
     stage?: ExecutionStage;
     error?: string;
+    /**
+     * For `step_failed`: what kind of stop — the step did not run, did not
+     * answer, was refused, or the budget or the caller ended the run before it.
+     * Absent means its logic threw or its tool reported an error.
+     */
+    reason?: HandoverStopReason;
 }
 export interface PlanOptions {
     scenario: SerializedScenario;
-    /** Resolves with the derived parameters. Rejection degrades to `{}`. */
+    /**
+     * Resolves with the derived parameters. A rejection settles them the way
+     * {@link ScenarioReplayPlan.useFallbackParams} does: settings at their
+     * recorded samples, targets `null` — never `{}`.
+     */
     params: Promise<Record<string, unknown>>;
+    /**
+     * What a *target* takes when the parameters settle without the derivation.
+     * `null` (the default) is the rule: a target is never guessed. `samples` is
+     * `bir replay`'s own contract — an operator named the scenario by id, so a
+     * recorded sample stands in (R-CALL-37).
+     */
+    fallbackTargets?: "null" | "samples";
     mode: ReplayMode;
     respParamsInit?: Record<string, unknown>;
     /**
@@ -127,6 +212,11 @@ export declare class ScenarioReplayPlan {
     private readonly entries;
     private readonly paramsPromise;
     private params;
+    /** The derivation's own answer, before `paramsLogic`. What safety.ts judges. */
+    private derivedParams;
+    /** Set once the parameters are final — derived, or settled without the derivation. */
+    private paramsSettled;
+    private readonly fallbackTargets;
     private respParams;
     private stepIndex;
     private readyPromise?;
@@ -158,11 +248,35 @@ export declare class ScenarioReplayPlan {
     private leaveFrame;
     /**
      * Await the derivation, then apply `paramsLogic` — once, however many callers
-     * race here. A rejected derivation resolves to `{}` rather than throwing: the
-     * caller decided long ago that a replay with fallback parameters beats no
-     * replay, and a throw here would abort a turn the user is waiting on.
+     * race here. A rejected derivation settles on the fallback values
+     * ({@link useFallbackParams}) rather than throwing.
+     *
+     * Rejects only when `paramsLogic` throws. That is real: the scenario's own
+     * logic is broken, and the caller must hand over rather than run steps on
+     * parameters nobody processed.
      */
     ready(): Promise<void>;
+    /**
+     * Settle the parameters without waiting any longer for the derivation: every
+     * *setting* at its recorded sample, every *target* `null` (R-PARAM-3), then
+     * `paramsLogic`. What the caller does when the derivation's budget runs out.
+     *
+     * Never `{}`. Running on an empty object put `undefined` into every argument
+     * — `{"command":"query undefined"}` — and a steered step was auto-approved
+     * with it. A target stays null here exactly as it does when the derivation
+     * answers without one, and the caller decides whether the plan can run
+     * without it (targets.ts).
+     *
+     * A derivation that answers later is ignored. Throws what `paramsLogic`
+     * throws.
+     */
+    useFallbackParams(): void;
+    /** Whether the parameters are final. */
+    get parametersSettled(): boolean;
+    /** The derivation's own values, before `paramsLogic`. Empty until settled. */
+    get derivedValues(): Readonly<Record<string, unknown>>;
+    private fallbackValues;
+    private settleParams;
     /** 0-based index of the step awaiting execution (== completed step count). */
     get currentStepIndex(): number;
     /** Steps this plan will run — the chain up to the first known-bad step. */
@@ -185,6 +299,10 @@ export declare class ScenarioReplayPlan {
     get parameters(): Readonly<Record<string, unknown>>;
     /** Everything the steps have accumulated so far. */
     get accumulated(): Readonly<Record<string, unknown>>;
+    /** The scenario's parameter schema — what the target and safety checks judge. */
+    get paramsSchema(): ParamsSchema | null;
+    /** The scenario's `paramsLogic`, which targets.ts reads as a consumer. */
+    get paramsLogic(): string | null;
     /** The step awaiting execution, or undefined when the plan is done. */
     currentStep(): SerializedScenarioStep | undefined;
     /** The tool the current step expects, or undefined when done. */
@@ -220,6 +338,24 @@ export declare class ScenarioReplayPlan {
     applyOutput(realOutput: string): string[];
     /** Build the final response model from everything the steps accumulated. */
     responseModel(): Record<string, unknown>;
+    /**
+     * The arguments each planned step will run with, where they are known before
+     * any step runs — for the steer directive (see {@link steeringDirective}).
+     *
+     * Known means: the parameters are settled, the step is the caller's own
+     * (a called segment's parameters are only built when it is entered), and
+     * its input logic neither reads nor passes on anything an earlier step
+     * accumulates — or it is the step at the cursor, whose accumulation is
+     * already final. Everything else is undefined, and the directive leaves
+     * those steps' arguments to the system.
+     *
+     * A look-ahead only: every body runs on copies, under a short limit, and a
+     * body that throws or runs long just leaves its step without arguments —
+     * the pin, not this, is what runs the step. The whole preview takes no more
+     * than `budgetMs` ({@link PREVIEW_BUDGET_MS}), a stopped body included; each
+     * body gets at most `bodyMs` ({@link PREVIEW_LOGIC_MS}) of it.
+     */
+    private previewArguments;
     /**
      * The directive injected via `UserPromptSubmit`'s `additionalContext`.
      *
@@ -227,9 +363,25 @@ export declare class ScenarioReplayPlan {
      * whole sequence server-side. In `steer` mode it names the sequence so the
      * model initiates the expected calls — the arguments are supplied by the
      * system, so the model need not compute them.
+     *
+     * WHY A STEER DIRECTIVE SHOWS ARGUMENTS. The pin replaces the model's
+     * arguments with the step's only when the call is plausibly the step
+     * (control/pin-guard.ts): the same command head, the same file, an argument
+     * in common. Told merely that "the system supplies the arguments", a model
+     * writes a placeholder call — `ls`, `{"query":"..."}` — that the guard rightly
+     * declines, and the plan retires having run nothing. So where a step's
+     * arguments are already known they are shown under it, as data, so that the
+     * call the model writes, and the user sees, is the call that runs.
+     *
+     * `previewBudgetMs` / `previewBodyMs` bound that preview (default
+     * {@link PREVIEW_BUDGET_MS} / {@link PREVIEW_LOGIC_MS}): a caller with less
+     * of its hook's time left passes less, and under
+     * {@link MIN_PREVIEW_BODY_MS} there is no preview at all.
      */
     steeringDirective(directToolName?: string, opts?: {
         subTask?: boolean;
+        previewBudgetMs?: number;
+        previewBodyMs?: number;
     }): string;
     /**
      * Execute every **remaining** step and lay the results out as one bundle.
@@ -238,16 +390,20 @@ export declare class ScenarioReplayPlan {
      * live session already ran — with side effects — every step before the one it
      * diverged on, so re-running them would be wrong.
      *
-     * There is no try/catch around the input or output logic: a throw there
-     * propagates out, and the caller abandons the whole bundle rather than
-     * shipping a half-computed one. The tool call itself is the exception — a
-     * rejection means the step could not be run *here*, and then a recorded output
-     * is not a shortcut past a real result, it is the only result that exists.
-     * Skipping instead would drop the step *and* stop threading `respParams`, so
-     * every later step reading from it fails too.
+     * A step whose call produced no result ends the bundle there
+     * ({@link DriveOptions}): later steps would compute on a result that does not
+     * exist, and nothing may be shown in its place. The stop is returned, and the
+     * bundle says the task is not finished. With `stopOnFailure` a logic throw or
+     * a tool error ends it the same way; without it they keep their old contract
+     * (a throw propagates, an error is threaded and counted).
+     *
+     * `deadline` bounds the whole bundle: this runs inside a `PreToolUse` hook
+     * with a timeout of its own, and a step started after the host stopped
+     * waiting is a side effect nobody is told about.
      */
-    composeBundle(maxChars: number, execute: ExecuteStep, recordedOutputFor?: RecordedOutputFor, onStep?: StepObserver, opts?: {
+    composeBundle(maxChars: number, execute: ExecuteStep, recordedOutputFor?: RecordedOutputFor, onStep?: StepObserver, opts?: DriveOptions & {
         handover?: boolean;
+        deadline?: number;
     }): Promise<ComposeResult>;
     /**
      * Run the whole plan from the current cursor, advancing it as it goes.
@@ -255,26 +411,44 @@ export declare class ScenarioReplayPlan {
      * This is `direct` mode's driver, and unlike {@link composeBundle} it mutates
      * the plan — the steps really did run, so the cursor and `respParams` must say
      * so, which is what lets the outcome be `steered_full` and `stepsPinned` be
-     * truthful. A step that cannot run at all still advances the cursor: the plan
-     * is spent either way, and stalling it would leave a retired turn looking live.
+     * truthful.
+     *
+     * A step whose call produced no result stops the run there, with the cursor
+     * on it ({@link DriveOptions}). So does the deadline, checked before each
+     * step, and the caller's `signal`. A step already sent is never abandoned:
+     * its result arrives (or its own timeout does) and is reported as it is.
      *
      * `maxChars` caps the bundle exactly as a divergence bundle is capped. The
      * direct path once passed `Number.MAX_SAFE_INTEGER` here — fine at 10 KB, and
      * an unbounded payload into the model's context for a scenario whose tools
      * answer in megabytes (docs/mcpmark.md §12).
      */
-    runToCompletion(execute: ExecuteStep, recordedOutputFor?: RecordedOutputFor, onStep?: StepObserver, deadline?: number, maxChars?: number, opts?: {
-        /**
-         * Stop at the first step that breaks — its logic throws, or its tool
-         * reports an error — instead of threading the error on (fallbk.md
-         * §Runner 3). A step after a failed one computes on a result that does not
-         * exist. Off keeps the old contract: a logic throw propagates, a tool
-         * error is threaded and counted.
-         */
-        stopOnFailure?: boolean;
-    }): Promise<ComposeResult & {
+    runToCompletion(execute: ExecuteStep, recordedOutputFor?: RecordedOutputFor, onStep?: StepObserver, deadline?: number, maxChars?: number, opts?: DriveOptions): Promise<ComposeResult & {
         partial: boolean;
         stopped?: PlanStop;
+        aborted?: boolean;
     }>;
+    /**
+     * A reason not to *start* the next step: the caller is gone, or the time is
+     * up. Undefined means go ahead.
+     */
+    private stopBefore;
+    /**
+     * Call one step's tool. Resolves with its result, with the recorded output
+     * that may stand in for it (only under `recordedFallback`, only for a step
+     * that could not be sent), or with the stop a missing result means.
+     */
+    private callStep;
+    /**
+     * A step's recorded output from the source run, waited on no longer than the
+     * driver's deadline.
+     *
+     * The lookup is a service fetch (source-run.ts) of up to its own timeout,
+     * and a divergence runs it inside a `PreToolUse` whose deadline the hook
+     * must keep (C1, C9): so it is a hot-path wait on the service, through the
+     * breaker, and a lookup that has not answered in time is no recorded output.
+     * A sliver of time left is not worth a request, nor a verdict on the service.
+     */
+    private recordedWithin;
 }
 //# sourceMappingURL=plan.d.ts.map