@basein/runner 0.2.0 → 0.2.2

package/dist/replay/plan.js

@@ -20,9 +20,29 @@
  *      step to know its reach, so it can choose between the proxy, a recorded
  *      output, and skipping.
  */
-import { evalParamsLogic, evalResponseParamsLogic, evalToolInputLogic, evalToolOutputLogic, } from "./logic.js";
+import { evalParamMapLogic, evalParamsLogic, evalResponseParamsLogic, evalResultMapLogic, evalToolInputLogic, evalToolOutputLogic, } from "./logic.js";
+import { flatEntriesOf } from "./flatten.js";
 import { assembleBundle, bundleInput, MAX_REPLAY_REASON } from "./bundle.js";
 import { toolResultError } from "./tool-error.js";
+/**
+ * The recorded values for the *settings* a mapping did not name (R-CALL-21).
+ *
+ * A target must always be supplied by the caller; a setting is what the segment
+ * was recorded doing, and taking its sample here is what makes "may be omitted"
+ * true rather than "runs with undefined".
+ */
+function settingsOf(paramsObject, mapped) {
+    const out = {};
+    if (!paramsObject || typeof paramsObject !== "object")
+        return out;
+    for (const [name, p] of Object.entries(paramsObject)) {
+        if (name in mapped)
+            continue;
+        if (p?.kind === "setting" && p && "sampleValue" in p)
+            out[name] = p.sampleValue;
+    }
+    return out;
+}
 /**
  * Evaluate one of the scenario's logic bodies, naming the step and the stage to
  * the observer if it throws — then rethrow, unchanged and uncaught.
@@ -32,13 +52,14 @@ import { toolResultError } from "./tool-error.js";
  * this adds is that the failure is now *attributable* — "step 2's tool input
  * logic", rather than a stack trace the console cannot line up against a chain.
  */
-function reportingStage(onStep, step, stage, input, startedAt, fn) {
+function reportingStage(onStep, entry, stage, input, startedAt, fn) {
     try {
         return fn();
     }
     catch (err) {
         onStep?.({
-            step,
+            step: entry.step,
+            entry,
             input,
             outcome: "failed",
             stage,
@@ -54,21 +75,107 @@ export class ScenarioReplayPlan {
     mode;
     intent;
     scenario;
-    steps;
+    /** The flat list this plan walks. One entry per step that will really run. */
+    entries;
     paramsPromise;
     params = {};
     respParams;
     stepIndex = 0;
     readyPromise;
+    /** Exclusive end of the planned steps. Equal to the chain length unless a step is parked. */
+    stopAt;
+    /** This plan is a sub-task inside the agent's own task (segmented.md R-OUT-13). */
+    subTask;
     constructor(opts) {
         this.scenario = opts.scenario;
         this.scenarioId = opts.scenario.id;
         this.runId = opts.scenario.runId;
         this.intent = opts.scenario.intent ?? "";
-        this.steps = opts.scenario.steps ?? [];
+        this.entries = opts.entries ?? flatEntriesOf(opts.scenario);
         this.mode = opts.mode;
         this.paramsPromise = opts.params;
         this.respParams = { ...(opts.respParamsInit ?? {}) };
+        // The caller's own frame accumulates into the plan's `respParams`, so
+        // `accumulated`, `responseModel` and every depth-0 step see one object.
+        if (this.entries[0])
+            this.rootFrame().respParams = this.respParams;
+        this.subTask = opts.subTask === true;
+        const stop = opts.stopAt;
+        this.stopAt =
+            typeof stop === "number" && stop >= 0 && stop < this.entries.length
+                ? stop
+                : this.entries.length;
+    }
+    /** The caller's own frame — the one at depth 0. */
+    rootFrame() {
+        let frame = this.entries[0].frame;
+        while (frame.parent)
+            frame = frame.parent;
+        return frame;
+    }
+    /** The parameters one entry's logic runs with (segmented.md R-CALL-29). */
+    paramsFor(entry) {
+        return entry.depth === 0 ? this.params : (entry.frame.parameters ?? {});
+    }
+    /** The accumulated values one entry's logic runs with. */
+    respFor(entry) {
+        return entry.depth === 0 ? this.respParams : entry.frame.respParams;
+    }
+    /**
+     * Entering a called frame: build the segment's parameters from the caller's
+     * state (R-CALL-29).
+     *
+     * The recipe is the dry run's, exactly (9.8 step 10): the mapping's output,
+     * plus the segment's own recorded sample for every *setting* the mapping left
+     * out. A mapping that omits a setting therefore cannot pass the service's
+     * check and then run `undefined` here.
+     */
+    enterFrame(entry, resp) {
+        if (!entry.first || entry.depth === 0)
+            return;
+        const frame = entry.frame;
+        const parent = frame.parent;
+        const parentParams = parent
+            ? parent.depth === 0
+                ? this.params
+                : (parent.parameters ?? {})
+            : this.params;
+        const parentResp = parent
+            ? resp
+                ? (resp.get(parent.id) ?? parent.respParams)
+                : parent.respParams
+            : this.respParams;
+        const mapped = frame.paramMapLogic
+            ? evalParamMapLogic(frame.paramMapLogic, parentParams, parent?.intent ?? this.intent, {
+                ...parentResp,
+            })
+            : {};
+        frame.parameters = { ...settingsOf(frame.paramsObject, mapped), ...mapped };
+        if (resp)
+            resp.set(frame.id, {});
+        else
+            frame.respParams = {};
+    }
+    /**
+     * Leaving a called frame: hand what the segment emitted back to its caller
+     * (R-CALL-29). `out` is the frame's own accumulated `respParams`.
+     */
+    leaveFrame(entry, resp) {
+        if (!entry.last || entry.depth === 0)
+            return;
+        const frame = entry.frame;
+        const parent = frame.parent;
+        if (!frame.resultMapLogic || !parent)
+            return;
+        const parentParams = parent.depth === 0 ? this.params : (parent.parameters ?? {});
+        const target = resp
+            ? (resp.get(parent.id) ?? parent.respParams)
+            : parent.depth === 0
+                ? this.respParams
+                : parent.respParams;
+        const own = resp ? (resp.get(frame.id) ?? frame.respParams) : frame.respParams;
+        const out = evalResultMapLogic(frame.resultMapLogic, { ...own }, parentParams, parent.intent, { ...target });
+        Object.assign(target, out);
     }
     /**
      * Await the derivation, then apply `paramsLogic` — once, however many callers
@@ -96,8 +203,37 @@ export class ScenarioReplayPlan {
     get currentStepIndex() {
         return this.stepIndex;
     }
+    /** Steps this plan will run — the chain up to the first known-bad step. */
     get stepCount() {
-        return this.steps.length;
+        return this.stopAt;
+    }
+    /** Every step this plan could run, planned or not. */
+    get totalSteps() {
+        return this.entries.length;
+    }
+    /** True when the plan ends in front of a known-bad step (fallbk.md D3). */
+    stopsEarly() {
+        return this.stopAt < this.entries.length;
+    }
+    /** The known-bad step the plan stops in front of, if any. */
+    stopStep() {
+        return this.stopsEarly() ? this.entries[this.stopAt]?.step : undefined;
+    }
+    /** The entry the plan stops in front of, with the frame that owns it. */
+    stopEntry() {
+        return this.stopsEarly() ? this.entries[this.stopAt] : undefined;
+    }
+    /** Tool names from position `from` to the end of the flat chain. */
+    toolsFrom(from) {
+        return this.entries.slice(Math.max(0, from)).map((e) => e.step.toolName ?? "");
+    }
+    /** Every entry in order — for the report, and for the owning scenario ids. */
+    allEntries() {
+        return this.entries;
+    }
+    /** The entry awaiting execution, or undefined when the plan is done. */
+    currentEntry() {
+        return this.stepIndex < this.stopAt ? this.entries[this.stepIndex] : undefined;
     }
     /** The parameters in force. Empty until {@link ready} resolves. */
     get parameters() {
@@ -109,19 +245,19 @@ export class ScenarioReplayPlan {
     }
     /** The step awaiting execution, or undefined when the plan is done. */
     currentStep() {
-        return this.steps[this.stepIndex];
+        return this.currentEntry()?.step;
     }
     /** The tool the current step expects, or undefined when done. */
     expectedTool() {
-        return this.steps[this.stepIndex]?.toolName;
+        return this.currentStep()?.toolName ?? undefined;
     }
-    /** True once every step has been applied — the plan should be retired. */
+    /** True once every planned step has been applied — the plan should be retired. */
     isDone() {
-        return this.stepIndex >= this.steps.length;
+        return this.stepIndex >= this.stopAt;
     }
     /** Every step in order — for the directive, and for coverage reporting. */
     allSteps() {
-        return this.steps;
+        return this.entries.map((e) => e.step);
     }
     /**
      * True when `toolName` is one of this scenario's own tools.
@@ -133,7 +269,7 @@ export class ScenarioReplayPlan {
      * abandoned the sequence.
      */
     usesTool(toolName) {
-        return this.steps.some((s) => s.toolName === toolName);
+        return this.entries.some((e) => e.step.toolName === toolName);
     }
     /**
      * Compute the pinned input for the current step. Throws when there is no
@@ -141,10 +277,13 @@ export class ScenarioReplayPlan {
      * a throw as divergence.
      */
     toolInputForCurrentStep() {
-        const step = this.steps[this.stepIndex];
-        if (!step)
+        const entry = this.entries[this.stepIndex];
+        if (!entry)
             throw new Error("no current step to compute input for");
-        return evalToolInputLogic(step.toolInputLogic, this.params, this.intent, this.respParams);
+        // Entering a called frame happens here, on its first step, because this is
+        // the first moment the caller's own accumulation is final (R-CALL-29).
+        this.enterFrame(entry);
+        return evalToolInputLogic(entry.step.toolInputLogic ?? "return {};", this.paramsFor(entry), entry.frame.intent, this.respFor(entry));
     }
     /**
      * Thread a real tool output into `respParams` and advance.
@@ -155,15 +294,20 @@ export class ScenarioReplayPlan {
      * Throws when `toolOutputLogic` fails; the caller aborts to a normal turn.
      */
     applyOutput(realOutput) {
-        const step = this.steps[this.stepIndex];
-        if (!step)
+        const entry = this.entries[this.stepIndex];
+        if (!entry)
             return [];
         let derivedKeys = [];
-        if (step.toolOutputLogic) {
-            const derived = evalToolOutputLogic(step.toolOutputLogic, realOutput, this.params, this.intent, this.respParams);
+        if (entry.step.toolOutputLogic) {
+            const derived = evalToolOutputLogic(entry.step.toolOutputLogic, realOutput, this.paramsFor(entry), entry.frame.intent, this.respFor(entry));
             derivedKeys = Object.keys(derived);
-            this.respParams = { ...this.respParams, ...derived };
+            // Mutated, not replaced: the frame's store is the object the plan and
+            // every later step of that frame already hold.
+            Object.assign(this.respFor(entry), derived);
         }
+        // Leaving a called frame hands its results back to the caller before the
+        // caller's next step reads them (R-CALL-29).
+        this.leaveFrame(entry);
         this.stepIndex += 1;
         return derivedKeys;
     }
@@ -181,14 +325,22 @@ export class ScenarioReplayPlan {
      * model initiates the expected calls — the arguments are supplied by the
      * system, so the model need not compute them.
      */
-    steeringDirective(directToolName = "mcp__bir__run_scenario") {
+    steeringDirective(directToolName = "mcp__bir__run_scenario", opts) {
+        // A sub-task plan (segmented.md R-OUT-13) never tells the agent to stop
+        // calling tools: the steps below are a part of the task it is already doing.
+        const subTask = opts?.subTask ?? this.subTask;
         // The intent is a paragraph the analyser wrote; it is context, not an
         // instruction, so it is clipped rather than dumped whole into the prompt.
         const intent = this.intent.length > 240 ? `${this.intent.slice(0, 240)}…` : this.intent;
-        const lines = this.steps.map((s, i) => {
-            const why = s.reasoning ? ` — ${s.reasoning}` : "";
-            return `  ${i + 1}. ${s.toolName}${why}`;
+        const lines = this.entries.slice(0, this.stopAt).map((e, i) => {
+            const why = e.step.reasoning ? ` — ${e.step.reasoning}` : "";
+            return `  ${i + 1}. ${e.step.toolName ?? ""}${why}`;
         });
+        // A parked step (fallbk.md D3): the model is told up front that the plan is
+        // partial, so the hand-over that follows is expected rather than a surprise.
+        const tail = this.stopsEarly()
+            ? ["", "The system will then hand the rest of the task back to you."]
+            : [];
         if (this.mode === "direct") {
             // The sequence is listed even though the model does not call it itself:
             // it is about to receive these results, and knowing what was run is what
@@ -203,7 +355,12 @@ export class ScenarioReplayPlan {
                 ...lines,
                 "",
                 `Call ${directToolName} once, with no arguments, before any other tool.`,
-                "Then answer the user's request from the results it returns.",
+                subTask
+                    ? "Then continue your task from the results it returns, calling tools as needed."
+                    : this.stopsEarly()
+                        ? "Then continue the user's request from the results it returns."
+                        : "Then answer the user's request from the results it returns.",
+                ...tail,
             ].join("\n");
         }
         return [
@@ -214,8 +371,17 @@ export class ScenarioReplayPlan {
             ...(intent ? ["", `Context: ${intent}`] : []),
             "",
             "The system supplies the exact arguments for each call — you do not need to",
-            "compute them. Do not call any other tools until this sequence is complete,",
-            "then answer the user's request from the tool results.",
+            ...(subTask
+                ? [
+                    "compute them. Do not call any other tools until this sequence is complete.",
+                    "These steps are part of your task: when they are done, continue your task,",
+                    "calling tools as needed.",
+                ]
+                : [
+                    "compute them. Do not call any other tools until this sequence is complete,",
+                    "then answer the user's request from the tool results.",
+                ]),
+            ...tail,
         ].join("\n");
     }
     /**
@@ -233,18 +399,27 @@ export class ScenarioReplayPlan {
      * Skipping instead would drop the step *and* stop threading `respParams`, so
      * every later step reading from it fails too.
      */
-    async composeBundle(maxChars, execute, recordedOutputFor, onStep) {
+    async composeBundle(maxChars, execute, recordedOutputFor, onStep, opts = {}) {
         // A local copy: composing must not corrupt the live plan's accumulation if
         // the caller decides to keep steering afterwards.
-        const respParams = { ...this.respParams };
+        // One copy per frame, for the same reason the plan copied its own: composing
+        // must not corrupt the live accumulation if the caller keeps steering.
+        const resp = new Map();
+        if (this.entries[0])
+            resp.set(this.rootFrame().id, { ...this.respParams });
         const entries = [];
         let executed = 0;
         let recordedCount = 0;
         let skipped = 0;
         let errored = 0;
-        for (const step of this.steps.slice(this.stepIndex)) {
+        for (const entry of this.entries.slice(this.stepIndex, this.stopAt)) {
+            const step = entry.step;
             const startedAt = Date.now();
-            const computed = reportingStage(onStep, step, "tool_input_logic", {}, startedAt, () => evalToolInputLogic(step.toolInputLogic, this.params, this.intent, respParams));
+            const computed = reportingStage(onStep, entry, "tool_input_logic", {}, startedAt, () => {
+                this.enterFrame(entry, resp);
+                const respParams = resp.get(entry.frame.id) ?? {};
+                return evalToolInputLogic(step.toolInputLogic ?? "return {};", this.paramsFor(entry), entry.frame.intent, respParams);
+            });
             let response;
             let recorded = false;
             try {
@@ -255,26 +430,27 @@ export class ScenarioReplayPlan {
                 const error = err instanceof Error ? err.message : String(err);
                 const fallback = (typeof step.recordedOutput === "string" && step.recordedOutput.length > 0
                     ? step.recordedOutput
-                    : undefined) ?? (await recordedOutputFor?.(step).catch(() => undefined));
+                    : undefined) ?? (await recordedOutputFor?.(entry).catch(() => undefined));
                 if (!fallback) {
                     skipped += 1;
-                    onStep?.({ step, input: computed, outcome: "skipped", error, ms: Date.now() - startedAt });
+                    onStep?.({ step, entry, input: computed, outcome: "skipped", error, ms: Date.now() - startedAt });
                     continue;
                 }
                 response = fallback;
                 recorded = true;
                 recordedCount += 1;
-                onStep?.({ step, input: computed, outcome: "recorded", error, ms: Date.now() - startedAt });
+                onStep?.({ step, entry, input: computed, outcome: "recorded", error, ms: Date.now() - startedAt });
             }
             // Thread the output for later steps' inputs. A recorded output threads
             // too: `toolOutputLogic` was authored against exactly this shape, and a
             // stale value beats a missing one downstream.
             let derivedKeys = [];
             if (step.toolOutputLogic) {
-                const derived = reportingStage(onStep, step, "tool_output_logic", computed, startedAt, () => evalToolOutputLogic(step.toolOutputLogic, response, this.params, this.intent, respParams));
+                const derived = reportingStage(onStep, entry, "tool_output_logic", computed, startedAt, () => evalToolOutputLogic(step.toolOutputLogic, response, this.paramsFor(entry), entry.frame.intent, resp.get(entry.frame.id) ?? {}));
                 derivedKeys = Object.keys(derived);
-                Object.assign(respParams, derived);
+                Object.assign(resp.get(entry.frame.id) ?? {}, derived);
             }
+            this.leaveFrame(entry, resp);
             if (!recorded) {
                 // A step's verdict is its output, not its resolution: a tool that ran
                 // and answered "Error: …" resolves like any other, and a chain of eight
@@ -284,6 +460,7 @@ export class ScenarioReplayPlan {
                     errored += 1;
                 onStep?.({
                     step,
+                    entry,
                     input: computed,
                     outcome: error ? "failed" : "executed",
                     stage: error ? "tool_call" : undefined,
@@ -293,14 +470,17 @@ export class ScenarioReplayPlan {
                 });
             }
             entries.push({
-                toolName: step.toolName,
+                toolName: step.toolName ?? "",
                 input: bundleInput(computed),
                 response,
                 recorded,
             });
         }
         return {
-            text: assembleBundle(entries, maxChars),
+            text: assembleBundle(entries, maxChars, {
+                handover: opts.handover,
+                subTask: this.subTask,
+            }),
             executed,
             recorded: recordedCount,
             skipped,
@@ -321,21 +501,39 @@ export class ScenarioReplayPlan {
      * an unbounded payload into the model's context for a scenario whose tools
      * answer in megabytes (docs/mcpmark.md §12).
      */
-    async runToCompletion(execute, recordedOutputFor, onStep, deadline, maxChars = MAX_REPLAY_REASON) {
+    async runToCompletion(execute, recordedOutputFor, onStep, deadline, maxChars = MAX_REPLAY_REASON, opts = {}) {
         const entries = [];
         let executed = 0;
         let recordedCount = 0;
         let skipped = 0;
         let errored = 0;
         let partial = false;
+        let stopped;
+        const stopOnFailure = opts.stopOnFailure === true;
+        const errText = (err) => (err instanceof Error ? err.message : String(err));
         while (!this.isDone()) {
             if (deadline !== undefined && Date.now() >= deadline) {
                 partial = true;
                 break;
             }
-            const step = this.steps[this.stepIndex];
+            const entry = this.entries[this.stepIndex];
+            const step = entry.step;
             const startedAt = Date.now();
-            const computed = reportingStage(onStep, step, "tool_input_logic", {}, startedAt, () => this.toolInputForCurrentStep());
+            let computed;
+            try {
+                computed = reportingStage(onStep, entry, "tool_input_logic", {}, startedAt, () => this.toolInputForCurrentStep());
+            }
+            catch (err) {
+                if (!stopOnFailure)
+                    throw err;
+                stopped = {
+                    kind: "step_failed",
+                    stepIndex: step.stepIndex,
+                    stage: "tool_input_logic",
+                    error: errText(err),
+                };
+                break;
+            }
             let response;
             let recorded = false;
             try {
@@ -346,20 +544,75 @@ export class ScenarioReplayPlan {
                 const error = err instanceof Error ? err.message : String(err);
                 const fallback = (typeof step.recordedOutput === "string" && step.recordedOutput.length > 0
                     ? step.recordedOutput
-                    : undefined) ?? (await recordedOutputFor?.(step).catch(() => undefined));
+                    : undefined) ?? (await recordedOutputFor?.(entry).catch(() => undefined));
                 if (!fallback) {
                     skipped += 1;
-                    onStep?.({ step, input: computed, outcome: "skipped", error, ms: Date.now() - startedAt });
+                    onStep?.({ step, entry, input: computed, outcome: "skipped", error, ms: Date.now() - startedAt });
                     // Advance past a step that cannot run, without threading anything.
+                    // The frame is still left behind it: a sub-task whose last step could
+                    // not run here still hands back whatever its earlier steps emitted.
+                    this.leaveFrame(entry);
                     this.stepIndex += 1;
                     continue;
                 }
                 response = fallback;
                 recorded = true;
                 recordedCount += 1;
-                onStep?.({ step, input: computed, outcome: "recorded", error, ms: Date.now() - startedAt });
+                onStep?.({ step, entry, input: computed, outcome: "recorded", error, ms: Date.now() - startedAt });
+            }
+            if (stopOnFailure && !recorded) {
+                // Judged before the output logic, which was written against a success
+                // and would only throw a second, less useful error on this one.
+                const toolError = toolResultError(response);
+                if (toolError) {
+                    errored += 1;
+                    onStep?.({
+                        step,
+                        entry,
+                        input: computed,
+                        outcome: "failed",
+                        stage: "tool_call",
+                        error: toolError,
+                        ms: Date.now() - startedAt,
+                    });
+                    entries.push({
+                        toolName: step.toolName ?? "",
+                        input: bundleInput(computed),
+                        response,
+                        recorded,
+                    });
+                    this.stepIndex += 1;
+                    stopped = {
+                        kind: "step_failed",
+                        stepIndex: step.stepIndex,
+                        stage: "tool_call",
+                        error: toolError,
+                    };
+                    break;
+                }
+            }
+            let derivedKeys;
+            try {
+                derivedKeys = reportingStage(onStep, entry, "tool_output_logic", computed, startedAt, () => this.applyOutput(response));
+            }
+            catch (err) {
+                if (!stopOnFailure)
+                    throw err;
+                // The tool ran; its output is real and belongs in front of the model.
+                entries.push({
+                    toolName: step.toolName ?? "",
+                    input: bundleInput(computed),
+                    response,
+                    recorded,
+                });
+                stopped = {
+                    kind: "step_failed",
+                    stepIndex: step.stepIndex,
+                    stage: "tool_output_logic",
+                    error: errText(err),
+                };
+                break;
             }
-            const derivedKeys = reportingStage(onStep, step, "tool_output_logic", computed, startedAt, () => this.applyOutput(response));
             if (!recorded) {
                 // A step's verdict is its output, not its resolution: a tool that ran
                 // and answered "Error: …" resolves like any other, and a chain of eight
@@ -369,6 +622,7 @@ export class ScenarioReplayPlan {
                     errored += 1;
                 onStep?.({
                     step,
+                    entry,
                     input: computed,
                     outcome: error ? "failed" : "executed",
                     stage: error ? "tool_call" : undefined,
@@ -378,19 +632,27 @@ export class ScenarioReplayPlan {
                 });
             }
             entries.push({
-                toolName: step.toolName,
+                toolName: step.toolName ?? "",
                 input: bundleInput(computed),
                 response,
                 recorded,
             });
         }
+        // Every planned step ran and the plan ends in front of a parked one.
+        if (!stopped && !partial && this.stopsEarly() && this.isDone()) {
+            stopped = { kind: "known_bad_step", stepIndex: this.entries[this.stopAt].stepIndex };
+        }
         return {
-            text: assembleBundle(entries, maxChars),
+            text: assembleBundle(entries, maxChars, {
+                handover: stopped !== undefined,
+                subTask: this.subTask,
+            }),
             executed,
             recorded: recordedCount,
             skipped,
             errored,
             partial,
+            stopped,
         };
     }
 }

package/dist/replay/source-run.d.ts

@@ -21,30 +21,44 @@
  *
  * Fetched **lazily** — only when a step actually needs it — and cached for the
  * turn, so a fully-executable replay never makes this call at all.
+ *
+ * A chain with calls draws on **several** recordings: a called segment's steps
+ * take their outputs from that segment's own recording, within its own range
+ * (segmented.md R-CALL-31). So the rows are cached per run id, and the cursors
+ * are kept per frame — a segment called twice in one chain replays from the
+ * start of its range both times, as two separate replays of it would.
  */
-import type { SerializedScenarioStep } from "./types.js";
+import type { FlatEntry } from "./flatten.js";
 export interface SourceRunOptions {
     baseUrl: string;
+    /** The run the plan's own scenario came from; others are fetched on demand. */
     runId: string;
     /** Bearer token; refreshed by the caller, read fresh on each fetch. */
     token: () => string;
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
 }
-export declare class SourceRunOutputs {
+export declare class SourceRunCache {
     private readonly opts;
-    /** toolName → recorded outputs, in run order. */
-    private byTool?;
-    private cursor;
-    private loading?;
+    /** run id → every recorded output of that run, in order. */
+    private readonly runs;
+    private readonly loading;
+    /** `frameId#toolName` → how many of that tool the frame has drawn. */
+    private readonly cursor;
     constructor(opts: SourceRunOptions);
     /**
-     * The next recorded output for `step`'s tool, or undefined when the run has
-     * none left (or could not be fetched). Never throws — a missing recorded
-     * output means the step is skipped, which the caller already handles.
+     * The next recorded output for this entry's tool, from this entry's own
+     * recording and range, or undefined when there is none left (or the run could
+     * not be fetched). Never throws — a missing recorded output means the step is
+     * skipped, which the caller already handles.
      */
-    outputFor(step: SerializedScenarioStep): Promise<string | undefined>;
+    outputFor(entry: FlatEntry): Promise<string | undefined>;
     private load;
     private fetchRun;
 }
+/**
+ * The name this class had before one chain could draw on more than one
+ * recording. Kept so nothing outside has to change its import.
+ */
+export { SourceRunCache as SourceRunOutputs };
 //# sourceMappingURL=source-run.d.ts.map