@basein/runner 0.2.0 → 0.2.2

package/dist/control/transcript.d.ts

@@ -18,6 +18,46 @@
  * ever required for a recording to be valid — a missing context is a missing
  * nicety, not a failed step.
  */
+/**
+ * The last `n` tool results of the *current* prompt, redacted and capped.
+ *
+ * Derivation reads them because a target is often named by an earlier step's
+ * output and never by the prompt — "the worst service" is a name the agent
+ * learned from a tool, not from the user (segmented.md R-PARAM-2).
+ *
+ * "This prompt" is everything after the last user-role line that carries text.
+ * A transcript compacted mid-turn yields whatever follows that line, which may
+ * be nothing; a transcript with no user prompt at all (a run opened by a proxy
+ * step) yields nothing. Results with `is_error: true` are kept: a failure is
+ * still the agent's evidence about what it is working on.
+ */
+export declare function recentToolResults(transcriptPath: string | undefined, n?: number, maxBytes?: number): string[];
+/** Which rung of R-INTENT-1 a step's intent came from. */
+export type IntentSource = "text" | "thinking" | "tool";
+/** What the agent meant by a tool call, and where that was read from. */
+export interface ToolUseIntent {
+    text: string;
+    source: "text" | "thinking";
+}
+/**
+ * The intent of one tool call, read the way the transcript really stores it
+ * (segmented.md R-INTENT-3).
+ *
+ * Claude Code writes **one line per content block**, and every line of a
+ * multi-block assistant message repeats the same `message.id`. So the `text`
+ * block, the `thinking` block and the `tool_use` block of one message are three
+ * separate lines. {@link contextForToolUse} reads only the line holding the
+ * `tool_use` block, which is why it has returned "" in practice since it was
+ * written: the text is always on a sibling line.
+ *
+ * Order is R-INTENT-1: the written text, else the thinking text, else nothing —
+ * and the caller then lets the *service* build a line from the tool name and
+ * arguments, so the runner never invents one.
+ *
+ * `sources` is `BIR_INTENT_SOURCES`: a source not in the set is skipped and the
+ * next rung tried. It governs only what may be *sent*; it never stops a probe.
+ */
+export declare function intentForToolUse(transcriptPath: string | undefined, toolUseId: string, sources?: ReadonlySet<IntentSource>): ToolUseIntent | undefined;
 /** The assistant text that accompanied `toolUseId`, or "" when unavailable. */
 export declare function contextForToolUse(transcriptPath: string | undefined, toolUseId: string): string;
 /** The last assistant text in the transcript — the turn's final answer. */

package/dist/control/transcript.js

@@ -19,6 +19,8 @@
  * nicety, not a failed step.
  */
 import { readFileSync } from "node:fs";
+import { redactText } from "../record/redact.js";
+import { truncateString } from "../record/truncate.js";
 function readLines(transcriptPath) {
     let raw;
     try {
@@ -56,6 +58,109 @@ function textOf(blocks) {
         .join("\n")
         .trim();
 }
+/** One `tool_result` block's payload, flattened to text. */
+function resultTextOf(block) {
+    const content = block.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return textOf(content);
+    if (typeof block.text === "string")
+        return block.text;
+    return "";
+}
+/**
+ * The last `n` tool results of the *current* prompt, redacted and capped.
+ *
+ * Derivation reads them because a target is often named by an earlier step's
+ * output and never by the prompt — "the worst service" is a name the agent
+ * learned from a tool, not from the user (segmented.md R-PARAM-2).
+ *
+ * "This prompt" is everything after the last user-role line that carries text.
+ * A transcript compacted mid-turn yields whatever follows that line, which may
+ * be nothing; a transcript with no user prompt at all (a run opened by a proxy
+ * step) yields nothing. Results with `is_error: true` are kept: a failure is
+ * still the agent's evidence about what it is working on.
+ */
+export function recentToolResults(transcriptPath, n = 5, maxBytes = 2048) {
+    if (!transcriptPath || n <= 0)
+        return [];
+    const lines = readLines(transcriptPath);
+    let start = -1;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const role = lines[i].message?.role ?? lines[i].type;
+        if (role !== "user")
+            continue;
+        if (textOf(blocksOf(lines[i]))) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return [];
+    const out = [];
+    for (let i = start; i < lines.length; i += 1) {
+        const role = lines[i].message?.role ?? lines[i].type;
+        if (role !== "user")
+            continue;
+        for (const block of blocksOf(lines[i])) {
+            if (block.type !== "tool_result")
+                continue;
+            const text = resultTextOf(block);
+            if (text)
+                out.push(text);
+        }
+    }
+    return out.slice(-n).map((t) => truncateString(redactText(t), maxBytes));
+}
+/**
+ * The intent of one tool call, read the way the transcript really stores it
+ * (segmented.md R-INTENT-3).
+ *
+ * Claude Code writes **one line per content block**, and every line of a
+ * multi-block assistant message repeats the same `message.id`. So the `text`
+ * block, the `thinking` block and the `tool_use` block of one message are three
+ * separate lines. {@link contextForToolUse} reads only the line holding the
+ * `tool_use` block, which is why it has returned "" in practice since it was
+ * written: the text is always on a sibling line.
+ *
+ * Order is R-INTENT-1: the written text, else the thinking text, else nothing —
+ * and the caller then lets the *service* build a line from the tool name and
+ * arguments, so the runner never invents one.
+ *
+ * `sources` is `BIR_INTENT_SOURCES`: a source not in the set is skipped and the
+ * next rung tried. It governs only what may be *sent*; it never stops a probe.
+ */
+export function intentForToolUse(transcriptPath, toolUseId, sources = new Set(["text", "thinking", "tool"])) {
+    if (!transcriptPath || !toolUseId)
+        return undefined;
+    const lines = readLines(transcriptPath);
+    const holder = lines.find((line) => blocksOf(line).some((b) => b.type === "tool_use" && b.id === toolUseId));
+    if (!holder)
+        return undefined;
+    // No `message.id` means an older transcript, or a hand-written fixture: the
+    // line is the whole message and there are no siblings to gather.
+    const messageId = holder.message?.id;
+    const siblings = messageId
+        ? lines.filter((line) => line.message?.id === messageId)
+        : [holder];
+    if (sources.has("text")) {
+        const text = textOf(siblings.flatMap((line) => blocksOf(line)));
+        if (text)
+            return { text, source: "text" };
+    }
+    if (sources.has("thinking")) {
+        const thinking = siblings
+            .flatMap((line) => blocksOf(line))
+            .filter((b) => b.type === "thinking" && typeof b.thinking === "string")
+            .map((b) => b.thinking)
+            .join("\n")
+            .trim();
+        if (thinking)
+            return { text: thinking, source: "thinking" };
+    }
+    return undefined;
+}
 /** The assistant text that accompanied `toolUseId`, or "" when unavailable. */
 export function contextForToolUse(transcriptPath, toolUseId) {
     if (!transcriptPath || !toolUseId)

package/dist/record/recorder.d.ts

@@ -5,18 +5,48 @@
  * service needs no new endpoints for v1: a BaseInstRunner run is the same row
  * shape as an RRepeat one, discriminated only by `metadata.recorder`.
  */
-import type { ExecutionStage, ExecutionStepResult } from "../replay/types.js";
+import type { ExecutionStage, ExecutionStepResult, FallbackKind } from "../replay/types.js";
+export interface StartRunOptions {
+    fallbackOf?: {
+        scenarioId: string;
+        stepIndex: number;
+    };
+}
 export interface RunMetrics {
     costUsd?: number;
     durationMs?: number;
 }
 export interface Recorder {
-    /** Create the run; returns the client-generated runId synchronously. */
-    startRun(input: string, metadata?: Record<string, unknown>): string;
+    /**
+     * Create the run; returns the client-generated runId synchronously.
+     *
+     * `options.fallbackOf` marks a *fragment* (fallbk.md D7): the model's own work
+     * after a calculated scenario handed it the task at `stepIndex`. The service
+     * never prompt-matches a fragment.
+     */
+    startRun(input: string, metadata?: Record<string, unknown>, options?: StartRunOptions): string;
     recordToolSelected(runId: string, stepIndex: number, d: {
         toolName: string;
         toolInput: string;
         context?: string;
+        /**
+         * The thinking text this call was chosen in, when there was no written
+         * text (segmented.md R-INTENT-1). It travels to the service only to be
+         * embedded and is never stored as text (R-INTENT-2), which is why it is
+         * carried apart from `context` rather than folded into it.
+         */
+        intent?: {
+            text: string;
+            source: "thinking";
+        };
+        /**
+         * Set when a plan executed this step, to the plan's scenario id
+         * (R-INTENT-7). The service stores such a step without a vector, so the
+         * system's own replays never count as recurrences of the work.
+         */
+        metadata?: {
+            pinnedBy: string;
+        };
     }): string;
     recordToolResponse(runId: string, stepIndex: number, d: {
         toolName: string;
@@ -36,18 +66,145 @@ export interface Recorder {
  * callers must stop recording it. What the caller does *instead* of recording is
  * v2's subject (docs/calculatedReplay.md); stopping is mandatory either way.
  */
+/** Which of a segment's two keys scored against the live step (R-OUT-3). */
+export type MatchKey = "intent" | "firstStep";
+/** The cheap model's answer about one live step and one segment (R-VERIFY-1). */
+export interface MatchVerdict {
+    model: string;
+    verdict: "same" | "different" | "skipped";
+    reason?: string;
+}
+/** Where a handed-out segment sits in its recording (R-OUT-8). */
+export interface MatchSegment {
+    runId: string;
+    stepFrom: number;
+    stepTo: number;
+    /** `tool_selected` rows of the recording before `stepFrom` (R-OUT-6). */
+    firstPosition: number;
+    hitCount?: number;
+}
 export interface RunMatch {
     runId: string;
     scenarioId: string | null;
     similarity: number;
     scenario: Record<string, unknown> | null;
     executionTicket?: string;
+    /**
+     * Server policy for this scenario (fallbk.md D8). A step whose `failureCount`
+     * is greater than `maxStepFailures` is handed to the model, not attempted.
+     * Absent from an older service, which means never.
+     */
+    fallback?: {
+        maxStepFailures: number;
+    };
+    /**
+     * What kind of row matched (segmented.md R-OUT-7). Absent from an older
+     * service, and then read as `scenario`.
+     */
+    kind?: "scenario" | "segment";
+    segment?: MatchSegment;
+    key?: MatchKey;
+    verified?: MatchVerdict;
+    /** The frozen name, beside the runtime `intent` the plan runs on (R-INTENT-12). */
+    intentName?: string;
 }
 /** Optional capability: `null` means "fresh run, keep recording". */
 export interface MatchAware {
     getMatch(runId: string): Promise<RunMatch | null>;
 }
 export declare function isMatchAware(r: Recorder): r is Recorder & MatchAware;
+/**
+ * Optional capability: whether the service actually created a run.
+ *
+ * A fragment's create call can answer `id: null` — a hand-over at the same step
+ * was recorded before, and this one is a hit on it — and then every step post
+ * for the id would 404. Resolves true when a run exists (or nobody can say).
+ */
+/** What the create call said about a run: fresh, or a hit on a fragment. */
+export interface RunCreation {
+    created: boolean;
+    /** Set when this was a hit on an existing fragment (R-FALL-7, R-HIT-7). */
+    fragmentOf?: {
+        runId: string;
+    };
+}
+export interface RunCreationAware {
+    runCreated(runId: string): Promise<RunCreation>;
+}
+export declare function isRunCreationAware(r: Recorder): r is Recorder & RunCreationAware;
+/** What a ReAct iteration sends to find a scenario by its intent (fallbk.md §Runner 4). */
+export interface IntentMatchRequest {
+    /**
+     * The step's intent (segmented.md R-INTENT-1). May be empty: a call made with
+     * no reasoning still probes, and the service builds a line from the tool name
+     * and arguments instead (R-HIT-4).
+     */
+    text: string;
+    currentToolName?: string;
+    /** Scenario ids already armed this turn. */
+    exclude?: string[];
+    /** Which rung the text came from (R-INTENT-3). */
+    source?: IntentSourceName;
+    /** The same value as `currentToolName`; what the new server reads (R-HIT-6). */
+    toolName?: string;
+    /** Redacted and capped arguments of the call about to be made (R-HIT-4). */
+    toolInput?: string;
+    /** The turn's identity, fixed for its whole life (R-HIT-6). */
+    turnId?: string;
+    /** `run.ordering.next` — where this call sits in the turn. */
+    stepPosition?: number;
+    /** Recordings this turn must not count hits against (R-HIT-7). */
+    excludeRuns?: string[];
+    /** Per recording a plan of this turn came from, the largest position (R-OUT-6). */
+    ranThrough?: Array<{
+        runId: string;
+        position: number;
+        scenarioId?: string;
+    }>;
+    /** Present only with `BIR_SEGMENT_ARM` (R-OUT-9, R-OUT-10). */
+    acceptSegments?: boolean;
+    /** Always true from this runner (R-CALL-28). */
+    supportsCalls?: boolean;
+}
+/** Which text a step's intent came from. */
+export type IntentSourceName = "text" | "thinking" | "tool";
+/** One recorded step a live step matched (R-HIT-6). */
+export interface StepHit {
+    runId: string;
+    stepIndex: number;
+    similarity: number;
+    hitCount?: number;
+}
+/** What a segment *would* have armed, when no ticket was issued (R-OUT-9). */
+export interface SegmentWouldArm {
+    scenarioId: string;
+    runId: string;
+    key?: MatchKey;
+    similarity: number;
+    band?: string;
+    verified?: MatchVerdict;
+    tool?: string;
+    firstTool?: string;
+    stepFrom?: number;
+    stepTo?: number;
+    hitCount?: number;
+}
+/**
+ * The whole answer to a probe, not just its match. The counting fields are what
+ * make the observe-only period readable (R-OUT-10), so they must survive the
+ * trip rather than being discarded with the rest of the body.
+ */
+export interface IntentMatchAnswer {
+    matched: RunMatch | null;
+    stepHit?: StepHit | null;
+    bestStepSimilarity?: number;
+    segmentWouldArm?: SegmentWouldArm;
+}
+/** Optional capability: intent matching needs a service. */
+export interface IntentMatcher {
+    matchIntent(req: IntentMatchRequest): Promise<IntentMatchAnswer | null>;
+}
+export declare function isIntentMatcher(r: Recorder): r is Recorder & IntentMatcher;
 /**
  * What a matched turn actually cost, reported once per match
  * (docs/calculatedReplay.md §11).
@@ -61,7 +218,7 @@ export interface ExecutionReport {
     scenarioId: string;
     /** The match's claim token. It *is* the execution row's id, so a doubled report books once. */
     ticket?: string;
-    outcome: "steered_full" | "diverged" | "not_steered" | "failed";
+    outcome: "steered_full" | "diverged" | "not_steered" | "failed" | "fell_back";
     /** The derivation call — the only tokens replay itself spends. */
     deriveCostUsd: number;
     /** The live turn, from the transcript usage delta. */
@@ -89,6 +246,23 @@ export interface ExecutionReport {
     errorStage?: ExecutionStage;
     errorStepIndex?: number;
     errorToolName?: string;
+    /** Where a `fell_back` execution handed over, and why (fallbk.md). */
+    fallbackStepIndex?: number;
+    fallbackKind?: FallbackKind;
+    /**
+     * False when another plan armed in this same turn, so this report's cost is
+     * not a measurement of what the task costs unaided (segmented.md R-MONEY-5).
+     * The service then adds no baseline sample from it. Absent means eligible,
+     * which is what every report said before this field existed.
+     */
+    baselineEligible?: boolean;
+    /**
+     * Segments of this plan's own recording that ran later in the same turn
+     * (segmented.md R-MONEY-4). The service freezes this row's baseline at what
+     * is left after their share, so one recording's steps are never counted in
+     * two baselines of one turn. The segments' own rows are untouched.
+     */
+    sharedWith?: string[];
 }
 /** Optional capability: reporting needs a service, and a NullRecorder has none. */
 export interface ScenarioReporter {

package/dist/record/recorder.js

@@ -8,6 +8,12 @@
 export function isMatchAware(r) {
     return typeof r.getMatch === "function";
 }
+export function isRunCreationAware(r) {
+    return typeof r.runCreated === "function";
+}
+export function isIntentMatcher(r) {
+    return typeof r.matchIntent === "function";
+}
 export function isScenarioReporter(r) {
     return typeof r.reportExecution === "function";
 }

package/dist/record/remote-recorder.d.ts

@@ -23,7 +23,7 @@
  * {@link RemoteRecorder.getMatch} is how they find out. v1 only stops; replay is v2.
  */
 import { type AuthSession } from "../auth/client.js";
-import type { ExecutionReport, Recorder, RunMatch, RunMetrics } from "./recorder.js";
+import type { ExecutionReport, IntentMatchAnswer, IntentMatchRequest, Recorder, RunCreation, RunMatch, RunMetrics, StartRunOptions } from "./recorder.js";
 export interface RemoteRecorderOptions {
     baseUrl: string;
     session: AuthSession;
@@ -38,19 +38,37 @@ export declare class RemoteRecorder implements Recorder {
     private readonly chains;
     /** runId → the similar-prompt outcome of its create call. */
     private readonly matches;
+    /** runId → what the create call said (not created: a hit, nothing to record). */
+    private readonly created;
     /**
      * Execution reports ride their own chain: a matched turn has no run on the
      * service (that is what a match means), so there is no run chain to append to.
      */
     private readonly executionChainKey;
     constructor(opts: RemoteRecorderOptions);
-    startRun(input: string, metadata?: Record<string, unknown>): string;
+    startRun(input: string, metadata?: Record<string, unknown>, options?: StartRunOptions): string;
+    /** What the create call said. "Created" for an id this recorder never opened. */
+    runCreated(runId: string): Promise<RunCreation>;
+    /**
+     * Match a ReAct iteration's reasoning against the caller's scenario intents
+     * (fallbk.md §Runner 4). Awaited, not queued: the caller is a `PreToolUse`
+     * holding a budget, and the answer decides what that hook says. A service that
+     * predates the route (404) or any failure is a miss.
+     */
+    matchIntent(req: IntentMatchRequest): Promise<IntentMatchAnswer | null>;
     /** Await the similar-prompt match for a run's create call (null = fresh run). */
     getMatch(runId: string): Promise<RunMatch | null>;
     recordToolSelected(runId: string, stepIndex: number, data: {
         toolName: string;
         toolInput: string;
         context?: string;
+        intent?: {
+            text: string;
+            source: "thinking";
+        };
+        metadata?: {
+            pinnedBy: string;
+        };
     }): string;
     recordToolResponse(runId: string, stepIndex: number, data: {
         toolName: string;

package/dist/record/remote-recorder.js

@@ -33,6 +33,8 @@ export class RemoteRecorder {
     chains = new Map();
     /** runId → the similar-prompt outcome of its create call. */
     matches = new Map();
+    /** runId → what the create call said (not created: a hit, nothing to record). */
+    created = new Map();
     /**
      * Execution reports ride their own chain: a matched turn has no run on the
      * service (that is what a match means), so there is no run chain to append to.
@@ -43,12 +45,16 @@ export class RemoteRecorder {
         this.session = opts.session;
         this.framework = opts.framework ?? "baseinstrunner";
     }
-    startRun(input, metadata) {
+    startRun(input, metadata, options) {
         const id = "run_" + randomUUID();
         let resolveMatch;
+        let resolveCreated;
         this.matches.set(id, new Promise((r) => {
             resolveMatch = r;
         }));
+        this.created.set(id, new Promise((r) => {
+            resolveCreated = r;
+        }));
         this.enqueue(id, async () => {
             try {
                 const body = await this.post("/recordings/runs", {
@@ -56,19 +62,60 @@ export class RemoteRecorder {
                     framework: this.framework,
                     input,
                     metadata,
+                    // A fragment (fallbk.md D7). Omitted, not null, so an older service
+                    // that does not know the field sees the body it always saw.
+                    ...(options?.fallbackOf ? { fallbackOf: options.fallbackOf } : {}),
+                    // A chain with calls is inlined for this runner rather than stopped in
+                    // front of its first call (segmented.md R-CALL-28).
+                    supportsCalls: true,
                 });
-                const matched = body && typeof body === "object"
-                    ? (body.matched ?? null)
-                    : null;
-                resolveMatch(matched);
+                const b = body && typeof body === "object"
+                    ? body
+                    : {};
+                resolveMatch(b.matched ?? null);
+                // `id: null` is the service saying it kept a run of its own. Which run
+                // that was matters: a turn must not count step hits against the
+                // recording it is itself a repeat of (R-HIT-7).
+                resolveCreated({ created: b.id !== null, fragmentOf: b.fragmentOf });
             }
             catch (err) {
                 resolveMatch(null); // fail-safe: on a create error, record normally
+                resolveCreated({ created: true });
                 throw err; // preserve enqueue's dropped-send logging
             }
         });
         return id;
     }
+    /** What the create call said. "Created" for an id this recorder never opened. */
+    async runCreated(runId) {
+        const pending = this.created.get(runId);
+        return pending ? await pending : { created: true };
+    }
+    /**
+     * Match a ReAct iteration's reasoning against the caller's scenario intents
+     * (fallbk.md §Runner 4). Awaited, not queued: the caller is a `PreToolUse`
+     * holding a budget, and the answer decides what that hook says. A service that
+     * predates the route (404) or any failure is a miss.
+     */
+    async matchIntent(req) {
+        try {
+            const body = await this.post("/scenarios/match-intent", req);
+            // The whole answer, not just `matched`: the counting fields are what make
+            // the observe-only period readable (segmented.md R-OUT-10), and an older
+            // server simply sends none of them (R-COMPAT-2).
+            const b = body && typeof body === "object" ? body : {};
+            return {
+                matched: b.matched ?? null,
+                stepHit: b.stepHit ?? null,
+                bestStepSimilarity: b.bestStepSimilarity,
+                segmentWouldArm: b.segmentWouldArm,
+            };
+        }
+        catch (err) {
+            logLine("replay.intent_match_failed", { error: errText(err), why: "treated as a miss" });
+            return null;
+        }
+    }
     /** Await the similar-prompt match for a run's create call (null = fresh run). */
     async getMatch(runId) {
         const pending = this.matches.get(runId);
@@ -76,13 +123,19 @@ export class RemoteRecorder {
     }
     recordToolSelected(runId, stepIndex, data) {
         const id = "step_" + randomUUID();
-        this.enqueue(runId, () => this.post(`/recordings/runs/${runId}/steps`, {
+        this.enqueue(runId, () => 
+        // `intent` and `metadata` are omitted, not nulled, when absent, so an
+        // older service sees the body it has always seen (segmented.md
+        // R-COMPAT-1).
+        this.post(`/recordings/runs/${runId}/steps`, {
             id,
             stepIndex,
             type: "tool_selected",
             toolName: data.toolName,
             toolInput: data.toolInput,
             context: data.context,
+            intent: data.intent,
+            metadata: data.metadata,
         }));
         return id;
     }
@@ -155,6 +208,10 @@ export class RemoteRecorder {
                 errorStage: report.errorStage,
                 errorStepIndex: report.errorStepIndex,
                 errorToolName: report.errorToolName,
+                fallbackStepIndex: report.fallbackStepIndex,
+                fallbackKind: report.fallbackKind,
+                baselineEligible: report.baselineEligible,
+                sharedWith: report.sharedWith,
             });
             const r = (body ?? {});
             const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
@@ -169,6 +226,8 @@ export class RemoteRecorder {
                 measured: report.measured,
                 steps: report.steps?.length,
                 stepsFailed: failed || undefined,
+                baselineEligible: report.baselineEligible === false ? false : undefined,
+                sharedWith: report.sharedWith?.length,
             });
         });
     }
@@ -177,6 +236,7 @@ export class RemoteRecorder {
         await (this.chains.get(runId) ?? Promise.resolve());
         this.chains.delete(runId);
         this.matches.delete(runId);
+        this.created.delete(runId);
         // Reports live on their own chain (a matched run has no run chain of its own
         // — the service created no run), so draining that chain is a separate step.
         await (this.chains.get(this.executionChainKey) ?? Promise.resolve());

package/dist/replay/bundle.d.ts

@@ -27,10 +27,19 @@ export interface BundleEntry {
 }
 /** Cap a computed input for inclusion in a bundle. */
 export declare function bundleInput(value: unknown): string;
+export interface AssembleOptions {
+    /** The plan stopped part-way and the model is to carry on (fallbk.md). */
+    handover?: boolean;
+    /**
+     * The plan was armed mid-task by intent (segmented.md R-OUT-13). Its results
+     * feed the agent's own task, which continues. `handover` wins over this.
+     */
+    subTask?: boolean;
+}
 /**
  * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
  */
-export declare function assembleBundle(entries: readonly BundleEntry[], maxChars: number): string;
+export declare function assembleBundle(entries: readonly BundleEntry[], maxChars: number, opts?: AssembleOptions): string;
 /** Truncate to `max` chars, appending a marker naming how much was dropped. */
 export declare function truncate(s: string, max: number): string;
 //# sourceMappingURL=bundle.d.ts.map

package/dist/replay/bundle.js

@@ -53,14 +53,52 @@ const MIXED_HEADER = "[BaseInstRunner calculated replay] A known-good tool seque
     "because their tool cannot be executed here — treat them as possibly out of date. " +
     "Use them to answer the user's request now — do NOT call any tools.";
 const MIXED_FOOTER = "\n\nAnswer the user's request using the results above. Do not call any tools.";
+/**
+ * The scenario stopped before the task was done (fallbk.md), so the model must
+ * NOT be told to answer without tools — the rest of the work is its own. The
+ * hand-over note in front of the bundle says what is left.
+ */
+const HANDOVER_HEADER = "[BaseInstRunner calculated replay] The tool calls below ran for real, moments ago, on " +
+    "the user's behalf, and their side effects are already in place. Results marked " +
+    "(recorded) come from an earlier recording because their tool cannot run here. The " +
+    "scenario stopped before the task was finished: do not repeat these calls, and " +
+    "continue the task yourself from where they end.";
+const HANDOVER_FOOTER = "\n\nThe calls above are done. Continue the rest of the task yourself, calling tools as needed.";
+/**
+ * The plan ran inside the agent's own task (segmented.md R-OUT-13): it finished,
+ * but the task did not, so the model must not be told to answer without tools.
+ * This is {@link HANDOVER_HEADER} without "The scenario stopped before the task
+ * was finished" — nothing stopped, the sub-task is simply done.
+ */
+const SUBTASK_HEADER = "[BaseInstRunner calculated replay] The tool calls below ran for real, moments ago, on " +
+    "the user's behalf, and their side effects are already in place. Results marked " +
+    "(recorded) come from an earlier recording because their tool cannot run here. These " +
+    "steps are done: do not repeat these calls. Continue your task from where they end, " +
+    "calling tools as needed.";
+const SUBTASK_FOOTER = "\n\nThe calls above are done. Continue your task, calling tools as needed.";
 /**
  * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
  */
-export function assembleBundle(entries, maxChars) {
+export function assembleBundle(entries, maxChars, opts = {}) {
     const n = entries.length;
     const anyRecorded = entries.some((e) => e.recorded);
-    const header = anyRecorded ? MIXED_HEADER : LIVE_HEADER;
-    const footer = anyRecorded ? MIXED_FOOTER : LIVE_FOOTER;
+    // A hand-over outranks a sub-task: it says "continue" too, and it also has to
+    // say that the plan stopped short. A sub-task outranks the live and mixed
+    // headers, whose wording forbids further tool calls (segmented.md 10.8 §6).
+    const header = opts.handover
+        ? HANDOVER_HEADER
+        : opts.subTask
+            ? SUBTASK_HEADER
+            : anyRecorded
+                ? MIXED_HEADER
+                : LIVE_HEADER;
+    const footer = opts.handover
+        ? HANDOVER_FOOTER
+        : opts.subTask
+            ? SUBTASK_FOOTER
+            : anyRecorded
+                ? MIXED_FOOTER
+                : LIVE_FOOTER;
     const fixedCost = header.length +
         footer.length +
         entries.reduce((sum, e) => sum + PER_STEP_OVERHEAD + e.toolName.length + e.input.length, 0);