@basein/runner 0.2.0 → 0.2.2

package/dist/replay/controller.d.ts

@@ -11,13 +11,14 @@
  * 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, MatchKey, MatchSegment, MatchVerdict } from "../record/recorder.js";
 import { type ReplayMode, type StepReach } from "./coverage.js";
-import { deriveParameters } from "./derive.js";
+import { deriveParameters, type DeriveContext } from "./derive.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
 import { SourceRunOutputs } from "./source-run.js";
-import { type ExecutionOutcome, type ExecutionStepResult, type SerializedScenario } from "./types.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";
 /** How long a `/proxy/poll` is held open before it answers empty. */
@@ -38,10 +39,25 @@ export interface ReplayOptions {
     enabled: boolean;
     /** Minimum similarity to steer — deliberately above the service's detection threshold. */
     minSimilarity: number;
+    /**
+     * Minimum similarity to steer a **segment** (`BIR_MIN_SEGMENT_STEER_SIMILARITY`,
+     * segmented.md R-OUT-11). The same number as the server's clear band, so a
+     * clear hand-out is always accepted and no score falls between "clear" and
+     * "accepted".
+     */
+    minSegmentSimilarity?: number;
+    /**
+     * `BIR_SEGMENT_ARM`. Off means observe-only: the runner asks for no segment
+     * and 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>;
     budgets?: Partial<ReplayBudgets>;
-    /** For the lazy source-run fetch and nothing else. */
+    /**
+     * The service: the lazy source-run fetch, and the parameter derivation this
+     * runner no longer needs a key of its own for (segmented.md R-PARAM-5).
+     */
     authUrl?: string;
     authToken?: () => string;
     /** Injected by tests. */
@@ -49,6 +65,46 @@ export interface ReplayOptions {
     fetchImpl?: typeof fetch;
     /** Anthropic key for derivation. Absent → recorded sample values, free. */
     apiKey?: string;
+    /**
+     * Intent matching in the ReAct loop (fallbk.md §Runner 4): while the model is
+     * driving, each tool call's reasoning is matched against scenario intents.
+     * Only consulted when `enabled` is on as well. Omitted means on, with defaults.
+     */
+    intentMatch?: Partial<IntentMatchOptions>;
+}
+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.
+     */
+    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).
+     */
+    maxRequestsPerTurn: number;
+}
+export declare const DEFAULT_INTENT_MATCH: IntentMatchOptions;
+/** The turn handed back to the model part-way (fallbk.md). */
+export interface Handover {
+    kind: FallbackKind;
+    /** The scenario's own `stepIndex` of the step it stopped at. */
+    stepIndex: number;
+    toolName?: string;
+    error?: 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. */
+    delivered: boolean;
 }
 /** One pinned call, remembered so its output is threaded from the right source. */
 interface PinnedCall {
@@ -88,13 +144,76 @@ export interface ReplayState {
      * `PreToolUse`, threaded in `PostToolUse`), and the second word on a step
      * replaces the first rather than appending a second verdict for it.
      */
-    stepResults: Map<number, ExecutionStepResult>;
+    stepResults: Map<string, ExecutionStepResult>;
     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";
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    declined?: DeclineCode;
+    /**
+     * Opaque to the controller: the control server's transcript watermark taken
+     * when an intent match armed this, so each plan in a turn is billed for its
+     * own window and a turn's cost is never reported twice.
+     */
+    usageMark?: unknown;
+    /**
+     * Takes another watermark. Set by the control server, which is the only side
+     * that holds the transcript path (segmented.md R-MONEY-3).
+     */
+    markUsage?: () => unknown;
+    /**
+     * The watermark at a *completing* retire, and when it happened.
+     *
+     * 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).
+     */
+    retiredMark?: unknown;
+    retiredAt?: number;
 }
+/**
+ * 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" | "similarity" | "known_bad_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key";
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -125,8 +244,17 @@ export declare class ReplayController {
     readonly enabled: boolean;
     readonly work: ProxyWorkQueue;
     readonly budgets: ReplayBudgets;
+    readonly intentMatch: IntentMatchOptions;
     private readonly opts;
     constructor(opts: ReplayOptions);
+    /**
+     * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
+     *
+     * Off by default: until an operator has read the observe-only logs and turned
+     * `BIR_SEGMENT_ARM=1` on, the runner 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;
     /**
@@ -144,9 +272,20 @@ export declare class ReplayController {
      * baseline sample to contribute, and losing that is how a savings ledger ends
      * up with a denominator nobody measured.
      */
-    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>): ReplayState;
+    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext): Promise<ReplayState>;
     /** The directive to inject via `additionalContext`, or undefined when declined. */
     directiveFor(state: ReplayState): string | undefined;
+    /**
+     * A hand-over note not yet delivered, claimed for delivery (fallbk.md D4).
+     * Returns it once and marks it delivered; undefined when there is none.
+     */
+    takeNote(state: ReplayState | undefined): string | undefined;
+    /**
+     * 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
+     * two channels a divergence bundle already uses.
+     */
+    deliverInstead(text: string, toolName: string): PreToolAction;
     /**
      * `PreToolUse`, while a plan is active.
      *
@@ -195,6 +334,8 @@ export declare class ReplayController {
         measured: boolean;
         durationMs: number;
         prompt?: string;
+        /** Every plan state of this turn, this one included (R-MONEY-5). */
+        siblings?: readonly ReplayState[];
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic
@@ -240,6 +381,17 @@ export declare class ReplayController {
      * directive the moment the match lands; the first `PreToolUse` — or
      * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
      */
+    /**
+     * Where to ask the service to read this turn (segmented.md R-PARAM-5).
+     *
+     * Undefined when there is nobody to ask — an unauthenticated session, or one
+     * whose token has gone. `derive` then falls back to the recorded samples, and
+     * a scenario with a target declines, exactly as a keyless runner always did.
+     *
+     * The token is read here rather than captured, because the recorder refreshes
+     * it as a session outlives it.
+     */
+    private deriveService;
     private startDerivation;
     /**
      * Divergence (§8). Execute the remaining steps for real, then deliver.
@@ -248,6 +400,16 @@ export declare class ReplayController {
      * nor re-injects again.
      */
     private diverge;
+    /**
+     * Hand the rest of the task to the model (fallbk.md D4/D5).
+     *
+     * Retires the plan and builds the note; delivery is the caller's, because the
+     * channel depends on the hook that noticed. The outcome is `fell_back` when at
+     * least one step did its work under the plan, and `failed` when none did — a
+     * scenario that did nothing has nothing to book, and is a baseline sample.
+     */
+    private handOver;
+    private noteFor;
     /**
      * The executor handed to a plan: dispatch a step to the proxy that owns its
      * upstream.
@@ -295,6 +457,17 @@ export interface RunMatchLike {
     similarity: number;
     scenario: Record<string, unknown> | null;
     executionTicket?: string;
+    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;
 }
+export declare function knownBadStepIndex(steps: readonly SerializedScenarioStep[], maxStepFailures: number | undefined): number | undefined;
 export {};
 //# sourceMappingURL=controller.d.ts.map