@basein/runner 0.3.26 → 0.3.28

package/dist/replay/controller.d.ts

@@ -11,7 +11,7 @@
  * degrades to "run the turn normally" or returns something the session can
  * ignore. Nothing throws at a hook.
  */
-import type { ExecutionReport } from "../record/recorder.js";
+import type { ExecutionReport, ExecutionTurn, TurnUsage } 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";
@@ -92,6 +92,13 @@ export interface PreToolOptions {
      * route's deadline guard spoke first. No further step is started.
      */
     signal?: AbortSignal;
+    /**
+     * The call only looks and changes nothing (replay/reads-only.ts), as the
+     * control server judged it with what the tool's server says of it. A direct
+     * plan the model has not asked for yet lets such a call through and waits
+     * for `run_scenario` (B2 is11.md); nothing runs in its place.
+     */
+    readsOnly?: boolean;
 }
 /**
  * What the caller knows about how a pinned call ended, beyond its error text
@@ -353,6 +360,15 @@ export interface Handover {
     error?: string;
     /** For a `step_failed`: where the stopped step stood ({@link stopOf}). */
     stop?: string;
+    /**
+     * Why it stopped, as a code: for a `step_failed` the stop's own reason
+     * (`budget`, `cancelled`, `test_failed`, `concurrent`, `host_rejected`, …),
+     * `failed` for a plain failure; for another kind the kind itself. Only the
+     * report reads it (the service's learningPhase.md LP11): {@link stop}
+     * folds the stops in front of a step into `not_run`, and that is all the
+     * service needs to continue one, not to tell why a plan stopped.
+     */
+    reason?: 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. */
@@ -461,6 +477,16 @@ export interface ReplayState {
     bashCwd?: string;
     /** Set when the plan handed the task to the model part-way (fallbk.md). */
     handover?: Handover;
+    /**
+     * Characters this plan handed the agent to read so far — `run_scenario`'s
+     * answer, a divergence's bundle, the notes told in place of a call or
+     * beside its result — for the report's `turn` (the service's
+     * learningPhase.md LP11). Counted where the text leaves for the agent,
+     * never where it is built: a note made and never delivered was not read.
+     */
+    handedChars?: number;
+    /** The bundle this plan handed the agent, when it handed one: brief (0.3.25), or the full one. */
+    bundleKind?: "brief" | "full";
     /**
      * Every planned step ran and the model was handed the results to answer
      * from: a steered plan whose last step threaded, a direct run that ran to
@@ -514,6 +540,12 @@ export interface ReplayState {
     running?: Promise<RunArmedResult>;
     /** The model called `run_scenario` for this plan (its `PreToolUse` was seen). */
     directRequested?: boolean;
+    /**
+     * Calls that only look, made while this direct plan waited for
+     * `run_scenario` (B2 is11.md): each ran as the model wrote it, and the plan
+     * stayed announced. The first is told the plan still waits, once.
+     */
+    readsWaited?: number;
     /**
      * The direct run's caller went away mid-run — Esc on `run_scenario`, or its
      * client timing out. The turn it cut short is no measurement of the task, so
@@ -677,7 +709,23 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_ste
  * failed on this request, so none of its steps could be computed. Set by
  * the control server.
  */
- | "params_failed";
+ | "params_failed"
+/**
+ * A direct plan announced to the model, which made a call that may change
+ * something before it called `run_scenario`: the plan retired running
+ * nothing, because run after the model's own change it could do the same
+ * work twice. Calls that only look before it do not count (B2 is11.md).
+ * Set by the control server (runners after 0.3.26; up to it, such a plan
+ * was retired at any first call, and reported no reason).
+ */
+ | "changed_first"
+/**
+ * A direct plan whose `run_scenario` call never reached the runner: the
+ * person refused it, a rule denied it, or it failed on the way. Refused
+ * means refused: the plan retired running nothing. Set by the control
+ * server (runners after 0.3.26; up to it, reported with no reason).
+ */
+ | "run_refused";
 /**
  * What a continuation continues (the service's fallbk.md Part 3): the plan
  * that handed over, the step it stopped in front of, and the recording of the
@@ -696,6 +744,14 @@ export interface ContinuationOf {
  * user's request: it ends with the answer.
  */
 export declare function isSubTask(state: Pick<ReplayState, "armedBy" | "continuation">): boolean;
+/**
+ * The report's `turn` (the service's learningPhase.md LP11): what this plan
+ * did in the turn, from its state, and the window's tokens and model calls,
+ * which only the control server can read (`usage`; undefined when it could
+ * not). Every value is null when it is not known, and nothing here throws: a
+ * state it cannot read is a `turn` of nulls, never a report lost.
+ */
+export declare function turnOf(state: ReplayState, usage?: TurnUsage): ExecutionTurn;
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -874,6 +930,13 @@ export declare class ReplayController {
      * Returns it once and marks it delivered; undefined when there is none.
      */
     takeNote(state: ReplayState | undefined): string | undefined;
+    /**
+     * The hand-over note `run_scenario` answers with: claimed when it is still
+     * to tell ({@link takeNote}), and told again when it was told already — the
+     * same text the run always answered (`takeNote(state) ?? the note`), now
+     * counted as read either way.
+     */
+    private runNote;
     /** 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;
     /**
@@ -1091,6 +1154,12 @@ export declare class ReplayController {
          * own baseline, so the turn's saving is booked somewhere.
          */
         booksOwnSaving?: boolean;
+        /**
+         * The model calls and tokens of the window `sessionCostUsd` was read
+         * for, for the report's `turn` (the service's learningPhase.md LP11).
+         * Only the control server holds the transcript; absent, they are null.
+         */
+        usage?: TurnUsage;
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic

package/dist/replay/controller.js

@@ -221,6 +221,10 @@ export function sentACall(state) {
     }
     return false;
 }
+/** {@link Handover.reason}: a stopped step's own reason, `failed` for a plain failure, else the kind. */
+function handoverReason(kind, stopReason) {
+    return kind === "step_failed" ? (stopReason ?? "failed") : kind;
+}
 /**
  * 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
@@ -255,6 +259,59 @@ const TURN_CALLS_MAX_CHARS = 8 * 1024 * 1024;
 export function isSubTask(state) {
     return state.armedBy === "intent" && state.continuation === undefined;
 }
+/**
+ * Count text the plan hands the agent to read ({@link ReplayState.handedChars}),
+ * where it leaves for the agent. Adds a length and nothing else.
+ */
+function handed(state, text) {
+    if (!state || typeof text !== "string" || text.length === 0)
+        return;
+    state.handedChars = (state.handedChars ?? 0) + text.length;
+}
+/** Longest `stop` or `reason` a report's `turn` carries: they are codes, and a code is short. */
+const TURN_CODE_MAX = 64;
+const turnCode = (value) => typeof value === "string" && value !== "" ? value.slice(0, TURN_CODE_MAX) : null;
+/**
+ * The report's `turn` (the service's learningPhase.md LP11): what this plan
+ * did in the turn, from its state, and the window's tokens and model calls,
+ * which only the control server can read (`usage`; undefined when it could
+ * not). Every value is null when it is not known, and nothing here throws: a
+ * state it cannot read is a `turn` of nulls, never a report lost.
+ */
+export function turnOf(state, usage) {
+    const count = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 ? Math.round(n) : null;
+    try {
+        const armed = state.mode === "direct" || state.mode === "steer";
+        const h = state.handover;
+        return {
+            mode: armed ? state.mode : null,
+            modelCalls: count(usage?.modelCalls),
+            inputTokens: count(usage?.inputTokens),
+            outputTokens: count(usage?.outputTokens),
+            cacheReadTokens: count(usage?.cacheReadTokens),
+            cacheWriteTokens: count(usage?.cacheWriteTokens),
+            bundleChars: armed ? count(state.handedChars ?? 0) : null,
+            brief: state.bundleKind === "brief" ? true : state.bundleKind === "full" ? false : null,
+            // Read by the control server after the turn, when it reads the answer (AC11).
+            answerChars: null,
+            handover: h ? { stop: turnCode(h.stop), reason: turnCode(h.reason) } : null,
+        };
+    }
+    catch {
+        return {
+            mode: null,
+            modelCalls: null,
+            inputTokens: null,
+            outputTokens: null,
+            cacheReadTokens: null,
+            cacheWriteTokens: null,
+            bundleChars: null,
+            brief: null,
+            answerChars: null,
+            handover: null,
+        };
+    }
+}
 export class ReplayController {
     enabled;
     work = new ProxyWorkQueue();
@@ -700,21 +757,24 @@ export class ReplayController {
             stopAt,
             subTask: isSubTask(state),
         });
-        if (mode === "steer") {
-            // A steer directive shows the arguments the steps will run with, so the
-            // call the model writes is one the pin guard accepts (plan.ts,
-            // `steeringDirective`). That needs the parameters settled — which costs
-            // nothing when the derivation has already answered: gate 7 waited for
-            // it, or there was nothing to derive. One turn of the loop lets an answer
-            // that is already in hand through; one still on its way is not waited
-            // for here, and the directive simply leaves the arguments to the system,
-            // as it always did. A `paramsLogic` that throws is not judged here: the
-            // first call that needs the parameters meets the same failure, as before.
-            if (!deriveAnswered)
-                await new Promise((resolve) => setImmediate(resolve));
-            if (deriveAnswered)
-                await state.plan.ready().catch(() => undefined);
-        }
+        // A steer directive shows the arguments the steps will run with, so the
+        // call the model writes is one the pin guard accepts (plan.ts,
+        // `steeringDirective`). A direct one says which of this request's values
+        // the steps take, and puts this request's values where the recording's
+        // stand in its intent (B2 is11.md): "set Olga up" under a request for
+        // Carlos made a careful model check first, and that check retired the
+        // plan. Both need the parameters settled — which costs nothing when the
+        // derivation has already answered: gate 7 waited for it, or there was
+        // nothing to derive. One turn of the loop lets an answer that is already
+        // in hand through; one still on its way is not waited for here, and the
+        // directive leaves the values out (a direct one names each recorded value
+        // by its role instead). A `paramsLogic` that throws is not judged here:
+        // the first call that needs the parameters meets the same failure, as
+        // before.
+        if (!deriveAnswered)
+            await new Promise((resolve) => setImmediate(resolve));
+        if (deriveAnswered)
+            await state.plan.ready().catch(() => undefined);
         state.mode = mode;
         state.stepsPlanned = steps.length;
         // The chain this plan was served at: what its own calls are marked with
@@ -967,6 +1027,7 @@ export class ReplayController {
                 scenario: state.scenarioId ?? undefined,
                 bytes: h.note.length,
             });
+            handed(state, h.note);
             return h.note;
         }
         // A plan that ran to its end with nobody there to read it has no
@@ -975,10 +1036,25 @@ export class ReplayController {
         if (u && !u.delivered) {
             u.delivered = true;
             logDetail("replay.unseen_delivered", { scenario: state.scenarioId ?? undefined, bytes: u.note.length });
+            handed(state, u.note);
             return u.note;
         }
         return undefined;
     }
+    /**
+     * The hand-over note `run_scenario` answers with: claimed when it is still
+     * to tell ({@link takeNote}), and told again when it was told already — the
+     * same text the run always answered (`takeNote(state) ?? the note`), now
+     * counted as read either way.
+     */
+    runNote(state) {
+        const note = this.takeNote(state);
+        if (note !== undefined)
+            return note;
+        const again = state.handover?.note;
+        handed(state, again);
+        return again;
+    }
     /** 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));
@@ -1055,6 +1131,16 @@ export class ReplayController {
             });
             return { kind: "passthrough" };
         }
+        // A CALL THAT ONLY LOOKS DOES NOT END A DIRECT PLAN (B2 is11.md). Asked
+        // for `run_scenario` first, the model looked at something first instead —
+        // in is11 its own notes, after the note had named another request's
+        // person. Read as a divergence, this call would run every step here,
+        // unattended; read as the model leaving the plan, it retired a plan that
+        // would have done the task right. It is neither: it runs as written,
+        // nothing runs in its place, and the plan waits for `run_scenario`. The
+        // control server retires it at the first call that may change something.
+        if (state.mode === "direct" && hook.readsOnly === true)
+            return { kind: "passthrough" };
         // Everything below — the wait for the parameters, and a divergence that
         // executes the rest of the plan — happens inside this one hook, which the
         // host waits on for a bounded time. One deadline covers all of it — and
@@ -1142,6 +1228,7 @@ export class ReplayController {
             if (skip && toolName !== plan.expectedTool() && skip.tools.has(toolName) && (skip.refused ?? 0) < 2) {
                 skip.delivered = true;
                 skip.refused = (skip.refused ?? 0) + 1;
+                handed(state, skip.text);
                 return this.deliverInstead(skip.text, toolName, otherHost);
             }
             // A call to the next step's tool: a note the model has read is done
@@ -1673,6 +1760,7 @@ export class ReplayController {
         if (!skip || skip.delivered)
             return undefined;
         skip.delivered = true;
+        handed(state, skip.text);
         return skip.text;
     }
     /**
@@ -1686,6 +1774,7 @@ export class ReplayController {
         if (!skip || skip.delivered || !skip.tools.has(toolName))
             return undefined;
         skip.delivered = true;
+        handed(state, skip.text);
         return skip.text;
     }
     /**
@@ -1874,7 +1963,7 @@ export class ReplayController {
                 delivery: "none",
                 stopReason: "not_run",
             });
-            return handedOver(this.takeNote(state) ?? state.handover?.note) ?? { ok: false, why: ready.error };
+            return handedOver(this.runNote(state)) ?? { ok: false, why: ready.error };
         }
         const deadline = Date.now() + this.budgets.planMs;
         let result;
@@ -1968,12 +2057,15 @@ export class ReplayController {
                     ? { ok: true, text: `${note}\n\n${result.text}`, responseModel: {}, steps: result.executed + result.recorded, partial: true }
                     : (handedOver(note) ?? { ok: false, why: note });
             }
-            const note = this.takeNote(state) ?? state.handover?.note ?? "";
+            const note = this.runNote(state) ?? "";
             if (!live) {
                 // Nothing ran: the tool answers with an error that says so, which is
                 // what a model reacts to best.
                 return handedOver(note) ?? { ok: false, why: note };
             }
+            // The note in front was counted as it was claimed; the rest of the answer here.
+            handed(state, `\n\n${result.text}`);
+            state.bundleKind = result.brief ? "brief" : "full";
             return {
                 ok: true,
                 text: `${note}\n\n${result.text}`,
@@ -1993,7 +2085,7 @@ export class ReplayController {
                 ran: 0,
                 noneNeeded: true,
             });
-            return handedOver(this.takeNote(state) ?? state.handover?.note) ?? { ok: false, why: "" };
+            return handedOver(this.runNote(state)) ?? { ok: false, why: "" };
         }
         if (result.executed === 0) {
             // Every step stood on its recorded output (BIR_REPLAY_RECORDED_OUTPUTS):
@@ -2008,7 +2100,7 @@ export class ReplayController {
                 stopReason: "not_run",
                 ran: 0,
             });
-            return handedOver(this.takeNote(state) ?? state.handover?.note) ?? { ok: false, why: "" };
+            return handedOver(this.runNote(state)) ?? { ok: false, why: "" };
         }
         // Live steps only, as above: a recorded stand-in did no work here.
         state.stepsPinned += result.executed;
@@ -2074,6 +2166,19 @@ export class ReplayController {
                 why: "the caller went away during the last step — every step ran and nobody read the results",
             });
         }
+        else {
+            // What `run_scenario` hands the agent: the bundle, and the response
+            // model `bir-scenario` puts under it when there is one.
+            handed(state, result.text);
+            try {
+                if (Object.keys(responseModel).length > 0)
+                    handed(state, JSON.stringify(responseModel));
+            }
+            catch {
+                // A model no JSON can carry reaches the agent as nothing: nothing to count.
+            }
+            state.bundleKind = result.brief ? "brief" : "full";
+        }
         return {
             ok: true,
             text: result.text,
@@ -2189,6 +2294,10 @@ export class ReplayController {
                 d.cutShort === true
                 ? false
                 : undefined,
+            // How the plan ran, what the turn's model calls and tokens were, what
+            // the agent was handed to read, and why it handed over (LP11). Only
+            // facts the runner already had; an older service drops the field.
+            turn: turnOf(state, d.usage),
         };
     }
     /**
@@ -2569,12 +2678,14 @@ export class ReplayController {
             // done its work, and the model must know before it does the task itself.
             if (stop?.reason === "uncertain" && stop.position !== undefined) {
                 const note = this.stopNote(state, plan, stop, "none", composed.left);
+                handed(state, note);
                 return this.deliverInstead(note, toolName, state.host !== undefined);
             }
             // The rest is the other half (AC5): the model is told so, in place of
             // its call, before it does any of the plan's remaining steps.
             if (stop?.kind === "other_branch" && stop.position !== undefined) {
                 const note = this.stopNote(state, plan, stop, "none", composed.left);
+                handed(state, note);
                 return this.deliverInstead(note, toolName, state.host !== undefined);
             }
             // Every remaining step was left out by its test: the steps the session
@@ -2602,6 +2713,7 @@ export class ReplayController {
                 kind: stopKind,
                 stepIndex: parked.stepIndex,
                 toolName: parked.toolName ?? undefined,
+                reason: stopKind,
                 note: this.noteFor(state, {
                     kind: stopKind,
                     step: parked,
@@ -2625,6 +2737,10 @@ export class ReplayController {
         // reason is read as adversarial interception.
         const action = this.deliverInstead(text, toolName, state.host !== undefined);
         logDetail("replay.inject", { channel: action.kind, bytes: text.length });
+        // What the agent reads of it: the whole text as a refusal's reason, as
+        // much as the channel carries as a command's output.
+        handed(state, action.kind === "bash" ? text.slice(0, BASH_CHANNEL_MAX) : text);
+        state.bundleKind = "full";
         return action;
     }
     /**
@@ -2662,6 +2778,7 @@ export class ReplayController {
             ...(stop.kind === "step_failed"
                 ? { stop: stopOf({ ranThisStep: stop.stage === "tool_output_logic", stopReason: stop.reason }) }
                 : {}),
+            reason: handoverReason(stop.kind, stop.reason),
             note,
             delivered: true,
         };
@@ -2686,6 +2803,7 @@ export class ReplayController {
             toolName: h.step?.toolName ?? undefined,
             error: h.error,
             ...(h.kind === "step_failed" ? { stop: stopOf(h) } : {}),
+            reason: handoverReason(h.kind, h.stopReason),
             note: this.noteFor(state, h),
             delivered: false,
         };

package/dist/replay/plan.d.ts

@@ -514,6 +514,47 @@ export declare class ScenarioReplayPlan {
      * body gets at most `bodyMs` ({@link PREVIEW_LOGIC_MS}) of it.
      */
     private previewArguments;
+    /**
+     * This request's value of `key`, as a directive may show it, or undefined
+     * (B2 is11.md): once the reading has settled, a plain value the reading
+     * took from the request — never a mark, and never a value a step works out
+     * (`from: "step"`): before the run nobody has that one, and the recorded one
+     * is another request's (issue 1212).
+     */
+    private shownValueOf;
+    /**
+     * A text written from the recording — the intent, a step's reasoning — put
+     * right for this request, for a directive to show (B2 is11.md).
+     *
+     * Both name the recording's values: "set Olga up", "moves each lead to
+     * Olga". Shown beside a request for Carlos, the name tells the model the
+     * plan is for someone else. A careful model then checks before it runs
+     * anything, and a direct plan's first call that was not `run_scenario`
+     * retired it — so the replay was lost on exactly the turn replay is for: the
+     * same task with a new value. The steps never read the text: they take
+     * Carlos from the request.
+     *
+     * Each recorded value of a parameter found in the text, as a whole word, is
+     * replaced by this request's own value where the plan has one it may show
+     * ({@link shownValueOf}), and else by the parameter's role (`<assignee
+     * name>`): a target the request did not name, a value a step works out, or
+     * any value while the reading has not settled. A value the same as the
+     * recorded one stays as it is. One pass, longest value first, so nothing put
+     * in is replaced again.
+     */
+    forThisRequest(text: string): string;
+    /** {@link forThisRequest} as one function, built once for a directive's many texts. */
+    private rewriter;
+    /**
+     * This request's own values, for the direct directive's line that says the
+     * steps take them (B2 is11.md): what the reading took from the request.
+     * The values the request names in words come first — a name, a title: what
+     * a reader holds the note against — those unlike the recording's first;
+     * then the values worked out from the day ("tomorrow" as a date). Targets
+     * only: never a setting, never a value a step works out, never a mark.
+     * Undefined until the reading has settled, or when it named none.
+     */
+    requestValues(): string | undefined;
     /**
      * The directive injected via `UserPromptSubmit`'s `additionalContext`.
      *