@basein/runner 0.3.17 → 0.3.19

package/dist/replay/derive.d.ts

@@ -38,10 +38,21 @@ export interface LiveCall {
     /** Redacted and capped, exactly as the probe sent it. */
     toolInput: string;
 }
+/** The day the agent was told it is (control/transcript.ts `agentDayOf`; issue 1212). */
+export interface AgentDay {
+    line: string;
+    day?: string;
+    source: "system" | "host";
+}
 /** What a turn can tell derivation beyond its prompt (segmented.md R-PARAM-2). */
 export interface DeriveContext {
     liveCall?: LiveCall;
     recentResults?: string[];
+    /**
+     * The agent's own day, read again each time it is asked: its host writes it
+     * into the session only after the prompt hook (issue 1212).
+     */
+    agentDay?: () => AgentDay | undefined;
 }
 /**
  * The service, which derives when this runner has no key of its own
@@ -62,6 +73,8 @@ export interface DeriveOptions extends DeriveContext {
     paramsObject: ParamsSchema | null;
     /** The day on this machine. Injected by tests; defaults to {@link localDay}. */
     today?: string;
+    /** The words that told the agent its day, when its host showed it any (issue 1212). */
+    todaySaid?: string;
     /** An override that keeps the reading on this machine. Absent → the service. */
     apiKey?: string;
     /** Used when there is no `apiKey`. Absent too → recorded samples. */
@@ -91,6 +104,8 @@ export interface DeriveResult {
     missing: string[];
     /** Settings filled from their recorded sample (R-PARAM-2). */
     sampled: string[];
+    /** The day the service read the turn's dates from, when it said (issue 1212). */
+    dayUsed?: string;
 }
 /**
  * The day on this machine, `YYYY-MM-DD`, in its own time zone.

package/dist/replay/derive.js

@@ -343,6 +343,10 @@ async function deriveViaService(opts, service, schema, keys) {
                 // What "tomorrow" is counted from. A service that does not know the
                 // field ignores it.
                 today: opts.today ?? localDay(),
+                // The words that told the agent its day ("Today's date is Thursday,
+                // 2023-11-30 …"), which the service turns into the day it reads from
+                // (issue 1212). Older services ignore it.
+                ...(opts.todaySaid ? { todaySaid: opts.todaySaid } : {}),
             }),
             signal: opts.signal ?? timeoutSignal(),
         });
@@ -402,6 +406,7 @@ async function deriveViaService(opts, service, schema, keys) {
         model: body.model,
         missing,
         sampled,
+        ...(typeof body.today === "string" ? { dayUsed: body.today } : {}),
     };
 }
 //# sourceMappingURL=derive.js.map

package/dist/replay/handover.d.ts

@@ -156,6 +156,13 @@ export interface HandoverNoteInput {
      * from there on are for, which this request is not (autocorrect.md AC5).
      */
     whenText?: string | null;
+    /**
+     * For `decision`: the live request the plan serves, the user's own words.
+     * Its sentences with a condition word are quoted, so the agent sees the
+     * choice that is its to make (the service's segmentsbreakdown.md SB-18).
+     * Read for no other kind.
+     */
+    request?: string | null;
 }
 export declare function buildHandoverNote(n: HandoverNoteInput): string;
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */

package/dist/replay/handover.js

@@ -11,6 +11,7 @@
  * and a tool's own payload is already in front of it where it ran.
  */
 import { truncate } from "./bundle.js";
+import { conditionSentences } from "./condition-words.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;
@@ -26,6 +27,8 @@ const UNUSABLE_LINE = {
     unsupported: "this runner cannot run",
 };
 export function buildHandoverNote(n) {
+    if (n.kind === "decision")
+        return decisionNote(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})` : "";
@@ -35,6 +38,91 @@ export function buildHandoverNote(n) {
     ];
     if (intent)
         lines.push(`Intent: ${intent}`);
+    lines.push(...ranLines(n));
+    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 if (n.kind === "nondeterministic_step") {
+        // The calculation could not write code for this step's input: it is a
+        // judgement, and the agent is the one to make it (plan-services.md D8).
+        lines.push(`Step ${human} of ${n.totalSteps}${tool} did not run: its input needs a judgement the scenario cannot compute. Make that choice yourself and carry on.`);
+    }
+    else if (n.kind === "other_branch") {
+        // The plan holds one half of an "if … otherwise" and this request is the
+        // other (autocorrect.md AC5). The steps from here are not wrong, they are
+        // not this request's: the model is told what they are for, never to run
+        // them, and the list of their tools is left out below for that reason.
+        const why = n.whenText ? `they are only for when ${n.whenText}, and that is not so for this request` : "this request is the other case of the task, which they are not for";
+        lines.push(n.stepIndex >= n.totalSteps
+            ? "None of the scenario's steps was needed for this request. Do the task as this request needs it."
+            : `Step ${human} of ${n.totalSteps}${tool} and the steps after it did not run: ${why}. Do the rest of the task yourself, as this request needs it.`);
+    }
+    else {
+        lines.push(stepFailedLine(n, human, tool));
+    }
+    // Not for the other half: those tools are the ones this request must not
+    // run, and naming them invites exactly that.
+    if (n.remainingTools.length > 0 && n.kind !== "other_branch") {
+        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);
+}
+/**
+ * The note of a plan stopped at its decision (the service's
+ * segmentsbreakdown.md SB-18): what ran, and the request's own words for the
+ * choice the agent now makes. Nothing that names the recorded half: no
+ * intent, no remaining steps, no parameters, and never the condition the
+ * service keeps (`stop.why`). Each would hint which way the recording went.
+ */
+function decisionNote(n) {
+    // Where the results of the steps that ran are, as the ran-steps line says.
+    const above = Math.max(0, Math.min(n.executedAbove ?? 0, n.executed));
+    const delivery = above >= n.executed ? "above" : n.delivery;
+    const from = n.executed === 0
+        ? ""
+        : delivery === "above"
+            ? " from the results above"
+            : delivery === "below"
+                ? above > 0
+                    ? " from the results above and below"
+                    : " from the results below"
+                : "";
+    const quote = conditionSentences(n.request);
+    const ask = quote ? `This request asks for a decision: “${quote}”.` : "This task has a decision to make here.";
+    const lines = [
+        "[BaseInstRunner calculated replay] The calculated scenario for this request ran the steps before a decision, and stopped there.",
+        ...ranLines(n),
+        `${ask} Decide${from} which way applies, then continue the task, calling tools as needed.`,
+    ];
+    return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
+}
+/** What ran before the stop, and what of it the model may assume: the lines every note carries. */
+function ranLines(n) {
+    const lines = [];
     // Steps left out by their tests sit among those before the stop (AC5): the
     // ones that ran are then named, never "steps 1–N", which would say a step
     // ran that did not.
@@ -100,57 +188,7 @@ export function buildHandoverNote(n) {
         lines.push(`Step ${n.inFlight.stepIndex + 1} of ${n.totalSteps}${inTool} was started and has not reported back: ` +
             "it may not have run, or may still complete. Check whether its work happened before you repeat it.");
     }
-    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 if (n.kind === "nondeterministic_step") {
-        // The calculation could not write code for this step's input: it is a
-        // judgement, and the agent is the one to make it (plan-services.md D8).
-        lines.push(`Step ${human} of ${n.totalSteps}${tool} did not run: its input needs a judgement the scenario cannot compute. Make that choice yourself and carry on.`);
-    }
-    else if (n.kind === "other_branch") {
-        // The plan holds one half of an "if … otherwise" and this request is the
-        // other (autocorrect.md AC5). The steps from here are not wrong, they are
-        // not this request's: the model is told what they are for, never to run
-        // them, and the list of their tools is left out below for that reason.
-        const why = n.whenText ? `they are only for when ${n.whenText}, and that is not so for this request` : "this request is the other case of the task, which they are not for";
-        lines.push(n.stepIndex >= n.totalSteps
-            ? "None of the scenario's steps was needed for this request. Do the task as this request needs it."
-            : `Step ${human} of ${n.totalSteps}${tool} and the steps after it did not run: ${why}. Do the rest of the task yourself, as this request needs it.`);
-    }
-    else {
-        lines.push(stepFailedLine(n, human, tool));
-    }
-    // Not for the other half: those tools are the ones this request must not
-    // run, and naming them invites exactly that.
-    if (n.remainingTools.length > 0 && n.kind !== "other_branch") {
-        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);
+    return lines;
 }
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */
 export function stepsPhrase(numbers) {

package/dist/replay/plan.d.ts

@@ -24,6 +24,48 @@ import { type FlatEntry } from "./flatten.js";
 import type { ReplayMode } from "./coverage.js";
 import type { HandoverStopReason } from "./handover.js";
 import type { ExecutionStage, FallbackKind, ParamsSchema, SerializedScenario, SerializedScenarioStep } from "./types.js";
+/**
+ * A value a step of the recording worked out — an address the directory
+ * returned, the id a search found; the service labels it `from: "step"` —
+ * is never replayed from the recording (issue 1212). The plan holds this mark
+ * in its place. A step whose input still holds it, because its earlier steps
+ * did not return the value and its code fell back on the parameter, stops the
+ * plan in front of it, for the agent; a summary that holds it is left out.
+ * Never the recorded e-mail address, never the recorded lead.
+ */
+export declare const FROM_STEP_MARK = "\u2063bir-from-step:";
+/**
+ * A value the request did not give, which only the steps of one half of an
+ * "if \u2026 otherwise" read (the service's review of calcscenarioautocorrect.md,
+ * item 11; targets.ts, `testedOnlyTargets`). The plan arms without it \u2014 the
+ * other half needs nothing it lacks \u2014 and holds this mark in its place, never
+ * `null` and never the recorded value. A step whose input reads or holds it
+ * stops in front of its call, and the agent does that half; a test that reads
+ * it decides nothing; a summary that reads it is left out.
+ */
+export declare const MISSING_VALUE_MARK = "\u2063bir-missing:";
+/**
+ * A step's code read a value a step works out, which here only the recording
+ * holds (issue 1212). Not a fault of the step: its earlier steps did not
+ * return the value this time. The plan stops in front of it, the step counts
+ * as not run, and the agent does the rest.
+ */
+export declare class RecordedValueError extends Error {
+    readonly key: string;
+    constructor(key: string, message?: string);
+}
+/**
+ * A step's code read a value the request did not give ({@link
+ * MISSING_VALUE_MARK}). The same stop as {@link RecordedValueError} \u2014 not a
+ * fault of the step: it counts as not run, nothing is parked or repaired, and
+ * the agent does the rest \u2014 so it is one, and every place that tells that
+ * stop apart tells this one apart too. Its words name the value.
+ */
+export declare class MissingValueError extends RecordedValueError {
+    constructor(key: string);
+}
+/** The value a mark stands for, when `value` holds one anywhere \u2014 either kind. */
+export declare function markedKey(value: unknown): string | undefined;
 /**
  * Runs one step's tool and returns its output as a string.
  *
@@ -76,6 +118,14 @@ export interface DriveOptions {
      * so what the run reports about it is the truth.
      */
     signal?: AbortSignal;
+    /**
+     * The tool the model may call although the bundle says to call none: `bir`'s
+     * own `mcp__bir__report_wrong_result`, when the session has it (the service's
+     * review of calcscenarioautocorrect.md, item 19). Set by the caller only
+     * where the `bir` server is connected; absent, the bundle's words are as
+     * they always were (bundle.ts, `AssembleOptions.reportTool`).
+     */
+    reportTool?: string;
 }
 /**
  * Supplies a step's recorded output when its tool cannot run here (§8.1).
@@ -289,7 +339,17 @@ export declare class ScenarioReplayPlan {
     private readonly scenario;
     /** The flat list this plan walks. One entry per step that will really run. */
     private readonly entries;
-    private readonly paramsPromise;
+    private paramsPromise;
+    /** The values a step worked out in the recording ({@link FROM_STEP_MARK}). */
+    private readonly fromStep;
+    /**
+     * The targets only the steps of one half read (targets.ts,
+     * `testedOnlyTargets`): each held as {@link MISSING_VALUE_MARK} when the
+     * request does not give it.
+     */
+    private readonly oneHalf;
+    /** Of {@link oneHalf}, the ones the request did not give: held as the mark now. */
+    private missingMarked;
     private params;
     /** The derivation's own answer, before `paramsLogic`. What safety.ts judges. */
     private derivedParams;
@@ -385,6 +445,12 @@ export declare class ScenarioReplayPlan {
      * throws.
      */
     useFallbackParams(): void;
+    /**
+     * The values read again, before any step ran (issue 1212): the agent's own
+     * day showed in the session only after the first reading. False once a step
+     * has run, when the values the steps ran on are the ones that stand.
+     */
+    resetParams(params: Promise<Record<string, unknown>>): boolean;
     /** Whether the parameters are final. */
     get parametersSettled(): boolean;
     /** The derivation's own values, before `paramsLogic`. Empty until settled. */
@@ -403,12 +469,33 @@ export declare class ScenarioReplayPlan {
     stopStep(): SerializedScenarioStep | undefined;
     /** The entry the plan stops in front of, with the frame that owns it. */
     stopEntry(): FlatEntry | undefined;
+    /**
+     * The flat position of the chain's decision stop (the service's
+     * segmentsbreakdown.md SB-18), or -1 when it has none. The steps from there
+     * on are the half the recording took, whatever stops the plan first.
+     */
+    decisionIndex(): number;
     /** Every entry in order — for the report, and for the owning scenario ids. */
     allEntries(): readonly FlatEntry[];
     /** The entry awaiting execution, or undefined when the plan is done. */
     currentEntry(): FlatEntry | undefined;
     /** The parameters in force. Empty until {@link ready} resolves. */
     get parameters(): Readonly<Record<string, unknown>>;
+    /**
+     * The values a body may not use: a value a step works out ({@link
+     * FROM_STEP_MARK}) and a value the request did not give ({@link
+     * MISSING_VALUE_MARK}). A read of one is the stop {@link valueError} names.
+     */
+    private watchedKeys;
+    /** The stop a read of `key` means: a value the request did not give, or one only the recording had. */
+    private valueError;
+    /**
+     * `parameters` for one body, with every read of a value a step works out
+     * noted (issue 1212): a read is the recorded value used, however the code
+     * changes it afterwards — upper-cased, encoded, sliced or counted. A value
+     * the request did not give is watched the same way (review item 11).
+     */
+    private watched;
     /** Everything the steps have accumulated so far. */
     get accumulated(): Readonly<Record<string, unknown>>;
     /** The scenario's parameter schema — what the target and safety checks judge. */
@@ -439,6 +526,14 @@ export declare class ScenarioReplayPlan {
      * a throw as divergence.
      */
     toolInputForCurrentStep(): Record<string, unknown>;
+    /**
+     * A step's input, refused when it holds a value only the recording had: its
+     * code fell back on a parameter a step works out, and the earlier steps did
+     * not return it (issue 1212). The caller stops the plan in front of it. So
+     * is one that reads, or holds, a value the request did not give (review
+     * item 11): {@link MissingValueError}.
+     */
+    private inputOf;
     /** Whether the plan's cursor rests in front of the step it is parked before. */
     atStop(): boolean;
     /**
@@ -450,11 +545,12 @@ export declare class ScenarioReplayPlan {
         text: string | null;
     } | undefined;
     /**
-     * The tool names of the steps from flat position `from` to the end, each
-     * that runs only under a test marked so — for a hand-over note's "remaining
-     * planned steps", which must not read as steps this request needs.
+     * The tool names of the steps from flat position `from` to the end (or to
+     * `until`, not included), each that runs only under a test marked so — for a
+     * hand-over note's "remaining planned steps", which must not read as steps
+     * this request needs.
      */
-    remainingFrom(from: number): string[];
+    remainingFrom(from: number, until?: number): string[];
     /** The steps the plan's own cursor has left out so far, in order (AC5). */
     leftOut(): readonly LeftOut[];
     /** Whether any planned step runs only under a test. */