@basein/runner 0.2.0 → 0.2.2

package/dist/replay/handover.d.ts

@@ -0,0 +1,60 @@
+/**
+ * handover — what the model is told when a calculated scenario stops part-way
+ * and the rest of the task is its own again (the service's fallbk.md).
+ *
+ * Before this existed a failing step retired the plan silently: every later
+ * tool call passed through, and the model finished the task without ever being
+ * told a plan had been steering it, which step broke, or what was left. So a
+ * hand-over is always a message, never silence (D4).
+ *
+ * Message only in the error position — this text reaches the model's context,
+ * and a tool's own payload is already in front of it where it ran.
+ */
+import type { FallbackKind } from "./types.js";
+/** Hard ceiling on a note. Long enough to carry derived params, short enough to read. */
+export declare const MAX_HANDOVER_NOTE = 4000;
+/** Where the executed steps are, from the model's point of view. */
+export type HandoverDelivery = 
+/** Steer mode: the steps that ran are the model's own tool calls, just above. */
+"above"
+/** Direct mode: the steps that ran are in the bundle that follows the note. */
+ | "below";
+export interface HandoverNoteInput {
+    intent: string;
+    kind: FallbackKind;
+    /** The step the plan stopped at — the scenario's own `stepIndex`. */
+    stepIndex: number;
+    stepToolName?: string;
+    /** How often the stopped step has failed before (known_bad_step). */
+    failureCount?: number;
+    /** Why it stopped (step_failed). */
+    error?: string;
+    /** Steps that ran under the scenario before the stop. */
+    executed: number;
+    totalSteps: number;
+    /** Tool names of the planned steps from the stopped one to the end. */
+    remainingTools: string[];
+    params?: Readonly<Record<string, unknown>>;
+    delivery: HandoverDelivery;
+    /**
+     * The plan stopped in front of a *call* it cannot run (segmented.md
+     * R-CALL-29, R-CALL-36). The agent is told what that stretch of work was and
+     * why it is not running, so it does that part itself rather than wondering
+     * what is missing.
+     */
+    unusable?: {
+        reason: string;
+        callIntent?: string | null;
+        segmentId?: string | null;
+        ownerScenarioId?: string | null;
+    };
+    /**
+     * The scenario that owns the stopped step, when it is not the one that was
+     * matched — a parked step inside a called segment (R-CALL-30).
+     */
+    ownerScenarioId?: string | null;
+    /** The sub-task the stopped step belongs to, when it is inside one. */
+    inSubTask?: string | null;
+}
+export declare function buildHandoverNote(n: HandoverNoteInput): string;
+//# sourceMappingURL=handover.d.ts.map

package/dist/replay/handover.js

@@ -0,0 +1,82 @@
+/**
+ * handover — what the model is told when a calculated scenario stops part-way
+ * and the rest of the task is its own again (the service's fallbk.md).
+ *
+ * Before this existed a failing step retired the plan silently: every later
+ * tool call passed through, and the model finished the task without ever being
+ * told a plan had been steering it, which step broke, or what was left. So a
+ * hand-over is always a message, never silence (D4).
+ *
+ * Message only in the error position — this text reaches the model's context,
+ * and a tool's own payload is already in front of it where it ran.
+ */
+import { truncate } from "./bundle.js";
+/** Hard ceiling on a note. Long enough to carry derived params, short enough to read. */
+export const MAX_HANDOVER_NOTE = 4_000;
+const MAX_ERROR_CHARS = 500;
+const MAX_PARAMS_CHARS = 1_500;
+/** What the note says about each reason a call cannot run (R-CALL-36). */
+const UNUSABLE_LINE = {
+    switched_off: "whose recorded scenario is switched off",
+    not_ready: "whose recorded scenario is not ready",
+    missing: "whose recorded scenario was deleted",
+    stale: "whose recorded scenario is out of date",
+    unresolved: "with no matching recorded scenario right now",
+    depth: "whose recorded scenario is nested too deep to run here",
+    unsupported: "this runner cannot run",
+};
+export function buildHandoverNote(n) {
+    const intent = n.intent.length > 240 ? `${n.intent.slice(0, 240)}…` : n.intent;
+    const human = n.stepIndex + 1;
+    const tool = n.stepToolName ? ` (${n.stepToolName})` : "";
+    const lines = [
+        "[BaseInstRunner calculated replay] The calculated scenario for this request stopped",
+        "before finishing. Continue the task yourself from here, calling tools as needed.",
+    ];
+    if (intent)
+        lines.push(`Intent: ${intent}`);
+    if (n.executed > 0) {
+        lines.push(n.delivery === "above"
+            ? `Steps 1–${n.executed} of ${n.totalSteps} ran under the scenario; their calls and results are the tool calls above. Do not repeat them.`
+            : `Steps 1–${n.executed} of ${n.totalSteps} ran under the scenario; their calls and results are below. Do not repeat them.`);
+    }
+    else {
+        lines.push("No step of the scenario ran; the whole task is yours.");
+    }
+    if (n.kind === "unusable_call") {
+        // A call is a stretch of work, not a tool: the agent is told what the
+        // sub-task was, not which tool did not run.
+        const what = n.unusable?.callIntent ? ` ("${truncate(n.unusable.callIntent, 200)}")` : "";
+        const why = UNUSABLE_LINE[n.unusable?.reason ?? ""] ?? "that cannot run here";
+        lines.push(`Step ${human} of ${n.totalSteps} is a sub-task${what} ${why}.`);
+    }
+    else if (n.kind === "known_bad_step") {
+        const times = n.failureCount ? ` ${n.failureCount} times` : "";
+        // A parked step inside a called segment names the scenario that owns it:
+        // that is where the repair happens, and the agent's own step numbering has
+        // no row for it (R-CALL-30).
+        const owner = n.inSubTask
+            ? `, in sub-task "${truncate(n.inSubTask, 120)}"${n.ownerScenarioId ? `, scenario ${n.ownerScenarioId}` : ""}`
+            : "";
+        lines.push(`Step ${human} of ${n.totalSteps}${tool.replace(/\)$/, `${owner})`)} did not run: it has failed${times} before, so the scenario stops in front of it.`);
+    }
+    else {
+        const error = n.error ? `: ${truncate(n.error, MAX_ERROR_CHARS)}` : "";
+        lines.push(`Step ${human} of ${n.totalSteps}${tool} failed${error}`);
+    }
+    if (n.remainingTools.length > 0) {
+        lines.push(`The remaining planned steps were: ${n.remainingTools.join(", ")}.`);
+    }
+    if (n.params && Object.keys(n.params).length > 0) {
+        let json;
+        try {
+            json = JSON.stringify(n.params);
+        }
+        catch {
+            json = "[unserializable]";
+        }
+        lines.push(`Parameters derived for this request: ${truncate(json, MAX_PARAMS_CHARS)}`);
+    }
+    return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
+}
+//# sourceMappingURL=handover.js.map

package/dist/replay/logic.d.ts

@@ -28,4 +28,15 @@ export declare function evalToolInputLogic(code: string, parameters: Record<stri
 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. */
 export declare function evalResponseParamsLogic(code: string, respParams: Record<string, unknown>, parameters: Record<string, unknown>, intent: string): Record<string, unknown>;
+/**
+ * The two mapping bodies of a call (segmented.md R-CALL-20).
+ *
+ * `paramMapLogic` builds the called segment's parameters from the caller's
+ * state; `resultMapLogic` turns what the segment emitted into the keys the
+ * caller's later steps read. Both belong to the *(call, segment) pair* rather
+ * than to either side alone, which is why two chains calling one segment carry
+ * two of them.
+ */
+export declare function evalParamMapLogic(code: string, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>): Record<string, unknown>;
+export declare function evalResultMapLogic(code: string, out: Record<string, unknown>, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>): Record<string, unknown>;
 //# sourceMappingURL=logic.d.ts.map

package/dist/replay/logic.js

@@ -47,4 +47,21 @@ export function evalResponseParamsLogic(code, respParams, parameters, intent) {
     const fn = new Function("respParams", "parameters", "intent", code);
     return assertPlainObject(fn(respParams, parameters, intent), "responseParamsLogic");
 }
+/**
+ * The two mapping bodies of a call (segmented.md R-CALL-20).
+ *
+ * `paramMapLogic` builds the called segment's parameters from the caller's
+ * state; `resultMapLogic` turns what the segment emitted into the keys the
+ * caller's later steps read. Both belong to the *(call, segment) pair* rather
+ * than to either side alone, which is why two chains calling one segment carry
+ * 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");
+}
+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");
+}
 //# sourceMappingURL=logic.js.map

package/dist/replay/plan.d.ts

@@ -20,8 +20,9 @@
  *      step to know its reach, so it can choose between the proxy, a recorded
  *      output, and skipping.
  */
+import { type FlatEntry } from "./flatten.js";
 import type { ReplayMode } from "./coverage.js";
-import type { ExecutionStage, SerializedScenario, SerializedScenarioStep } from "./types.js";
+import type { ExecutionStage, FallbackKind, SerializedScenario, SerializedScenarioStep } from "./types.js";
 /**
  * Runs one step's tool and returns its output as a string.
  *
@@ -30,8 +31,14 @@ import type { ExecutionStage, SerializedScenario, SerializedScenarioStep } from
  * case a recorded output may stand in for.
  */
 export type ExecuteStep = (step: SerializedScenarioStep, input: Record<string, unknown>) => Promise<string>;
-/** Supplies a step's recorded output when its tool cannot run here (§8.1). */
-export type RecordedOutputFor = (step: SerializedScenarioStep) => Promise<string | undefined>;
+/**
+ * Supplies a step's recorded output when its tool cannot run here (§8.1).
+ *
+ * It takes the *entry*, not the step: a step inside a called segment takes its
+ * recorded output from that segment's own recording, within its own range
+ * (segmented.md R-CALL-31).
+ */
+export type RecordedOutputFor = (entry: FlatEntry) => Promise<string | undefined>;
 /**
  * What one step did, told to the caller as it happens.
  *
@@ -45,6 +52,12 @@ export type RecordedOutputFor = (step: SerializedScenarioStep) => Promise<string
  */
 export interface StepInfo {
     step: SerializedScenarioStep;
+    /**
+     * The flat entry this step ran as: which scenario owns it, which frame it
+     * ran in, and where it sits in the flat order (segmented.md R-CALL-13).
+     * Absent only where a caller builds a StepInfo by hand.
+     */
+    entry?: FlatEntry;
     input: Record<string, unknown>;
     outcome: "executed" | "recorded" | "skipped" | "failed";
     /** Which part of the step broke. Only set for `failed`. */
@@ -66,12 +79,41 @@ export interface ComposeResult {
      */
     errored: number;
 }
+/** Where, and why, a run stopped short of the chain's end (fallbk.md). */
+export interface PlanStop {
+    kind: FallbackKind;
+    /** The owning scenario's own `stepIndex` of the step it stopped at. */
+    stepIndex: number;
+    /** Its position in the flat list, which is what the caller indexes by. */
+    flatIndex?: number;
+    stage?: ExecutionStage;
+    error?: string;
+}
 export interface PlanOptions {
     scenario: SerializedScenario;
     /** Resolves with the derived parameters. Rejection degrades to `{}`. */
     params: Promise<Record<string, unknown>>;
     mode: ReplayMode;
     respParamsInit?: Record<string, unknown>;
+    /**
+     * Position of the first known-bad step (fallbk.md D3). The plan ends in front
+     * of it: the steps before it are the plan, the rest is handed to the model.
+     * Omitted means the whole chain.
+     */
+    stopAt?: number;
+    /**
+     * The plan is a sub-task inside the agent's own task (segmented.md R-OUT-13):
+     * it was armed by intent, not by the prompt, so its directive and its bundles
+     * tell the agent to continue its task rather than to stop calling tools.
+     */
+    subTask?: boolean;
+    /**
+     * The flattened chain: the steps that will really run, each with the frame it
+     * runs in (segmented.md 10.6). A chain with no calls flattens to one frame
+     * and behaves exactly as it did before calls existed, which is why this is
+     * optional — a caller that does not flatten gets that same single frame.
+     */
+    entries?: FlatEntry[];
 }
 export declare class ScenarioReplayPlan {
     readonly scenarioId: string;
@@ -79,13 +121,39 @@ export declare class ScenarioReplayPlan {
     readonly mode: ReplayMode;
     readonly intent: string;
     private readonly scenario;
-    private readonly steps;
+    /** The flat list this plan walks. One entry per step that will really run. */
+    private readonly entries;
     private readonly paramsPromise;
     private params;
     private respParams;
     private stepIndex;
     private readyPromise?;
+    /** Exclusive end of the planned steps. Equal to the chain length unless a step is parked. */
+    private readonly stopAt;
+    /** This plan is a sub-task inside the agent's own task (segmented.md R-OUT-13). */
+    readonly subTask: boolean;
     constructor(opts: PlanOptions);
+    /** The caller's own frame — the one at depth 0. */
+    private rootFrame;
+    /** The parameters one entry's logic runs with (segmented.md R-CALL-29). */
+    private paramsFor;
+    /** The accumulated values one entry's logic runs with. */
+    private respFor;
+    /**
+     * 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.
+     */
+    private enterFrame;
+    /**
+     * Leaving a called frame: hand what the segment emitted back to its caller
+     * (R-CALL-29). `out` is the frame's own accumulated `respParams`.
+     */
+    private leaveFrame;
     /**
      * Await the derivation, then apply `paramsLogic` — once, however many callers
      * race here. A rejected derivation resolves to `{}` rather than throwing: the
@@ -95,7 +163,22 @@ export declare class ScenarioReplayPlan {
     ready(): Promise<void>;
     /** 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. */
     get stepCount(): number;
+    /** Every step this plan could run, planned or not. */
+    get totalSteps(): number;
+    /** True when the plan ends in front of a known-bad step (fallbk.md D3). */
+    stopsEarly(): boolean;
+    /** The known-bad step the plan stops in front of, if any. */
+    stopStep(): SerializedScenarioStep | undefined;
+    /** The entry the plan stops in front of, with the frame that owns it. */
+    stopEntry(): FlatEntry | undefined;
+    /** Tool names from position `from` to the end of the flat chain. */
+    toolsFrom(from: number): string[];
+    /** Every entry in order — for the report, and for the owning scenario ids. */
+    allEntries(): readonly FlatEntry[];
+    /** The entry awaiting execution, or undefined when the plan is done. */
+    currentEntry(): FlatEntry | undefined;
     /** The parameters in force. Empty until {@link ready} resolves. */
     get parameters(): Readonly<Record<string, unknown>>;
     /** Everything the steps have accumulated so far. */
@@ -104,7 +187,7 @@ export declare class ScenarioReplayPlan {
     currentStep(): SerializedScenarioStep | undefined;
     /** The tool the current step expects, or undefined when done. */
     expectedTool(): string | 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(): boolean;
     /** Every step in order — for the directive, and for coverage reporting. */
     allSteps(): readonly SerializedScenarioStep[];
@@ -143,7 +226,9 @@ export declare class ScenarioReplayPlan {
      * model initiates the expected calls — the arguments are supplied by the
      * system, so the model need not compute them.
      */
-    steeringDirective(directToolName?: string): string;
+    steeringDirective(directToolName?: string, opts?: {
+        subTask?: boolean;
+    }): string;
     /**
      * Execute every **remaining** step and lay the results out as one bundle.
      *
@@ -159,7 +244,9 @@ export declare class ScenarioReplayPlan {
      * Skipping instead would drop the step *and* stop threading `respParams`, so
      * every later step reading from it fails too.
      */
-    composeBundle(maxChars: number, execute: ExecuteStep, recordedOutputFor?: RecordedOutputFor, onStep?: StepObserver): Promise<ComposeResult>;
+    composeBundle(maxChars: number, execute: ExecuteStep, recordedOutputFor?: RecordedOutputFor, onStep?: StepObserver, opts?: {
+        handover?: boolean;
+    }): Promise<ComposeResult>;
     /**
      * Run the whole plan from the current cursor, advancing it as it goes.
      *
@@ -174,8 +261,18 @@ export declare class ScenarioReplayPlan {
      * 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): Promise<ComposeResult & {
+    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 & {
         partial: boolean;
+        stopped?: PlanStop;
     }>;
 }
 //# sourceMappingURL=plan.d.ts.map