@basein/runner 0.3.24 → 0.3.26

package/dist/replay/controller.d.ts

@@ -14,6 +14,7 @@
 import type { ExecutionReport } from "../record/recorder.js";
 import { type ReplayMode, type StepReach } from "./coverage.js";
 import { deriveParameters, type AgentDay, type DeriveContext, type DeriveResult } from "./derive.js";
+import { type HandoverStopReason } from "./handover.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
 import { type HostSinks } from "./safety.js";
@@ -199,7 +200,8 @@ export declare function clampDirectRun(budgets: ReplayBudgets, logicMs?: number)
  *
  *  - **ok** — the plan ran to its end: `{ ok: true, text, responseModel, steps,
  *    partial: false }`. `text` is the bundle; `responseModel` what the
- *    scenario's own logic built from it (`{}` when it has none).
+ *    scenario's own logic built from it (`{}` when it has none, and when the
+ *    bundle is brief and carries it already — plan.ts, `DriveOptions.brief`).
  *  - **partial** — the plan stopped part-way after running steps here: `{ ok:
  *    true, text, responseModel: {}, steps, partial }`. `text` opens with the
  *    hand-over note (text beginning `[BaseInstRunner calculated replay]`) and
@@ -309,6 +311,39 @@ export interface IntentMatchOptions {
     maxRequestsPerTurn: number;
 }
 export declare const DEFAULT_INTENT_MATCH: IntentMatchOptions;
+/**
+ * Where the stopped step stood when a plan handed over, in the words the
+ * service reads (its recordings/repo.ts `handoverFamily`): did the step
+ * happen. Its tool ran and only its output could not be read: `ran`. It was
+ * sent and nothing came back: `uncertain`. Stopped in front of it — the plan's
+ * time ran out (`budget`), its caller left (`cancelled`), its test could not
+ * say whether this request needs it (`test_failed`) — it was never sent:
+ * `not_run`. Otherwise the stop's own reason (`not_run`, `failed`,
+ * `concurrent`, `host_rejected`, `host_edited`), and a plain failure, which
+ * carries none, reads `failed`.
+ *
+ * The service continues a hand-over only with work that was recorded where the
+ * step had not happened (`not_run`, `failed`): the agent's work there starts
+ * with that very step. Continued after a step that ran, or may have, the plan
+ * made of it ran the step a second time. The three stops in front of a step
+ * went out under their own names, which the service reads as "may have run":
+ * a plan stopped by its time budget was never continued.
+ */
+export declare function stopOf(h: {
+    ranThisStep?: boolean;
+    inFlight?: unknown;
+    stopReason?: HandoverStopReason;
+}): string;
+/**
+ * Whether a run of the plan sent at least one of its calls: a step did its
+ * work, its tool answered with an error, its output could not be read after
+ * the tool ran, or it was sent and has not been seen through (a pin still out,
+ * a stop that may have happened). A step its test left out, one whose logic
+ * broke before its call, one that could not be sent and a recorded stand-in
+ * sent nothing — a plan that only did those has nothing a second run could
+ * repeat.
+ */
+export declare function sentACall(state: ReplayState): boolean;
 /** The turn handed back to the model part-way (fallbk.md). */
 export interface Handover {
     kind: FallbackKind;
@@ -316,6 +351,8 @@ export interface Handover {
     stepIndex: number;
     toolName?: string;
     error?: string;
+    /** For a `step_failed`: where the stopped step stood ({@link stopOf}). */
+    stop?: string;
     /** What the model is told. Always built, even when delivery fails. */
     note: string;
     /** Set once the note reached the model, so it is never delivered twice. */
@@ -483,6 +520,16 @@ export interface ReplayState {
      * the execution report says `measured: false`.
      */
     callerCancelled?: boolean;
+    /**
+     * The plan ran to its end while its caller was gone, so its results reached
+     * nobody and no hand-over note exists: this says so, once, to the model
+     * ({@link ReplayController.takeNote}), so that it does not run the steps
+     * again.
+     */
+    unseen?: {
+        note: string;
+        delivered: boolean;
+    };
     /**
      * The derivation is the service's to answer (no key here), so waiting on it
      * is waiting on the service, and obeys its breaker (util/service-health.ts).
@@ -617,6 +664,14 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_ste
  * arms on the model's first call after the hand-over, whatever that is.)
  */
  | "not_taken"
+/**
+ * The plan was cancelled by its caller (Esc on `run_scenario`, or a timeout)
+ * a few minutes ago, after at least one step had run, and the same plan came
+ * back: not armed again, so the steps whose side effects are in place do not
+ * run a second time. The agent does the task, told what ran. Set by the
+ * control server.
+ */
+ | "after_cancel"
 /**
  * A continuation whose own code for working out its values (`paramsLogic`)
  * failed on this request, so none of its steps could be computed. Set by
@@ -773,6 +828,12 @@ export declare class ReplayController {
      * against the plan; the outcome is `fell_back` when a step ran and `failed`
      * when none did, as for every hand-over. The note is the caller's to
      * deliver ({@link takeNote}). Returns false when there was no live plan.
+     *
+     * A step the adapter was given and has not reported back on may be running:
+     * the plan stops after it, as for a call beside a pin ({@link concurrentCall}),
+     * and the hand-over says the step may have happened — never "did not run",
+     * which the service would continue with work that starts by running it
+     * again. Its result is still read when it lands.
      */
     hostHandOver(state: ReplayState, why: "own_call" | "closed" | "late"): boolean;
     /**
@@ -813,6 +874,8 @@ export declare class ReplayController {
      * Returns it once and marks it delivered; undefined when there is none.
      */
     takeNote(state: ReplayState | undefined): string | undefined;
+    /** Whether a note about this plan is still to be told to the model: a hand-over's, or the unseen results'. */
+    hasUndeliveredNote(state: ReplayState | undefined): boolean;
     /**
      * Deliver text to the model in place of the tool call it was about to make:
      * as genuine command output for `Bash`, as the denial reason otherwise — the

package/dist/replay/controller.js

@@ -22,7 +22,7 @@ import { BuiltinNotRunnable, BuiltinTimeout, FILE_BUILTINS, parseBashAllow, pars
 import { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, testWords, truncate } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
 import { deriveParameters, localDay, } from "./derive.js";
-import { buildHandoverNote, MAX_HANDOVER_NOTE, } from "./handover.js";
+import { buildHandoverNote, buildUnseenResultNote, MAX_HANDOVER_NOTE, } from "./handover.js";
 import { NO_PROXY, NoSessionProxyError, ProxyWorkQueue, QUEUE_CLOSED } from "./executor.js";
 import { logicTimeoutMs, MAX_LOGIC_TIMEOUT_MS } from "./logic.js";
 import { PREVIEW_BUDGET_MS, RecordedValueError, ScenarioReplayPlan, StepRunError, } from "./plan.js";
@@ -171,6 +171,56 @@ export const DEFAULT_INTENT_MATCH = {
     maxPerTurn: 3,
     maxRequestsPerTurn: 40,
 };
+/**
+ * Where the stopped step stood when a plan handed over, in the words the
+ * service reads (its recordings/repo.ts `handoverFamily`): did the step
+ * happen. Its tool ran and only its output could not be read: `ran`. It was
+ * sent and nothing came back: `uncertain`. Stopped in front of it — the plan's
+ * time ran out (`budget`), its caller left (`cancelled`), its test could not
+ * say whether this request needs it (`test_failed`) — it was never sent:
+ * `not_run`. Otherwise the stop's own reason (`not_run`, `failed`,
+ * `concurrent`, `host_rejected`, `host_edited`), and a plain failure, which
+ * carries none, reads `failed`.
+ *
+ * The service continues a hand-over only with work that was recorded where the
+ * step had not happened (`not_run`, `failed`): the agent's work there starts
+ * with that very step. Continued after a step that ran, or may have, the plan
+ * made of it ran the step a second time. The three stops in front of a step
+ * went out under their own names, which the service reads as "may have run":
+ * a plan stopped by its time budget was never continued.
+ */
+export function stopOf(h) {
+    if (h.ranThisStep)
+        return "ran";
+    if (h.inFlight)
+        return "uncertain";
+    if (h.stopReason === "budget" || h.stopReason === "cancelled" || h.stopReason === "test_failed")
+        return "not_run";
+    return h.stopReason ?? "failed";
+}
+/**
+ * Whether a run of the plan sent at least one of its calls: a step did its
+ * work, its tool answered with an error, its output could not be read after
+ * the tool ran, or it was sent and has not been seen through (a pin still out,
+ * a stop that may have happened). A step its test left out, one whose logic
+ * broke before its call, one that could not be sent and a recorded stand-in
+ * sent nothing — a plan that only did those has nothing a second run could
+ * repeat.
+ */
+export function sentACall(state) {
+    if (state.stepsPinned > 0 || state.pinned.size > 0 || (state.lingering?.size ?? 0) > 0)
+        return true;
+    const stop = state.handover?.stop;
+    if (stop === "ran" || stop === "uncertain" || stop === "host_edited")
+        return true;
+    for (const r of state.stepResults.values()) {
+        if (r.status === "ok")
+            return true;
+        if (r.status === "failed" && (r.stage === "tool_call" || r.stage === "tool_output_logic"))
+            return true;
+    }
+    return false;
+}
 /**
  * How long a call waits for the previous pin to thread before it is judged to
  * be running beside it: the control server's hook-view fallback
@@ -527,12 +577,23 @@ export class ReplayController {
         // reading that did not answer carries every target at its recorded
         // sample (derive.ts), and one of these must be the mark there too — never
         // last week's task name under a step that would create the task.
-        const oneHalf = hasTargets(scenario.paramsObject)
-            ? testedOnlyTargets(targetKeys(scenario.paramsObject), scenario.paramsObject, planned, scenario.paramsLogic)
+        const allTargets = hasTargets(scenario.paramsObject) ? targetKeys(scenario.paramsObject) : [];
+        const oneHalf = allTargets.length > 0
+            ? testedOnlyTargets(allTargets, scenario.paramsObject, planned, scenario.paramsLogic)
             : [];
-        const params = derivation.then((r) => r.derived || oneHalf.length === 0
+        // A reading that did not answer (no key, the service down, out of budget,
+        // too slow) names no target at all. Settings may stand on their recorded
+        // samples; a target never does, whichever way the plan reads it. Only the
+        // ones a step would act on outright make the gate below decline, and the
+        // rest are what targets.ts counts on: a chain that finds its own value
+        // (`(respParams.ranked || [])[0] ?? parameters.id`) keeps the caller's
+        // copy as a bare fallback, and that fallback is `null` there — as it is
+        // when the reading answered and found nothing. Left at its sample, the
+        // fallback was last week's device, and the step acted on it whenever the
+        // chain found nothing.
+        const params = derivation.then((r) => r.derived || allTargets.length === 0
             ? r.params
-            : { ...r.params, ...Object.fromEntries(oneHalf.map((key) => [key, null])) });
+            : { ...r.params, ...Object.fromEntries(allTargets.map((key) => [key, null])) });
         // `params` is awaited by the plan, and by gate 7 below when there is a
         // target. Without this, the losing race in gate 7 leaves `derivation`
         // rejected and unhandled, which takes the process down on an unhandled
@@ -665,7 +726,10 @@ export class ReplayController {
         if (this.recordedFallback && this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
-                runId: scenario.runId,
+                // The run the current chain was calculated from: for a plan repaired
+                // from a fresh recording that is not the run it is stored under, and a
+                // stand-in taken from the old one is the output of another chain.
+                runId: scenario.sourceRunId ?? scenario.runId,
                 token: this.opts.authToken,
                 fetchImpl: this.opts.fetchImpl,
             });
@@ -759,24 +823,63 @@ export class ReplayController {
      * against the plan; the outcome is `fell_back` when a step ran and `failed`
      * when none did, as for every hand-over. The note is the caller's to
      * deliver ({@link takeNote}). Returns false when there was no live plan.
+     *
+     * A step the adapter was given and has not reported back on may be running:
+     * the plan stops after it, as for a call beside a pin ({@link concurrentCall}),
+     * and the hand-over says the step may have happened — never "did not run",
+     * which the service would continue with work that starts by running it
+     * again. Its result is still read when it lands.
      */
     hostHandOver(state, why) {
         const plan = state.plan;
         if (!plan || state.retired)
             return false;
-        const position = plan.currentStepIndex;
-        this.handOver(state, {
-            kind: "step_failed",
-            step: plan.currentStep(),
-            position,
-            error: why === "own_call"
-                ? "the model made a call of its own, so the scenario stopped"
-                : why === "late"
-                    ? "its arguments were not ready in time"
-                    : "the run ended before this step",
-            delivery: "above",
-            stopReason: "not_run",
-        });
+        const reason = why === "own_call"
+            ? "the model made a call of its own, so the scenario stopped"
+            : why === "late"
+                ? "its arguments were not ready in time"
+                : "the run ended before this step";
+        const outstanding = [...state.pinned.values()][0];
+        if (!outstanding) {
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.currentStep(),
+                position: plan.currentStepIndex,
+                error: reason,
+                delivery: "above",
+                stopReason: "not_run",
+            });
+            return true;
+        }
+        const inFlight = new Map(state.pinned);
+        const next = outstanding.stepIndex + 1;
+        if (next < plan.stepCount) {
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.allSteps()[next],
+                position: next,
+                error: reason,
+                delivery: "above",
+                stopReason: "not_run",
+                ran: outstanding.stepIndex,
+                inFlight: { stepIndex: outstanding.stepIndex, toolName: outstanding.toolName },
+            });
+        }
+        else {
+            // The step out is the plan's last: the stop is that step, sent and not answered.
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.allSteps()[outstanding.stepIndex],
+                position: outstanding.stepIndex,
+                error: why === "own_call"
+                    ? "it had not reported back when the model made a call of its own"
+                    : "it had not reported back when the run ended",
+                delivery: "above",
+                stopReason: "uncertain",
+                ran: outstanding.stepIndex,
+            });
+        }
+        state.lingering = inFlight;
         return true;
     }
     /**
@@ -858,14 +961,27 @@ export class ReplayController {
      */
     takeNote(state) {
         const h = state?.handover;
-        if (!h || h.delivered)
-            return undefined;
-        h.delivered = true;
-        logDetail("replay.handover_delivered", {
-            scenario: state.scenarioId ?? undefined,
-            bytes: h.note.length,
-        });
-        return h.note;
+        if (h && !h.delivered) {
+            h.delivered = true;
+            logDetail("replay.handover_delivered", {
+                scenario: state.scenarioId ?? undefined,
+                bytes: h.note.length,
+            });
+            return h.note;
+        }
+        // A plan that ran to its end with nobody there to read it has no
+        // hand-over, and this one note instead.
+        const u = state?.unseen;
+        if (u && !u.delivered) {
+            u.delivered = true;
+            logDetail("replay.unseen_delivered", { scenario: state.scenarioId ?? undefined, bytes: u.note.length });
+            return u.note;
+        }
+        return undefined;
+    }
+    /** Whether a note about this plan is still to be told to the model: a hand-over's, or the unseen results'. */
+    hasUndeliveredNote(state) {
+        return Boolean((state?.handover && !state.handover.delivered) || (state?.unseen && !state.unseen.delivered));
     }
     /**
      * Deliver text to the model in place of the tool call it was about to make:
@@ -1709,6 +1825,12 @@ export class ReplayController {
         const plan = state.plan;
         if (!plan || state.retired)
             return { ok: false, why: RUN_NO_PLAN };
+        // Only a direct plan is run here, and only one with no step pinned for the
+        // model's own call. A steer plan is stepped through by the model's calls,
+        // and a step it pinned and that is still in flight would run a second time
+        // under this run: the model told to call `run_scenario` by hand, beside it.
+        if (state.mode !== "direct" || state.pinned.size > 0)
+            return { ok: false, why: RUN_NO_PLAN };
         if (state.running)
             return state.running;
         const running = this.runArmedOnce(state, plan, signal).catch((err) => {
@@ -1757,7 +1879,15 @@ export class ReplayController {
         const deadline = Date.now() + this.budgets.planMs;
         let result;
         try {
-            result = await plan.runToCompletion(this.executeStep(state, { deadline }), this.recordedSource(state), this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true, recordedFallback: this.recordedFallback, signal, reportTool: this.reportToolFor(state) });
+            result = await plan.runToCompletion(this.executeStep(state, { deadline }), this.recordedSource(state), this.observeStep(state), deadline, MAX_REPLAY_REASON, {
+                stopOnFailure: true,
+                recordedFallback: this.recordedFallback,
+                signal,
+                reportTool: this.reportToolFor(state),
+                // The agent answers from the bundle alone: a run that went entirely
+                // well is laid out briefly, with the plan's summary in it.
+                brief: true,
+            });
         }
         catch (err) {
             // The scenario's own logic failed. Retire and let the model do the work.
@@ -1791,7 +1921,14 @@ export class ReplayController {
             // out — is no saving at all: the turn it ended cost next to nothing and
             // says nothing about what the task costs. `handOver` books `fell_back`
             // (steps did run) or `failed`, and the report is not a measurement.
-            if (stop.reason === "cancelled")
+            //
+            // Whether the caller is gone is read here, after the run, and not only
+            // from the stop's own reason: a caller who leaves during a step sees the
+            // run go on to that step's end, and a step that then fails stops the run
+            // for its own reason. The note about it went to a closed request, and the
+            // model was never told which steps had run.
+            const callerGone = stop.reason === "cancelled" || signal?.aborted === true;
+            if (callerGone)
                 state.callerCancelled = true;
             // Nothing ran *here*: there is no bundle, only the task — a recorded
             // output is not a result that happened (plan.ts, DriveOptions).
@@ -1807,7 +1944,7 @@ export class ReplayController {
                 // A cancelled run's note is kept for the model's next call, alone —
                 // the bundle went to a caller who is gone — so it points at side
                 // effects in place, never at results "below" that nobody receives.
-                delivery: live && stop.reason !== "cancelled" ? "below" : "none",
+                delivery: live && !callerGone ? "below" : "none",
                 stopReason: stop.reason,
                 ran: live ? undefined : 0,
                 // An output-logic failure stops *after* its step's tool ran: the step
@@ -1816,7 +1953,7 @@ export class ReplayController {
                 // The other half (AC5): what the steps from here are for.
                 whenText: stop.whenText,
             });
-            if (stop.reason === "cancelled") {
+            if (callerGone) {
                 // The caller is gone and reads nothing. The note stays undelivered: a
                 // client that timed out hands the task back to the model in this same
                 // turn, and the model's next call is where it learns which steps
@@ -1875,12 +2012,18 @@ export class ReplayController {
         }
         // Live steps only, as above: a recorded stand-in did no work here.
         state.stepsPinned += result.executed;
+        // A brief bundle carries the plan's summary itself, in a few words, so it
+        // is not delivered a second time beside it.
         let responseModel = {};
-        try {
-            responseModel = plan.responseModel();
-        }
-        catch (err) {
-            logDetail("replay.response_model_failed", { error: errText(err) });
+        if (result.summaryError)
+            logDetail("replay.response_model_failed", { error: result.summaryError });
+        if (!result.brief) {
+            try {
+                responseModel = plan.responseModel();
+            }
+            catch (err) {
+                logDetail("replay.response_model_failed", { error: errText(err) });
+            }
         }
         // A plan whose tools errored ran to the end and did nothing. `steered_full`
         // would book the largest saving available for it; `failed` books a baseline
@@ -1908,6 +2051,29 @@ export class ReplayController {
             partial: result.partial || undefined,
             ms: Date.now() - state.armedAt,
         });
+        // The caller left during the last step, which the run does not interrupt:
+        // every step ran, and the answer goes to a closed request. Nothing stopped,
+        // so there is no hand-over note, and the model was never told that the
+        // steps ran — the next request of the same task ran them again, a second
+        // row, a second mail. So the turn is no measurement of the task, and the
+        // model is told once, at its next call or prompt (the server keeps the note
+        // for it: `stashCancelledNote`).
+        if (signal?.aborted) {
+            state.callerCancelled = true;
+            state.unseen = {
+                note: buildUnseenResultNote({
+                    intent: plan.intent ?? "",
+                    executed: result.executed,
+                    totalSteps: plan.totalSteps ?? state.stepsPlanned,
+                }),
+                delivered: false,
+            };
+            logLine("replay.cancelled", {
+                scenario: state.scenarioId ?? undefined,
+                ran: `${result.executed}/${plan.stepCount}`,
+                why: "the caller went away during the last step — every step ran and nobody read the results",
+            });
+        }
         return {
             ok: true,
             text: result.text,
@@ -2011,8 +2177,15 @@ export class ReplayController {
             // After a person's "no" the task ended early; after a changed call that
             // was the plan's first step, the turn made one model call fewer than
             // the task needs — the one the plan's call replaced.
+            //
+            // Nor one its caller cancelled, or one this plan was not armed for
+            // because it had been cancelled a moment before: the steps it did
+            // already ran in the turn before, so the agent's work is the rest of the
+            // task, and its cost is no measure of the whole.
             baselineEligible: d.siblings?.some((s) => s !== state && s.plan !== undefined) ||
                 state.hostStop !== undefined ||
+                state.callerCancelled === true ||
+                state.declined === "after_cancel" ||
                 d.cutShort === true
                 ? false
                 : undefined,
@@ -2092,17 +2265,30 @@ export class ReplayController {
             }
             return out;
         });
+        // The plan stops in front of a step the service parked, or whose owner
+        // froze it by hand (plan-services.md D8). An operator who asks for the run
+        // by id turns the gates off, not that: a frozen step is the one that must
+        // not run unattended — an install, a deploy — and the run ended up running
+        // it, and every step after it. It stops there, and says so (`stopped`).
+        const stopAt = stopIndex(scenario.steps, undefined);
+        if (stopAt === 0) {
+            return {
+                ok: false,
+                why: "the plan's first step is parked or frozen by hand, so it stops in front of it: nothing was run",
+            };
+        }
         const plan = new ScenarioReplayPlan({
             scenario,
             params,
             mode,
             fallbackTargets: "samples",
+            stopAt,
         });
         state.plan = plan;
         if (this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
-                runId: scenario.runId,
+                runId: scenario.sourceRunId ?? scenario.runId,
                 token: this.opts.authToken,
                 fetchImpl: this.opts.fetchImpl,
             });
@@ -2352,7 +2538,10 @@ export class ReplayController {
         // it as that half's evidence. Booked `diverged`, it never did.
         const otherHalf = stop?.kind === "other_branch";
         this.upgrade(state, broke || !didWork ? "failed" : otherHalf ? "fell_back" : "diverged");
-        state.stepsPinned += composed.executed;
+        // A step whose tool answered with an error did not do its work: it is not
+        // among the steps the plan "ran", whose saving is booked and whose note
+        // tells the model not to run them again (as `runArmedOnce` counts them).
+        state.stepsPinned += Math.max(0, composed.executed - composed.errored);
         // The headline number of this whole design: recovering from a divergence
         // costs nothing, because the proxies were already connected.
         logLine("replay.compose", {
@@ -2470,6 +2659,9 @@ export class ReplayController {
             stepIndex: step?.stepIndex ?? position,
             toolName: step?.toolName ?? undefined,
             error: stop.error,
+            ...(stop.kind === "step_failed"
+                ? { stop: stopOf({ ranThisStep: stop.stage === "tool_output_logic", stopReason: stop.reason }) }
+                : {}),
             note,
             delivered: true,
         };
@@ -2493,6 +2685,7 @@ export class ReplayController {
             stepIndex: h.step?.stepIndex ?? h.position,
             toolName: h.step?.toolName ?? undefined,
             error: h.error,
+            ...(h.kind === "step_failed" ? { stop: stopOf(h) } : {}),
             note: this.noteFor(state, h),
             delivered: false,
         };
@@ -3138,6 +3331,13 @@ function classifyWorkError(err, serverName) {
     if (message === QUEUE_CLOSED || /\bupstream is not available\b/i.test(message)) {
         return new StepRunError(message, "not_run");
     }
+    // A timeout, an interrupt, a dropped connection: sent, and not seen through,
+    // so its work may have happened — before the "MCP error" rule below, which
+    // would call `MCP error -32001: Request timed out` a failure the tool
+    // answered. The pinned path words it the same way ({@link pinFailure}). A
+    // plan told "failed" there let the agent run the step again.
+    if (UNCERTAIN_TEXT.test(message))
+        return new StepRunError(message, "uncertain");
     if (/^MCP error -?\d+/i.test(message))
         return new StepRunError(message, "failed");
     return new StepRunError(message, "uncertain");

package/dist/replay/derive.js

@@ -33,7 +33,7 @@
 import { redactText } from "../record/redact.js";
 import { isUnhealthyStatus, serviceHealth, timeoutSignal } from "../util/service-health.js";
 import { serviceHeaders } from "../util/service-headers.js";
-import { calculateCostUsd } from "./pricing.js";
+import { calculateCostUsd, requestRates } from "./pricing.js";
 export const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
 const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
 const ANTHROPIC_VERSION = "2023-06-01";
@@ -133,6 +133,44 @@ export function extractJsonObject(text) {
     }
     return undefined;
 }
+/**
+ * `text` with each bare `undefined` in its JSON made `null`, when that JSON
+ * does not parse as it came. `undefined` is not JSON, but models emit it
+ * (`{"a": undefined}`), and one stray token should not cost the extraction.
+ * A value that says it in words — `TypeError: undefined is not a function` —
+ * is a value, and was rewritten along with the rest: the plan was handed
+ * `TypeError: null is not a function`, silently. So the JSON is read as it
+ * came first, and only a token outside every string literal is changed: the
+ * walk takes each string from its opening quote to its closing one, so a
+ * quote inside a string never ends it early.
+ */
+function nullUndefined(text) {
+    const json = extractJsonObject(text);
+    if (json === undefined)
+        return text;
+    try {
+        JSON.parse(json);
+        return text;
+    }
+    catch {
+        // not JSON as it came: repaired below
+    }
+    let fixed = "";
+    let at = 0;
+    while (at < json.length) {
+        const open = json.indexOf('"', at);
+        fixed += json.slice(at, open < 0 ? json.length : open).replace(/\bundefined\b/g, "null");
+        if (open < 0)
+            break;
+        let end = open + 1;
+        while (end < json.length && json[end] !== '"')
+            end += json[end] === "\\" ? 2 : 1;
+        fixed += json.slice(open, end + 1);
+        at = end + 1;
+    }
+    const start = text.indexOf(json);
+    return text.slice(0, start) + fixed + text.slice(start + json.length);
+}
 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
@@ -232,15 +270,19 @@ export async function deriveParameters(opts) {
         .join("");
     const inputTokens = body.usage?.input_tokens ?? 0;
     const outputTokens = body.usage?.output_tokens ?? 0;
+    const cacheReadTokens = body.usage?.cache_read_input_tokens ?? 0;
+    const cacheCreationTokens = body.usage?.cache_creation_input_tokens ?? 0;
     const costUsd = calculateCostUsd(model, {
         inputTokens,
         outputTokens,
-        cacheReadTokens: body.usage?.cache_read_input_tokens ?? 0,
-        cacheCreationTokens: body.usage?.cache_creation_input_tokens ?? 0,
+        cacheReadTokens,
+        cacheCreationTokens,
+        // One request: priced by its own prompt length where the model is (pricing.ts).
+        ...requestRates(model, { promptTokens: inputTokens + cacheReadTokens + cacheCreationTokens }),
     });
     // `undefined` is not JSON, but models emit it; normalise before parsing so one
     // stray token does not cost the whole extraction.
-    const normalized = text.replace(/:\s*undefined\b/g, ": null");
+    const normalized = nullUndefined(text);
     const cleaned = extractJsonObject(normalized) ??
         normalized
             .replace(/^```(?:json)?\s*/m, "")

package/dist/replay/handover.d.ts

@@ -130,6 +130,19 @@ export interface HandoverNoteInput {
     whenText?: string | null;
 }
 export declare function buildHandoverNote(n: HandoverNoteInput): string;
+/**
+ * The note for a plan that ran every one of its steps while its caller was
+ * gone (Esc on `run_scenario`, or the client's timeout), so that the results
+ * reached nobody. Nothing stopped, so no hand-over note exists; without this
+ * one the model was never told the steps ran, and the next request of the same
+ * task ran them again — a row added twice, a mail sent twice.
+ */
+export declare function buildUnseenResultNote(n: {
+    intent: string;
+    /** How many steps ran, of how many the plan has. */
+    executed: number;
+    totalSteps: number;
+}): string;
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */
 export declare function stepsPhrase(numbers: readonly number[]): string;
 //# sourceMappingURL=handover.d.ts.map