@basein/runner 0.3.15 → 0.3.17

package/dist/control/transcript.js

@@ -397,6 +397,61 @@ function foldLine(idx, line) {
         }
     }
 }
+/**
+ * The model's text after the message that made the tool call `toolUseId`: its
+ * answer, once that call's result came back (the service's autocorrect.md
+ * AC11). Empty while none has been written, and when the call is not in the
+ * transcript — never an older text, which `lastAssistantText` can be: the
+ * sentence before a call, or the turn before's answer.
+ */
+export function textAfterToolUse(transcriptPath, toolUseId) {
+    if (!transcriptPath || !toolUseId)
+        return "";
+    const idx = indexFor(transcriptPath);
+    const at = idx?.toolUses.get(toolUseId)?.message;
+    if (!idx || at === undefined)
+        return "";
+    let after = false;
+    let text = "";
+    for (const [key, entry] of idx.messages) {
+        if (key === at) {
+            after = true;
+            continue;
+        }
+        if (after && entry.texts.length > 0)
+            text = entry.texts.join("");
+    }
+    return text.trim();
+}
+/**
+ * {@link textAfterToolUse}, waited for: up to `timeoutMs` for a text to appear,
+ * then until it stops changing for `confirmMs`. Empty when none came in time —
+ * a plan's report then goes without an answer, rather than with a wrong one.
+ */
+export async function settledTextAfterToolUse(transcriptPath, toolUseId, opts = {}) {
+    if (!transcriptPath || !toolUseId)
+        return "";
+    const pollMs = opts.pollMs ?? 150;
+    const confirmMs = opts.confirmMs ?? 400;
+    const deadline = Date.now() + (opts.timeoutMs ?? 2_000);
+    const sleep = () => new Promise((resolve) => {
+        const t = setTimeout(resolve, pollMs);
+        t.unref?.();
+    });
+    let latest = textAfterToolUse(transcriptPath, toolUseId);
+    let since = Date.now();
+    while (Date.now() < deadline) {
+        if (latest && Date.now() - since >= confirmMs)
+            return latest;
+        await sleep();
+        const now = textAfterToolUse(transcriptPath, toolUseId);
+        if (now !== latest) {
+            latest = now;
+            since = Date.now();
+        }
+    }
+    return latest;
+}
 /** Forget every cached index (tests; a caller that knows files were replaced). */
 export function forgetTranscripts() {
     indexes.clear();

package/dist/record/recorder.d.ts

@@ -61,6 +61,27 @@ export interface FlushOptions {
      */
     timeoutMs?: number;
 }
+/**
+ * A plan's own call recorded into the turn's newest run (the service's
+ * autocorrect.md AC2): which plan made it, which of its steps, and the chain
+ * revision it was served at — left out when the service served none, since
+ * its schema takes a number or nothing, never null.
+ */
+export interface PlanCallMark {
+    scenarioId: string;
+    stepIndex: number;
+    chainRevision?: number;
+}
+/**
+ * A recorded step's metadata. `pinnedBy`: a plan executed this step live in
+ * the turn (R-INTENT-7). `byPlan`: the plan made this call before the agent
+ * redid the task, and it is recorded first into the agent's repeat so the
+ * repeat holds the whole turn (AC2). The service stores neither with a vector.
+ */
+export type StepMetadata = {
+    pinnedBy?: string;
+    byPlan?: PlanCallMark;
+};
 export interface Recorder {
     /**
      * Create the run; returns the client-generated runId synchronously.
@@ -86,17 +107,18 @@ export interface Recorder {
         };
         /**
          * 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
+         * (R-INTENT-7), or made it before the agent redid the task (`byPlan`,
+         * AC2). 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;
-        };
+        metadata?: StepMetadata;
     }): string;
     recordToolResponse(runId: string, stepIndex: number, d: {
         toolName: string;
         toolOutput?: string;
         toolError?: string;
+        /** `byPlan` on the answer of a plan's own call (AC2); omitted otherwise. */
+        metadata?: StepMetadata;
     }): string;
     recordFinalAnswer(runId: string, stepIndex: number, d: {
         answer: string;
@@ -417,6 +439,27 @@ export interface ExecutionReport {
      * person reading the audit log, this is for the console.
      */
     declined?: string;
+    /**
+     * The plan ran to its end and the agent did not take its result: it went on
+     * with calls of its own, recorded as the recording's newest run with the
+     * reason `redone` (the service's newestRun.md N7, autocorrect.md AC1).
+     * `runId` is that repeat's own id; `ownCalls` the agent's own tool calls
+     * recorded into it — not the plan's calls recorded first (AC2), and not a
+     * step a plan pinned. Only on the report of the prompt's plan, and only when
+     * the service took the repeat; an older service drops the field.
+     */
+    redoneBy?: {
+        runId: string;
+        ownCalls: number;
+    };
+    /**
+     * The model's final answer, when the prompt's plan ran to its end and no
+     * redo of the model's own was recorded (the service's autocorrect.md AC11):
+     * the service checks whether the model took the plan's result, and holds and
+     * corrects the plan when it did not. Read from the transcript after the turn
+     * ends; an older service drops the field.
+     */
+    answer?: string;
 }
 /** Optional capability: reporting needs a service, and a NullRecorder has none. */
 export interface ScenarioReporter {

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

@@ -50,7 +50,7 @@
  */
 import { type AuthSession } from "../auth/client.js";
 import { type ServiceHealth } from "../util/service-health.js";
-import type { ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions } from "./recorder.js";
+import type { ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata } from "./recorder.js";
 /**
  * Caps for the free text this recorder sends, in UTF-8 bytes. Tool payloads
  * arrive capped at 64 KiB by their producers; text never passed through one,
@@ -70,6 +70,8 @@ export declare const TEXT_CAPS: {
     readonly toolError: number;
     /** An execution report's error lines, rendered in a web page. */
     readonly reportError: number;
+    /** The model's answer on a plan's report (AC11): the service keeps 4,000 characters of it. */
+    readonly reportAnswer: number;
 };
 /**
  * The most an execution report's request may weigh. The service reads this
@@ -225,14 +227,13 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
             text: string;
             source: "thinking";
         };
-        metadata?: {
-            pinnedBy: string;
-        };
+        metadata?: StepMetadata;
     }): string;
     recordToolResponse(runId: string, stepIndex: number, data: {
         toolName: string;
         toolOutput?: string;
         toolError?: string;
+        metadata?: StepMetadata;
     }): string;
     recordFinalAnswer(runId: string, stepIndex: number, data: {
         answer: string;

package/dist/record/remote-recorder.js

@@ -75,6 +75,8 @@ export const TEXT_CAPS = {
     toolError: 8 * 1024,
     /** An execution report's error lines, rendered in a web page. */
     reportError: 2 * 1024,
+    /** The model's answer on a plan's report (AC11): the service keeps 4,000 characters of it. */
+    reportAnswer: 8 * 1024,
 };
 /**
  * The most an execution report's request may weigh. The service reads this
@@ -674,6 +676,10 @@ export class RemoteRecorder {
             toolName: data.toolName,
             toolOutput: out(toolOutput),
             toolError: out(toolError),
+            // Omitted, not nulled, when absent: an ordinary answer is the body it
+            // has always been. Only a plan's own call recorded into a redo carries
+            // one (`byPlan`, the service's autocorrect.md AC2).
+            metadata: data.metadata,
         }));
         return id;
     }
@@ -738,12 +744,19 @@ export class RemoteRecorder {
         const costUsd = report.deriveCostUsd + report.sessionCostUsd + report.fallbackCostUsd;
         const prompt = pend(report.prompt, TEXT_CAPS.prompt);
         const error = pend(report.error, TEXT_CAPS.reportError);
+        const answer = pend(report.answer, TEXT_CAPS.reportAnswer);
         const steps = report.steps?.map(pendStep);
         this.enqueue({
             lane: EXECUTIONS,
             kind: "report",
-            bytes: sizeOf(prompt, error, ...(steps ?? []).flatMap((s) => [s.toolInput, s.toolOutput])) + 1024,
+            bytes: sizeOf(prompt, error, answer, ...(steps ?? []).flatMap((s) => [s.toolInput, s.toolOutput])) + 1024,
             send: async () => {
+                // A redo whose run the service refused to create is no run of its:
+                // never named (the service's autocorrect.md AC1), even when the
+                // refusal came after the report was built.
+                const redoneBy = report.redoneBy && this.runs.get(report.redoneBy.runId)?.settled?.created.created === false
+                    ? undefined
+                    : report.redoneBy;
                 const body = await this.request("POST", `/scenarios/${report.scenarioId}/executions`, 
                 // Per-step verdicts and the headline failure (errorshandling.md) ride
                 // beside the costs. All optional on the service side, so an older
@@ -776,6 +789,12 @@ export class RemoteRecorder {
                     // Why nothing ran, when nothing ran. Additive: an older service drops
                     // the field and books the cost exactly as it always did.
                     declined: report.declined,
+                    // The plan ran to its end and the agent redid the task (the
+                    // service's autocorrect.md AC1). Additive, like `declined`.
+                    redoneBy,
+                    // ...or only answered: its answer, capped and redacted like any
+                    // text (AC11). Additive, like `redoneBy`.
+                    answer: out(answer),
                 }, steps), { retryTransient: Boolean(report.ticket) });
                 const r = (body ?? {});
                 const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
@@ -795,6 +814,9 @@ export class RemoteRecorder {
                     baselineEligible: report.baselineEligible === false ? false : undefined,
                     sharedWith: report.sharedWith?.length,
                     declined: report.declined,
+                    // `bir investigate` prints it beside the outcome: "redone by run_…".
+                    redoneBy: report.redoneBy?.runId,
+                    ownCalls: report.redoneBy?.ownCalls,
                 });
             },
         });

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

@@ -90,11 +90,7 @@ export declare class SwitchableRecorder implements Recorder {
     currentAccessToken(): string | undefined;
     startRun(input: string, metadata?: Record<string, unknown>, options?: StartRunOptions): string;
     recordToolSelected(runId: string, stepIndex: number, d: Parameters<Recorder["recordToolSelected"]>[2]): string;
-    recordToolResponse(runId: string, stepIndex: number, d: {
-        toolName: string;
-        toolOutput?: string;
-        toolError?: string;
-    }): string;
+    recordToolResponse(runId: string, stepIndex: number, d: Parameters<Recorder["recordToolResponse"]>[2]): string;
     recordFinalAnswer(runId: string, stepIndex: number, d: {
         answer: string;
     }): string;

package/dist/replay/bundle.d.ts

@@ -34,7 +34,17 @@ export interface BundleEntry {
     response: string;
     /** True when `response` is a recorded output, not a fresh run. */
     recorded?: boolean;
+    /**
+     * Set on a step its test left out (the service's autocorrect.md AC5): no
+     * call was made, and the bundle says so in its place, so the model can tell
+     * a whole answer from a part. `text` is the test in words, when it has some.
+     */
+    notNeeded?: {
+        text: string | null;
+    };
 }
+/** The test's words, one line and short, for a bundle or a note. */
+export declare function testWords(text: string | null | undefined): string | null;
 /** Cap a computed input for inclusion in a bundle. */
 export declare function bundleInput(value: unknown): string;
 export interface AssembleOptions {

package/dist/replay/bundle.js

@@ -30,6 +30,13 @@ export const BASH_CHANNEL_MAX = 25_000;
 const MAX_INPUT_CHARS = 2_000;
 /** Fixed structural overhead reserved per step (labels, separators). */
 const PER_STEP_OVERHEAD = 80;
+/** The test's words, one line and short, for a bundle or a note. */
+export function testWords(text) {
+    const line = (text ?? "").trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
+    if (!line)
+        return null;
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
 /** Cap a computed input for inclusion in a bundle. */
 export function bundleInput(value) {
     let text;
@@ -90,7 +97,9 @@ const SUBTASK_FOOTER = "\n\nThe calls above are done. Continue your task, callin
  * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
  */
 export function assembleBundle(entries, maxChars, opts = {}) {
-    const n = entries.length;
+    // A step left out has no response to share the budget with: only the steps
+    // that answered split it.
+    const n = entries.filter((e) => !e.notNeeded).length;
     const anyRecorded = entries.some((e) => e.recorded);
     // 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
@@ -111,10 +120,22 @@ export function assembleBundle(entries, maxChars, opts = {}) {
                 : LIVE_FOOTER;
     const fixedCost = header.length +
         footer.length +
-        entries.reduce((sum, e) => sum + PER_STEP_OVERHEAD + e.toolName.length + e.input.length, 0);
+        entries.reduce((sum, e) => sum +
+            PER_STEP_OVERHEAD +
+            e.toolName.length +
+            e.input.length +
+            // A left-out step's line, which has no response to take from.
+            (e.notNeeded ? PER_STEP_OVERHEAD + (testWords(e.notNeeded.text)?.length ?? 0) : 0), 0);
     const responseBudget = Math.max(0, maxChars - fixedCost);
     const perResponse = n > 0 ? Math.floor(responseBudget / n) : responseBudget;
     const sections = entries.map((e, i) => {
+        if (e.notNeeded) {
+            // Never "skipped" or "failed": the step was left out on purpose, because
+            // this request does not need it, and nothing is missing for its absence.
+            const why = testWords(e.notNeeded.text);
+            return (`\n\n--- Step ${i + 1}: ${e.toolName} (not needed) ---\n` +
+                `Not run: this request does not need it${why ? ` — it is only for when ${why}` : ""}.`);
+        }
         const response = truncate(e.response, perResponse);
         return (`\n\n--- Step ${i + 1}: ${e.toolName} ---\n` +
             `Call: ${e.input}\n` +

package/dist/replay/controller.d.ts

@@ -514,6 +514,60 @@ export interface ReplayState {
      * sample of what the task costs unaided.
      */
     hostStop?: HostStop;
+    /**
+     * The served chain's revision, for the mark on the plan's own calls when
+     * they are recorded into the turn's newest run (autocorrect.md AC2).
+     */
+    chainRevision?: number;
+    /**
+     * Keep every call this plan makes, whole, for the turn's newest run: set by
+     * the control server on a prompt plan whose match offered to record the
+     * turn as a repeat. A plan that runs to its end and is then redone by the
+     * agent has its calls recorded first into that repeat (AC2) — the report's
+     * copies are cut to 3,800 bytes, and the agent's work is built on them.
+     */
+    keepCalls?: boolean;
+    /**
+     * Those calls, in the order the plan made them, keyed by frame and step —
+     * a sub-task called twice keeps both calls of each step.
+     */
+    turnCalls?: Map<string, TurnCall>;
+    /** What they hold, in characters: bounded by {@link TURN_CALLS_MAX_CHARS}. */
+    turnCallChars?: number;
+    /**
+     * Steer mode: the steps a test just left out (AC5), and the note that tells
+     * the model so — riding on the `PostToolUse` that moved the cursor past
+     * them, or given in place of a call the model makes to one of them.
+     */
+    skipNote?: {
+        text: string;
+        tools: Set<string>;
+        delivered: boolean;
+        refused?: number;
+        /**
+         * It says the sequence is complete — the steps left out were the plan's
+         * last. The only note that outlives the plan: every other one names a step
+         * to call next, which a retired plan no longer has (AC5 review).
+         */
+        complete?: boolean;
+    };
+}
+/**
+ * One of a plan's own calls, kept whole for the turn's newest run (the
+ * service's autocorrect.md AC2): redacted and capped like a recorded call,
+ * never cut to what a report carries.
+ */
+export interface TurnCall {
+    scenarioId: string;
+    stepIndex: number;
+    chainRevision: number | null;
+    toolName: string;
+    /** Serialized and redacted, at most 64 KiB, as a recorded call's input is. */
+    input: string;
+    /** The tool's answer, when it gave one; on the same terms. */
+    output?: string;
+    /** What it reported instead, when it failed. */
+    error?: string;
 }
 /**
  * Why a match did not arm. One code per gate of the ladder, so the caller can
@@ -522,10 +576,21 @@ export interface ReplayState {
 export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key"
 /** The service handed over no plan: this runner is too old for it. */
  | "runner_update_required"
+/**
+ * The service handed over no plan: it holds it, because the agent did the
+ * task again after the plan's last run (the service's autocorrect.md AC4).
+ */
+ | "held"
 /** The session's host only records: its adapter asked for no plan with the prompt. */
  | "host_records_only"
 /** The plan names a tool the host's agent does not hold. */
  | "host_tool_missing"
+/**
+ * The plan has steps that run only when a test says so (the service's
+ * autocorrect.md AC5), and the session's host is another app, whose adapter
+ * steps through a plan call by call and knows no tests yet.
+ */
+ | "host_tests_unsupported"
 /**
  * No gate said no: the plan was good, and late. Not ready when the prompt
  * had to be answered (`arm_timeout`), or ready just after it had been
@@ -786,6 +851,50 @@ export declare class ReplayController {
      * ({@link pinFailure}). `how` lets the caller say so outright.
      */
     postTool(state: ReplayState, toolUseId: string, output: string, failed?: string, how?: PostToolOptions): boolean;
+    /**
+     * A steer plan whose cursor reached its end: in front of a parked step (or a
+     * call the service could not answer), which hands over; otherwise it ran to
+     * its end — and from here every call is the model's own.
+     */
+    private finishSteer;
+    /**
+     * Move a plan's own cursor past the steps this request does not need, and
+     * act on what its tests decide (the service's autocorrect.md AC5). Every
+     * verdict is recorded as it is made. `stopped` means the plan handed over —
+     * the other half, a test that could not answer, or no step needed at all —
+     * and its note waits in {@link takeNote}. Otherwise the steps left out are
+     * named in a note for the model ({@link takeSkipNote}), and the caller goes
+     * on: a step is due, or the plan is done.
+     *
+     * Nothing at all for a plan without tests, which behaves exactly as before.
+     */
+    private settleCursor;
+    /** What the model is told about steps a test left out (AC5). */
+    private skipNoteText;
+    /**
+     * The note naming the steps a test just left out, claimed for delivery on a
+     * `PostToolUse` (AC5). Returned once; undefined when there is none.
+     */
+    takeSkipNote(state: ReplayState | undefined): string | undefined;
+    /**
+     * The same note, for a call the model is about to make to one of the steps
+     * it names — when the note has not reached the model yet. The control server
+     * gives it in place of that call, whether the plan is still steering or has
+     * just finished: a step left out must never run because the note was late.
+     */
+    skipNoteFor(state: ReplayState | undefined, toolName: string): string | undefined;
+    /**
+     * The pin guard took a call to the next step as that step: a note still
+     * waiting to say that a step before it was left out has nothing left to
+     * stop, and goes — as it went at the call before the guard existed.
+     */
+    pinTaken(state: ReplayState | undefined): void;
+    /**
+     * The plan's own calls of the turn, whole, in the order it made them — for
+     * the turn's newest run when the agent redoes the task (AC2). Empty unless
+     * the control server asked for them to be kept ({@link ReplayState.keepCalls}).
+     */
+    turnCallsOf(state: ReplayState | undefined): TurnCall[];
     /**
      * The result of a call pinned under a plan that has since handed over
      * because another call ran beside it (`concurrentCall`). Nothing threads —
@@ -854,6 +963,16 @@ export declare class ReplayController {
          * usual cost.
          */
         cutShort?: boolean;
+        /**
+         * The plan ran to its end and the agent redid the task in a repeat the
+         * service took (autocorrect.md AC1): that repeat's id and the agent's
+         * own calls in it. Only the control server knows, and only for the
+         * prompt's plan.
+         */
+        redoneBy?: {
+            runId: string;
+            ownCalls: number;
+        };
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic
@@ -951,6 +1070,13 @@ export declare class ReplayController {
      * step.
      */
     private stopKindOf;
+    /**
+     * The steps before flat position `bound` that ran, 1-based, and the ones
+     * their tests left out (AC5) — the plan cursor's own, and a divergence
+     * bundle's (`extra`). `left` is empty when no step was left out; `ran` is
+     * then not filled, since every step before `bound` ran.
+     */
+    private ranBefore;
     private noteFor;
     /**
      * The executor handed to a plan: dispatch a step to the proxy that owns its
@@ -1038,6 +1164,13 @@ export declare class ReplayController {
      * the recording's input and output beside this run's verdict.
      */
     private recordStep;
+    /**
+     * Keep one call of the plan whole (AC2): its arguments and its answer,
+     * redacted and capped as a recorded call's are. Later news about the same
+     * step replaces earlier, in place, so the order is the order the calls went
+     * out. Past {@link TURN_CALLS_MAX_CHARS} a call keeps only a report's cut.
+     */
+    private keepCall;
     /** The step verdicts, in chain order, for the execution report. */
     private stepResultsOf;
     private logStep;