@basein/runner 0.3.17 → 0.3.19

package/dist/replay/controller.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ExecutionReport, MatchKey, MatchSegment, MatchVerdict } from "../record/recorder.js";
 import { type ReplayMode, type StepReach } from "./coverage.js";
-import { deriveParameters, type DeriveContext } from "./derive.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";
@@ -22,6 +22,13 @@ 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";
+/**
+ * `bir`'s own tool for saying a replay's results do not answer the request
+ * (bin/bir-scenario.ts; the service's review of calcscenarioautocorrect.md,
+ * item 19): the one call a finished bundle lets the agent make, where the
+ * session has it ({@link ReplayState.reportTool}).
+ */
+export declare const REPORT_TOOL_NAME = "mcp__bir__report_wrong_result";
 /** How long a `/proxy/poll` is held open before it answers empty. */
 export declare const POLL_HOLD_MS = 25000;
 /**
@@ -233,8 +240,11 @@ export interface ReplayOptions {
     /** On unless `BIR_REPLAY=0`. Everything here is inert when false. */
     enabled: boolean;
     /**
-     * `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).
+     * 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. */
@@ -391,6 +401,14 @@ export interface ReplayState {
     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.
+     */
+    request?: string;
     /**
      * 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
@@ -478,7 +496,10 @@ 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).
+     * 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).
      */
     retiredMark?: unknown;
     retiredAt?: number;
@@ -501,6 +522,25 @@ export interface ReplayState {
      * is waiting on the service, and obeys its breaker (util/service-health.ts).
      */
     deriveOnService?: boolean;
+    /** The day the plan's values were read for (issue 1212): the agent's own, or this machine's. */
+    deriveDay?: string;
+    /** The line that told the agent its day, as the reading was sent it. */
+    deriveLine?: string;
+    /** The agent's own day, read again when the plan starts. */
+    agentDayNow?: () => AgentDay | undefined;
+    /** Read the plan's values again for another day; set when the plan armed. */
+    rederive?: (day: AgentDay) => Promise<DeriveResult>;
+    /** What the second reading left unnamed, once it has answered. */
+    rederivedMissing?: string[];
+    /**
+     * Whether this plan's session has `bir`'s report tool ({@link
+     * REPORT_TOOL_NAME}) right now, asked when a bundle is laid out: set by the
+     * control server, from what the session's `bir` server said of itself. A
+     * bundle that forbids every tool call then makes one exception for it
+     * (bundle.ts). Absent — `bir replay`, another host, an older server — the
+     * words stay as they were.
+     */
+    reportTool?: () => boolean;
     /**
      * Set when the session's host is not Claude Code (see {@link HostContext}).
      * Such a plan is always `steer` with every step `live`, and nothing here
@@ -661,9 +701,11 @@ export declare class ReplayController {
     /**
      * 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).
+     * 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. */
@@ -706,6 +748,13 @@ export declare class ReplayController {
      * the field. Built from the same entries 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.
      *
@@ -995,6 +1044,10 @@ 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;
@@ -1070,6 +1123,12 @@ export declare class ReplayController {
      * 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
@@ -1105,6 +1164,12 @@ export declare class ReplayController {
      * cut off by its clock (`uncertain`), a step that ran and broke (`failed`).
      */
     private executeBuiltin;
+    /**
+     * The report tool a bundle may name, when this plan's session has it
+     * ({@link ReplayState.reportTool}); undefined leaves the bundle's words as
+     * they always were. Never for another host: its adapter reads no bundle.
+     */
+    private reportToolFor;
     /** Where recorded outputs come from, when they may stand in at all. */
     private recordedSource;
     /**
@@ -1177,6 +1242,12 @@ 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 {