@basein/runner 0.2.0 → 0.2.1

package/dist/replay/coverage.js

@@ -34,11 +34,11 @@ export function reachOf(toolName, wrapped, allow) {
 export function modeFor(steps, wrapped, allow) {
     if (steps.length === 0)
         return "none";
-    return steps.every((s) => reachOf(s.toolName, wrapped, allow) === "direct") ? "direct" : "steer";
+    return steps.every((s) => reachOf(s.toolName ?? "", wrapped, allow) === "direct") ? "direct" : "steer";
 }
 /** Per-step reach, in step order — what `plan.armed` logs and `bir doctor` shows. */
 export function coverageOf(steps, wrapped, allow) {
-    return steps.map((s) => reachOf(s.toolName, wrapped, allow));
+    return steps.map((s) => reachOf(s.toolName ?? "", wrapped, allow));
 }
 /**
  * Parse `BIR_REPLAY_ALLOW_SERVERS`. Unset (or empty) means *every wrapped

package/dist/replay/derive.d.ts

@@ -23,7 +23,18 @@
  */
 import type { ParamsSchema } from "./types.js";
 export declare const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
-export interface DeriveOptions {
+/** The call the agent was about to make when a plan armed mid-task. */
+export interface LiveCall {
+    toolName: string;
+    /** Redacted and capped, exactly as the probe sent it. */
+    toolInput: string;
+}
+/** What a turn can tell derivation beyond its prompt (segmented.md R-PARAM-2). */
+export interface DeriveContext {
+    liveCall?: LiveCall;
+    recentResults?: string[];
+}
+export interface DeriveOptions extends DeriveContext {
     prompt: string;
     intent: string;
     paramsObject: ParamsSchema | null;
@@ -42,12 +53,20 @@ export interface DeriveResult {
     model?: string;
     inputTokens?: number;
     outputTokens?: number;
+    /**
+     * Targets that came back `null` (segmented.md R-PARAM-3). Non-empty means the
+     * plan must not run: the turn does not say what this task is to act on.
+     */
+    missing: string[];
+    /** Settings filled from their recorded sample (R-PARAM-2). */
+    sampled: string[];
 }
 /**
  * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
  * often than they emit it bare, and a failed parse here costs a whole replay.
  */
 export declare function extractJsonObject(text: string): string | undefined;
+export declare function buildExtractionPrompt(prompt: string, intent: string, schema: ParamsSchema, ctx?: DeriveContext): string;
 /**
  * Derive the scenario's parameters from `prompt`. Never throws: every failure
  * path resolves with the recorded sample values, because a replay with stale

package/dist/replay/derive.js

@@ -32,6 +32,10 @@ function sampleValues(schema) {
         out[key] = schema[key].sampleValue;
     return out;
 }
+/** A parameter with no kind reads as a target (segmented.md R-PARAM-3). */
+function isTarget(schema, key) {
+    return schema[key]?.kind !== "setting";
+}
 /**
  * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
  * often than they emit it bare, and a failed parse here costs a whole replay.
@@ -66,24 +70,40 @@ export function extractJsonObject(text) {
     }
     return undefined;
 }
-function buildExtractionPrompt(prompt, intent, schema) {
+export function buildExtractionPrompt(prompt, intent, schema, ctx = {}) {
+    // Each parameter wears its kind, because the last rule below treats the two
+    // differently and the model cannot tell them apart from the name alone
+    // (segmented.md R-PARAM-2).
     const descriptions = Object.keys(schema)
         .map((key) => {
         const { description, sampleValue } = schema[key];
-        return `- ${key}: ${description} (sample: ${JSON.stringify(sampleValue)})`;
+        const kind = isTarget(schema, key) ? "target" : "setting";
+        return `- ${key} (${kind}): ${description} (sample: ${JSON.stringify(sampleValue)})`;
     })
         .join("\n");
+    // The call the agent was about to make is the most specific thing the turn
+    // says about a target — more specific than the prompt, which may not mention
+    // it at all (R-PARAM-8).
+    const live = ctx.liveCall
+        ? `\nThe agent was about to call ${ctx.liveCall.toolName} with ${ctx.liveCall.toolInput}.\n`
+        : "";
+    const results = (ctx.recentResults ?? []).filter((r) => r.trim().length > 0);
+    const recent = results.length > 0
+        ? `\nRecent tool results from this task, oldest first:\n${results
+            .map((r) => `\`\`\`\n${r}\n\`\`\``)
+            .join("\n")}\n`
+        : "";
     return `You are extracting parameter values from a user prompt to execute a pre-defined scenario.
 
 Scenario intent: ${intent}
-
+${live}
 Parameters needed (with sample values from past runs):
 ${descriptions}
 
 User prompt:
 ${prompt}
-
-Extract the parameter values from the user prompt. If a value is not explicitly mentioned, infer a reasonable default from the sample values above.
+${recent}
+Extract the parameter values. A setting you cannot find takes its sample value. A target you cannot find in the prompt, the reasoning, the call or the results is null — never invent it and never copy the sample.
 
 Respond ONLY with a valid JSON object mapping each parameter name to its value. No markdown fences, no prose.
 Example: { "directory": "src/utils", "pattern": "*.ts" }`;
@@ -98,10 +118,19 @@ export async function deriveParameters(opts) {
     const schema = opts.paramsObject ?? {};
     const keys = Object.keys(schema);
     if (keys.length === 0)
-        return { params: {}, costUsd: 0, derived: false };
+        return { params: {}, costUsd: 0, derived: false, missing: [], sampled: [] };
     const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    // No key is a supported configuration, and `derived: false` is how the caller
+    // tells it apart from a real extraction: it declines any scenario that has a
+    // target and arms an all-settings one on its recorded values (R-PARAM-5).
     if (!apiKey)
-        return { params: sampleValues(schema), costUsd: 0, derived: false };
+        return {
+            params: sampleValues(schema),
+            costUsd: 0,
+            derived: false,
+            missing: [],
+            sampled: keys,
+        };
     const model = opts.model ?? process.env.BIR_DERIVE_MODEL ?? DEFAULT_DERIVE_MODEL;
     const doFetch = opts.fetchImpl ?? fetch;
     const res = await doFetch(ANTHROPIC_URL, {
@@ -115,7 +144,13 @@ export async function deriveParameters(opts) {
             model,
             max_tokens: 2024,
             messages: [
-                { role: "user", content: buildExtractionPrompt(opts.prompt, opts.intent, schema) },
+                {
+                    role: "user",
+                    content: buildExtractionPrompt(opts.prompt, opts.intent, schema, {
+                        liveCall: opts.liveCall,
+                        recentResults: opts.recentResults,
+                    }),
+                },
             ],
         }),
         signal: opts.signal,
@@ -155,12 +190,34 @@ export async function deriveParameters(opts) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("derive returned a non-object");
     }
-    // A missing or null key falls back to its recorded sample, so a partial
-    // extraction still yields a runnable parameter set.
+    // A setting nobody stated takes its recorded sample — that is what a setting
+    // is. A target nobody stated stays null and is named in `missing`, and the
+    // caller declines the plan (segmented.md R-PARAM-2, R-PARAM-3). Copying the
+    // sample here is exactly the guess the design forbids: it is how a replay
+    // ends up querying last quarter's region because this prompt named no region.
+    const missing = [];
+    const sampled = [];
     for (const key of keys) {
-        if (parsed[key] === null || parsed[key] === undefined)
+        if (parsed[key] !== null && parsed[key] !== undefined)
+            continue;
+        if (isTarget(schema, key)) {
+            parsed[key] = null;
+            missing.push(key);
+        }
+        else {
             parsed[key] = schema[key].sampleValue;
+            sampled.push(key);
+        }
     }
-    return { params: parsed, costUsd, derived: true, model, inputTokens, outputTokens };
+    return {
+        params: parsed,
+        costUsd,
+        derived: true,
+        model,
+        inputTokens,
+        outputTokens,
+        missing,
+        sampled,
+    };
 }
 //# sourceMappingURL=derive.js.map

package/dist/replay/flatten.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Flattening calls into frames (segmented.md 10.6).
+ *
+ * A chain may hold a **call**: one row that says "here the agent does this
+ * sub-task", answered by a recorded scenario the service inlines into the
+ * payload. Running it is not a second plan. It is one plan over one flat list
+ * of steps, in which some steps belong to another scenario and run with *its*
+ * parameters, *its* intent and *its* accumulated values.
+ *
+ * That is what a **frame** is: the scope one stretch of steps runs in. Frame 0
+ * is the caller's own. Entering a called frame evaluates the call's
+ * `paramMapLogic` to build the segment's parameters; leaving it evaluates
+ * `resultMapLogic` and merges the result back into the caller's `respParams`
+ * (R-CALL-29).
+ *
+ * Everything downstream reads the flat list rather than the chain: the gates
+ * judge the steps that will really run (R-CALL-30), recorded outputs come from
+ * the right recording and range (R-CALL-31), and a failure is reported on the
+ * scenario that owns the step (R-CALL-13).
+ *
+ * The flattener itself decides nothing about *which* segment answers a call —
+ * the service did that long before this payload was built. It only lays out
+ * what it was served, and stops in front of anything it cannot run.
+ */
+import type { SerializedScenario, SerializedScenarioStep, CallUnusable } from "./types.js";
+import type { ParamsSchema } from "./types.js";
+/** The scope one stretch of steps runs in. Frame 0 is the caller's own. */
+export interface Frame {
+    id: number;
+    /** 0 for the caller, 1 for a segment it calls, 2 for one that segment calls. */
+    depth: number;
+    scenarioId: string;
+    runId: string;
+    /** The recorded range the frame's outputs come from. Null means the whole run. */
+    stepFrom: number | null;
+    stepTo: number | null;
+    /** The intent the frame's step logic runs with (R-INTENT-12). */
+    intent: string;
+    parent?: Frame;
+    /** The caller's chain `stepIndex` of the call row that opened this frame. */
+    callerStepIndex?: number;
+    callIntent?: string;
+    paramMapLogic?: string;
+    resultMapLogic?: string;
+    segmentId?: string;
+    /** The inlined segment's `chainRevision` as served (R-CALL-13). */
+    chainRevision?: number;
+    /** The segment's own parameters, for the settings a mapping omits (R-CALL-21). */
+    paramsObject?: ParamsSchema | null;
+    /** Filled by the plan when the frame is entered. */
+    parameters?: Record<string, unknown>;
+    respParams: Record<string, unknown>;
+}
+/** One step that will really run, with the frame it runs in. */
+export interface FlatEntry {
+    scenarioId: string;
+    runId: string;
+    stepFrom: number | null;
+    stepTo: number | null;
+    /** The owning scenario's own `scenario_steps.step_index`, not a flat position. */
+    stepIndex: number;
+    /** Always a tool row: a call row becomes a frame, or a stop. */
+    step: SerializedScenarioStep;
+    frame: Frame;
+    depth: number;
+    /** First / last entry of its frame — where the two mapping bodies run. */
+    first: boolean;
+    last: boolean;
+}
+/** Why the flat list stops short, and which call row said so. */
+export interface FlatStop {
+    kind: "unusable";
+    reason: CallUnusable;
+    /** The scenario whose chain holds the call row. */
+    scenarioId: string;
+    /** That call row's own `stepIndex`. */
+    stepIndex: number;
+    segmentId?: string | null;
+    callIntent?: string | null;
+}
+export interface FlatChain {
+    entries: FlatEntry[];
+    /** Flat position the plan stops in front of. Undefined means the whole chain. */
+    stopAt?: number;
+    stopReason?: FlatStop;
+}
+/**
+ * Mirrors the service's `SEGMENT_MAX_DEPTH`. A constant, not a setting: one
+ * call row holds one answer, which is only correct because a call inside a
+ * level-two segment is never answered (R-CALL-12).
+ */
+export declare const MAX_CALL_DEPTH = 2;
+/**
+ * Lay a served chain out as one flat list of steps, with a frame per call.
+ *
+ * Stops at the first call it cannot run. The stop is *clamped* to the start of
+ * the outermost called frame that contains it: a plan must never run half a
+ * sub-task and leave its `resultMapLogic` unevaluated, because the caller's
+ * later steps read what that body returns (R-CALL-30).
+ */
+export declare function flattenChain(scenario: SerializedScenario, opts?: {
+    maxDepth?: number;
+    /** The range a segment armed on its own covers (its own recording). */
+    range?: {
+        stepFrom: number;
+        stepTo: number;
+    } | null;
+}): FlatChain;
+/**
+ * Move a stop back to the start of the outermost called frame it falls in
+ * (R-CALL-30, 10.6 step 3).
+ *
+ * Used for the known-bad-step gate, which judges entries: a parked step in the
+ * middle of a sub-task stops the plan in front of the *sub-task*, not in front
+ * of the step, because stopping inside it would skip the body that hands its
+ * results back.
+ */
+export declare function clampToFrameStart(entries: readonly FlatEntry[], index: number): number;
+/**
+ * One frame per chain, for a payload with no calls in it and for the callers
+ * that build a plan by hand (tests, `bir replay`). Byte for byte the old
+ * behaviour: one frame, one scenario, one range.
+ */
+export declare function flatEntriesOf(scenario: SerializedScenario): FlatEntry[];
+//# sourceMappingURL=flatten.d.ts.map

package/dist/replay/flatten.js

@@ -0,0 +1,182 @@
+/**
+ * Flattening calls into frames (segmented.md 10.6).
+ *
+ * A chain may hold a **call**: one row that says "here the agent does this
+ * sub-task", answered by a recorded scenario the service inlines into the
+ * payload. Running it is not a second plan. It is one plan over one flat list
+ * of steps, in which some steps belong to another scenario and run with *its*
+ * parameters, *its* intent and *its* accumulated values.
+ *
+ * That is what a **frame** is: the scope one stretch of steps runs in. Frame 0
+ * is the caller's own. Entering a called frame evaluates the call's
+ * `paramMapLogic` to build the segment's parameters; leaving it evaluates
+ * `resultMapLogic` and merges the result back into the caller's `respParams`
+ * (R-CALL-29).
+ *
+ * Everything downstream reads the flat list rather than the chain: the gates
+ * judge the steps that will really run (R-CALL-30), recorded outputs come from
+ * the right recording and range (R-CALL-31), and a failure is reported on the
+ * scenario that owns the step (R-CALL-13).
+ *
+ * The flattener itself decides nothing about *which* segment answers a call —
+ * the service did that long before this payload was built. It only lays out
+ * what it was served, and stops in front of anything it cannot run.
+ */
+/**
+ * Mirrors the service's `SEGMENT_MAX_DEPTH`. A constant, not a setting: one
+ * call row holds one answer, which is only correct because a call inside a
+ * level-two segment is never answered (R-CALL-12).
+ */
+export const MAX_CALL_DEPTH = 2;
+/**
+ * Lay a served chain out as one flat list of steps, with a frame per call.
+ *
+ * Stops at the first call it cannot run. The stop is *clamped* to the start of
+ * the outermost called frame that contains it: a plan must never run half a
+ * sub-task and leave its `resultMapLogic` unevaluated, because the caller's
+ * later steps read what that body returns (R-CALL-30).
+ */
+export function flattenChain(scenario, opts = {}) {
+    const maxDepth = opts.maxDepth ?? MAX_CALL_DEPTH;
+    const entries = [];
+    let frameId = 0;
+    let stopAt;
+    let stopReason;
+    const root = {
+        id: frameId++,
+        depth: 0,
+        scenarioId: scenario.id,
+        runId: scenario.runId,
+        stepFrom: opts.range?.stepFrom ?? null,
+        stepTo: opts.range?.stepTo ?? null,
+        intent: scenario.intent ?? "",
+        respParams: {},
+    };
+    /** The entry a frame's steps start at, for the clamp. */
+    const frameStart = new Map();
+    const walk = (steps, frame, stack) => {
+        for (const step of steps) {
+            if (stopAt !== undefined)
+                return;
+            if (step.kind !== "segment") {
+                entries.push({
+                    scenarioId: frame.scenarioId,
+                    runId: frame.runId,
+                    stepFrom: frame.stepFrom,
+                    stepTo: frame.stepTo,
+                    stepIndex: step.stepIndex,
+                    step,
+                    frame,
+                    depth: frame.depth,
+                    first: false,
+                    last: false,
+                });
+                continue;
+            }
+            // A call the service already marked unrunnable, a third level, or a
+            // segment already on this stack (which would be a cycle): all the same
+            // thing to a plan — it stops here and the agent takes over (R-CALL-29).
+            const cycles = !!step.segment && stack.includes(step.segment.id);
+            const tooDeep = frame.depth + 1 > maxDepth;
+            const reason = step.unusable
+                ? step.unusable
+                : !step.segment || cycles || tooDeep
+                    ? "depth"
+                    : undefined;
+            if (reason) {
+                // The clamp: a stop inside a called frame moves back to the first entry
+                // of the outermost called frame containing it, so the caller never runs
+                // part of a sub-task (R-CALL-30).
+                let outermost = frame;
+                while (outermost && outermost.depth > 1)
+                    outermost = outermost.parent;
+                stopAt =
+                    frame.depth > 0 && outermost
+                        ? (frameStart.get(outermost.id) ?? entries.length)
+                        : entries.length;
+                stopReason = {
+                    kind: "unusable",
+                    reason,
+                    scenarioId: frame.scenarioId,
+                    stepIndex: step.stepIndex,
+                    segmentId: step.segmentId ?? step.segment?.id ?? null,
+                    callIntent: step.callIntent ?? null,
+                };
+                return;
+            }
+            const segment = step.segment;
+            const child = {
+                id: frameId++,
+                depth: frame.depth + 1,
+                scenarioId: segment.id,
+                runId: segment.runId,
+                stepFrom: segment.stepFrom,
+                stepTo: segment.stepTo,
+                intent: segment.intent ?? "",
+                parent: frame,
+                callerStepIndex: step.stepIndex,
+                callIntent: step.callIntent ?? undefined,
+                paramMapLogic: step.paramMapLogic ?? undefined,
+                resultMapLogic: step.resultMapLogic ?? undefined,
+                segmentId: segment.id,
+                chainRevision: segment.chainRevision,
+                paramsObject: segment.paramsObject ?? null,
+                respParams: {},
+            };
+            frameStart.set(child.id, entries.length);
+            walk(segment.steps ?? [], child, [...stack, segment.id]);
+        }
+    };
+    frameStart.set(root.id, 0);
+    walk(scenario.steps ?? [], root, [scenario.id]);
+    // `first` / `last` per frame, marked once the whole list is known: they are
+    // where the two mapping bodies run. A frame's entries are not necessarily
+    // contiguous — a call sitting in the middle of a chain interleaves its
+    // callee's entries with its own — so these are the frame's first and last
+    // entries overall, never the edges of a run of them.
+    const firstOf = new Map();
+    const lastOf = new Map();
+    entries.forEach((entry, index) => {
+        if (!firstOf.has(entry.frame.id))
+            firstOf.set(entry.frame.id, index);
+        lastOf.set(entry.frame.id, index);
+    });
+    entries.forEach((entry, index) => {
+        entry.first = firstOf.get(entry.frame.id) === index;
+        entry.last = lastOf.get(entry.frame.id) === index;
+    });
+    return { entries, stopAt, stopReason };
+}
+/**
+ * Move a stop back to the start of the outermost called frame it falls in
+ * (R-CALL-30, 10.6 step 3).
+ *
+ * Used for the known-bad-step gate, which judges entries: a parked step in the
+ * middle of a sub-task stops the plan in front of the *sub-task*, not in front
+ * of the step, because stopping inside it would skip the body that hands its
+ * results back.
+ */
+export function clampToFrameStart(entries, index) {
+    const at = entries[index];
+    if (!at || at.depth === 0)
+        return index;
+    let outermost = at.frame;
+    while (outermost && outermost.depth > 1)
+        outermost = outermost.parent;
+    if (!outermost)
+        return index;
+    for (let i = 0; i < entries.length; i += 1) {
+        if (entries[i].frame.id === outermost.id)
+            return i;
+    }
+    return index;
+}
+/**
+ * One frame per chain, for a payload with no calls in it and for the callers
+ * that build a plan by hand (tests, `bir replay`). Byte for byte the old
+ * behaviour: one frame, one scenario, one range.
+ */
+export function flatEntriesOf(scenario) {
+    return flattenChain(scenario).entries;
+}
+//# sourceMappingURL=flatten.js.map

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