@basein/runner 0.3.21 → 0.3.23

package/dist/replay/controller.d.ts

@@ -11,14 +11,13 @@
  * degrades to "run the turn normally" or returns something the session can
  * ignore. Nothing throws at a hook.
  */
-import type { ExecutionReport, MatchKey, MatchSegment, MatchVerdict } from "../record/recorder.js";
+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 { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
 import { type HostSinks } from "./safety.js";
 import { SourceRunOutputs } from "./source-run.js";
-import { type FlatStop } from "./flatten.js";
 import { type ExecutionOutcome, type ExecutionStepResult, type FallbackKind, type SerializedScenario, type SerializedScenarioStep } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
 export declare const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
@@ -239,14 +238,6 @@ export declare const RUN_NO_PLAN = "no_plan";
 export interface ReplayOptions {
     /** On unless `BIR_REPLAY=0`. Everything here is inert when false. */
     enabled: boolean;
-    /**
-     * Whether a handed-out segment may run mid-task. The recorder sets it from
-     * `BIR_SEGMENT_ARM`: on unless that is `0`, from runner 0.3.19 (the
-     * service's segmentsbreakdown.md SB-21). Omitted, as by a test or an
-     * embedder, it is off: observe-only, where the runner asks for no segment,
-     * arms none, and only logs what would have armed (R-OUT-10).
-     */
-    segmentArm?: boolean;
     /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
     allowServers?: ReadonlySet<string>;
     /**
@@ -307,21 +298,13 @@ export interface ReplayOptions {
 export interface IntentMatchOptions {
     /** `BIR_INTENT_MATCH`. */
     enabled: boolean;
-    /**
-     * How long a `PreToolUse` waits for the service. A timeout is a miss.
-     *
-     * 4 000 ms, not the 1 500 of Part 1: a request whose best segment lands in
-     * the *not clear* band has one live question to ask under the server's own
-     * 2 500 ms attempt, and must still answer well inside the hook's 30 s
-     * (segmented.md R-HIT-11). A clear match or a miss answers as fast as before.
-     */
+    /** How long a probe's request may take. A timeout is a miss. */
     budgetMs: number;
     /** Plans intent matching may arm in one turn. */
     maxPerTurn: number;
     /**
-     * Probes one turn may *send*. Separate from `maxPerTurn`, and much larger:
-     * arming three plans is a claim on the turn, while counting hits is only
-     * bookkeeping, and it must not stop at the third arm (R-HIT-5).
+     * Probes one turn may *send*. Separate from `maxPerTurn`, and larger: most
+     * probes find nothing, and a turn that armed nothing yet may still match.
      */
     maxRequestsPerTurn: number;
 }
@@ -401,24 +384,20 @@ export interface ReplayState {
     armedAt: number;
     reported: boolean;
     sourceRun?: SourceRunOutputs;
-    /**
-     * Why the flattener stopped the plan, when it is what stopped it: a call this
-     * chain cannot run right now (segmented.md R-CALL-29). The note names the
-     * sub-task and the reason, and the report carries `unusable_call`.
-     */
-    flatStop?: FlatStop;
     /** Set once a plan has been retired, so nothing re-arms mid-turn. */
     retired: boolean;
     /** What armed it: the prompt, or a ReAct iteration's intent (fallbk.md). */
     armedBy: "prompt" | "intent";
     /**
-     * The user's request this plan serves, in their own words: the prompt for a
-     * plan the prompt armed (set in `arm`), the turn's prompt for one an intent
-     * match armed (set by the control server). Read only for the note of a plan
-     * stopped at its decision, which quotes the request's condition sentences
-     * (the service's segmentsbreakdown.md SB-18). Never sent anywhere.
+     * Set on a continuation (the service's fallbk.md Part 3): a plan armed
+     * mid-turn because the plan before it handed over at a step, and the work
+     * recorded after an earlier hand-over at that step was calculated into this
+     * plan. `armedBy` is `intent` — it arms mid-turn, and is billed for its own
+     * window like any plan armed there — but it finishes the user's request
+     * rather than a part of the agent's own task, and its report books no
+     * saving: the plan it continued books the whole turn.
      */
-    request?: string;
+    continuation?: ContinuationOf;
     /**
      * The Claude Code session this plan serves, set by the control server. Its
      * steps run on that session's own proxies (executor.ts). Absent for `bir
@@ -443,25 +422,6 @@ export interface ReplayState {
      * paths, which resolve against the project directory as the host's do.
      */
     bashCwd?: string;
-    /**
-     * Which kind of row was handed out (segmented.md R-OUT-7). A `segment` is a
-     * named sub-task of a recording rather than a whole task, and it is judged
-     * against its own similarity gate. Absent from an older server, and then read
-     * as `scenario` (R-COMPAT-2).
-     */
-    kind: "scenario" | "segment";
-    /** Where a handed-out segment sits in its recording (R-OUT-8). */
-    segment?: MatchSegment;
-    /** Which of the segment's two keys scored (R-OUT-3). For logs. */
-    key?: MatchKey;
-    /** The cheap model's answer, when the score sat in the not-clear band. */
-    verified?: MatchVerdict;
-    /**
-     * Segments of this plan's own recording that armed later in the same turn
-     * (R-MONEY-4). Their share comes off this plan's baseline, so one recording's
-     * steps are never counted in two baselines of one turn.
-     */
-    sharedWith: string[];
     /** Set when the plan handed the task to the model part-way (fallbk.md). */
     handover?: Handover;
     /**
@@ -483,11 +443,9 @@ export interface ReplayState {
      */
     diverging?: boolean;
     /**
-     * Which gate declined, as a fixed code (segmented.md R-HIT-14). The prose
-     * `why` that `decline()` logs stays free text; this is what code reads — the
-     * position rule (R-OUT-6) reports a position only for `known_bad_first_step`,
-     * and reading prose for that would break the first time a sentence was
-     * reworded.
+     * Which gate declined, as a fixed code. The prose `why` that `decline()`
+     * logs stays free text; this is what code and the report read, and reading
+     * prose would break the first time a sentence was reworded.
      */
     declined?: DeclineCode;
     /**
@@ -507,10 +465,7 @@ export interface ReplayState {
      * A plan that finished its work stops costing at that moment: the agent's
      * later work in the same turn is the agent's, not this plan's. A plan that
      * handed over or diverged takes no mark, because the follow-on work is the
-     * direct consequence of its stopping (R-MONEY-3, R-FALL-5) — except a plan
-     * stopped at its decision after a step ran: it did all it was for, and the
-     * agent's decision and the half it chose are the agent's own (the service's
-     * segmentsbreakdown.md SB-26).
+     * direct consequence of its stopping (R-MONEY-3, R-FALL-5).
      */
     retiredMark?: unknown;
     retiredAt?: number;
@@ -578,10 +533,7 @@ export interface ReplayState {
      * 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.
-     */
+    /** Those calls, in the order the plan made them, keyed by step. */
     turnCalls?: Map<string, TurnCall>;
     /** What they hold, in characters: bounded by {@link TURN_CALLS_MAX_CHARS}. */
     turnCallChars?: number;
@@ -624,7 +576,7 @@ export interface TurnCall {
  * Why a match did not arm. One code per gate of the ladder, so the caller can
  * act on a decline without parsing the sentence that explains it.
  */
-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"
+export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_step" | "nondeterministic_first_step" | "coverage" | "missing_target" | "no_derive_key"
 /** The service handed over no plan: this runner is too old for it. */
  | "runner_update_required"
 /**
@@ -654,7 +606,33 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "
  * the prompt had been answered, or while prompts were not waiting on it
  * (the match gate). Set by the control server, like the two above.
  */
- | "match_late";
+ | "match_late"
+/**
+ * A continuation (the service's fallbk.md Part 3) whose first step is not
+ * the call the model is making after the hand-over: another tool, or the
+ * same tool on something else. The model chose what to do next — the
+ * judgement the plan before it stopped for — and chose otherwise. Set by
+ * the control server.
+ */
+ | "not_first_step";
+/**
+ * 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
+ * work done after an earlier hand-over there, which this plan was calculated
+ * from.
+ */
+export interface ContinuationOf {
+    ofScenarioId: string;
+    stepIndex: number;
+    runId: string;
+}
+/**
+ * Whether a plan is a part of the task the agent is already doing — armed
+ * mid-turn by its intent — so its words say "continue" and never "answer the
+ * user". A continuation is armed mid-turn too, and it is the rest of the
+ * user's request: it ends with the answer.
+ */
+export declare function isSubTask(state: Pick<ReplayState, "armedBy" | "continuation">): boolean;
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -711,16 +689,6 @@ export declare class ReplayController {
      */
     private hostSignals;
     constructor(opts: ReplayOptions);
-    /**
-     * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
-     *
-     * Only when the option says so. The recorder passes it on unless
-     * `BIR_SEGMENT_ARM=0` (from 0.3.19; the service's segmentsbreakdown.md
-     * SB-21); a controller built without it stays observe-only, asks for no
-     * segment and arms none. The server enforces the same thing from its side
-     * (R-OUT-9).
-     */
-    get segmentArm(): boolean;
     /** The plan's own delivery vehicle is never a scenario step. */
     isDirectTool(toolName: string): boolean;
     /**
@@ -742,6 +710,14 @@ export declare class ReplayController {
      * itself as one that never reported.
      */
     lateMatch(match: RunMatchLike, host?: HostContext): ReplayState;
+    /**
+     * The state of a continuation handed out and not armed (the service's
+     * fallbk.md Part 3): declined before any gate ran — its first step is not
+     * the model's call (`not_first_step`), or the service's answer came too
+     * late (`match_late`). Like {@link lateMatch}, it exists only for its
+     * ticket's report, with the reason.
+     */
+    declinedContinuation(match: RunMatchLike, code: DeclineCode, continuation: ContinuationOf): ReplayState;
     /**
      * Run the gate ladder and, if every gate passes, arm a plan.
      *
@@ -750,24 +726,21 @@ export declare class ReplayController {
      * up with a denominator nobody measured.
      *
      * `host` is given for a session whose host is not Claude Code, and is kept
-     * on the state (see {@link HostContext}).
+     * on the state (see {@link HostContext}). `extra.continuation` arms a
+     * continuation (the service's fallbk.md Part 3): see
+     * {@link ReplayState.continuation}.
      */
-    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext, host?: HostContext): Promise<ReplayState>;
+    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext, host?: HostContext, extra?: {
+        continuation?: ContinuationOf;
+    }): Promise<ReplayState>;
     /**
      * The armed plan as data: the steps it will run, in order, and where it
      * stops when that is before its end. For a host that steps through the plan
      * itself and must not have to pick the tool names out of a directive
      * written for a model — a reworded sentence would break every adapter in
-     * the field. Built from the same entries the directive lists.
+     * the field. Built from the same steps the directive lists.
      */
     planData(state: ReplayState): PlanData | undefined;
-    /**
-     * Whether the plan's steps end in front of a decision (the service's
-     * segmentsbreakdown.md SB-6): it runs the steps before it, then hands the
-     * task back there. The control server gives such a plan a usage mark, so
-     * that it is billed only up to the stop (SB-26).
-     */
-    stopsAtDecision(state: ReplayState): boolean;
     /**
      * Take back a plan that armed and has run nothing, as a decline.
      *
@@ -914,9 +887,9 @@ export declare class ReplayController {
      */
     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.
+     * A steer plan whose cursor reached its end: in front of a parked step,
+     * which hands over; otherwise it ran to its end — and from here every call
+     * is the model's own.
      */
     private finishSteer;
     /**
@@ -1035,6 +1008,13 @@ export declare class ReplayController {
             runId: string;
             ownCalls: number;
         };
+        /**
+         * What the continuations of this plan spent reading their values this
+         * turn (the service's fallbk.md Part 3). Booked here, on the plan whose
+         * report bills the whole turn: theirs book no saving, so a cost left on
+         * them would be left out of the turn's saving.
+         */
+        chainDeriveUsd?: number;
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic
@@ -1057,10 +1037,6 @@ export declare class ReplayController {
      * there is nothing to be similar *to* and nothing to decline. It books no
      * execution either — there is no ticket, and inventing a saving for a manual
      * invocation is exactly the kind of number a ledger must never contain.
-     *
-     * One served stop is kept: a plan's decision (the service's
-     * segmentsbreakdown.md SB-6). The run stops in front of it, and `stopped`
-     * says so with the reason `decision`.
      */
     runAdHoc(scenario: SerializedScenario, prompt: string, wrapped: ReadonlySet<string>): Promise<{
         ok: boolean;
@@ -1130,23 +1106,10 @@ export declare class ReplayController {
      */
     private handOver;
     /**
-     * Which kind of stop a plan's end is (plan-services.md D8). The stopping
-     * step's own served reason wins — the calculation's verdict is more exact
-     * than a counter — then a call the service could not answer, then a parked
-     * step.
-     */
-    private stopKindOf;
-    /**
-     * A divergence's bundle that ended at the plan's decision (SB-17): logged
-     * as `handOver` logs every other hand-over, and its usage mark taken there
-     * when a step of the plan ran (SB-26).
-     */
-    private decidedInDivergence;
-    /**
-     * 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.
+     * The steps before 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;
@@ -1255,12 +1218,6 @@ export declare class ReplayController {
     /** Outcomes only move forward; `not_steered` is the floor (§11.1). */
     private upgrade;
     private retire;
-    /**
-     * Where the plan's work ended, for its bill: now, and the transcript's
-     * watermark now. Taken at a completing retire, and at a decision hand-over
-     * after a step ran (the service's segmentsbreakdown.md SB-26).
-     */
-    private markRetired;
 }
 /** The subset of `RunMatch` replay consumes. Structural, so tests need no recorder. */
 export interface RunMatchLike {
@@ -1272,11 +1229,6 @@ export interface RunMatchLike {
     fallback?: {
         maxStepFailures: number;
     };
-    /** All absent from an older server (segmented.md R-COMPAT-2). */
-    kind?: "scenario" | "segment";
-    segment?: MatchSegment;
-    key?: MatchKey;
-    verified?: MatchVerdict;
     /** The frozen name, beside the runtime intent the plan runs on (R-INTENT-12). */
     intentName?: string;
     /** Why the service handed over no plan, when it says. Read for `runner_update_required`. */
@@ -1295,8 +1247,7 @@ export declare function knownBadStepIndex(steps: readonly SerializedScenarioStep
  *
  * A step that carries `stop` was decided by the service — `null` means run it,
  * even when its count is past the limit: its retry is due. A step without the
- * field came from an older service, and the old counter rule decides it. Both
- * can sit in one chain, since a called segment is served on its own terms.
+ * field came from an older service, and the old counter rule decides it.
  */
 export declare function stopIndex(steps: readonly SerializedScenarioStep[], maxStepFailures: number | undefined): number | undefined;
 export {};