@basein/runner 0.3.18 → 0.3.20

package/dist/record/recorder.d.ts

@@ -197,8 +197,13 @@ export declare function isRecorderHealthReporter(r: Recorder): r is Recorder & R
  * callers must stop recording it. What the caller does *instead* of recording is
  * v2's subject (docs/calculatedReplay.md); stopping is mandatory either way.
  */
-/** Which of a segment's two keys scored against the live step (R-OUT-3). */
-export type MatchKey = "intent" | "firstStep";
+/**
+ * Which of a segment's two keys scored against the live step (R-OUT-3).
+ * `decision`: no score at all — one of the calculated scenarios that can follow
+ * a plan's decision, handed out for the agent's next call (the service's
+ * offer1.md O3).
+ */
+export type MatchKey = "intent" | "firstStep" | "decision";
 /** The cheap model's answer about one live step and one segment (R-VERIFY-1). */
 export interface MatchVerdict {
     model: string;
@@ -335,13 +340,21 @@ export interface IntentMatchRequest {
     stepPosition?: number;
     /** Recordings this turn must not count hits against (R-HIT-7). */
     excludeRuns?: string[];
-    /** Per recording a plan of this turn came from, the largest position (R-OUT-6). */
+    /**
+     * Per plan of this turn: its recording, and how far it got in its own chain
+     * — the step it handed over at (a decision included), or its last step when
+     * it ran to its end (R-OUT-6). One entry per plan; the service maps each onto
+     * the recording and keeps the largest (its segmentsbreakdown.md D18).
+     */
     ranThrough?: Array<{
         runId: string;
         position: number;
         scenarioId?: string;
     }>;
-    /** Present only with `BIR_SEGMENT_ARM` (R-OUT-9, R-OUT-10). */
+    /**
+     * Present only while segment arming is on (R-OUT-9, R-OUT-10): the
+     * recorder's default from 0.3.19, absent with `BIR_SEGMENT_ARM=0`.
+     */
     acceptSegments?: boolean;
     /** Always true from this runner (R-CALL-28). */
     supportsCalls?: boolean;
@@ -398,6 +411,36 @@ export interface IntentMatcher {
     matchIntent(req: IntentMatchRequest, opts?: IntentMatchOptions): Promise<IntentMatchAnswer | null>;
 }
 export declare function isIntentMatcher(r: Recorder): r is Recorder & IntentMatcher;
+/** What a turn sends when a plan of it has stopped at its decision (the service's offer1.md O3). */
+export interface NextScenariosRequest {
+    /** The turn's identity, as a probe sends it (R-HIT-6). */
+    turnId?: string;
+    /** Always true from this runner (R-CALL-28). */
+    supportsCalls?: boolean;
+}
+/**
+ * One calculated scenario that can follow a plan's decision: a hand-out in the
+ * shape of a match, with its own ticket, `key: "decision"`, and the tool of its
+ * first step. The service leaves withheld ones out.
+ */
+export interface NextHandOut extends RunMatch {
+    /** The tool its first served step calls; null when the service could not say. */
+    firstTool?: string | null;
+}
+/** The service's answer: the scenarios, and where the plan's decision is. */
+export interface NextScenariosAnswer {
+    next: NextHandOut[];
+    decisionStep: number | null;
+}
+/**
+ * Optional capability: the calculated scenarios that can follow a decision
+ * (offer1.md O3) need a service. `null` is "none" — an older service (404), a
+ * cool-down, or any failure: the agent then does the work itself, as before.
+ */
+export interface NextScenarioSource {
+    nextScenarios(planId: string, req: NextScenariosRequest, opts?: IntentMatchOptions): Promise<NextScenariosAnswer | null>;
+}
+export declare function isNextScenarioSource(r: Recorder): r is Recorder & NextScenarioSource;
 /**
  * What a matched turn actually cost, reported once per match
  * (docs/calculatedReplay.md §11).

package/dist/record/recorder.js

@@ -20,6 +20,9 @@ export function isServiceProber(r) {
 export function isIntentMatcher(r) {
     return typeof r.matchIntent === "function";
 }
+export function isNextScenarioSource(r) {
+    return typeof r.nextScenarios === "function";
+}
 export function isToolListReporter(r) {
     return typeof r.reportTools === "function";
 }

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 { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } from "./recorder.js";
+import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, NextScenariosAnswer, NextScenariosRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } 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,
@@ -206,6 +206,14 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * waiting, so an abandoned probe does not hold a socket for minutes.
      */
     matchIntent(req: IntentMatchRequest, opts?: IntentMatchOptions): Promise<IntentMatchAnswer | null>;
+    /**
+     * The calculated scenarios that can follow a plan's decision (the service's
+     * offer1.md O3), each handed out with a ticket of its own. Asked once per
+     * decision hand-over, while the agent decides. An older service (404), a
+     * cool-down or any failure answers null: the agent then does the work
+     * itself, exactly as before.
+     */
+    nextScenarios(planId: string, req: NextScenariosRequest, opts?: IntentMatchOptions): Promise<NextScenariosAnswer | null>;
     /**
      * The similar-prompt match for a run's create call (null = fresh run). Like
      * {@link runCreated}, answers null at once while a failure is on record —

package/dist/record/remote-recorder.js

@@ -713,6 +713,36 @@ export class RemoteRecorder {
             return null;
         }
     }
+    /**
+     * The calculated scenarios that can follow a plan's decision (the service's
+     * offer1.md O3), each handed out with a ticket of its own. Asked once per
+     * decision hand-over, while the agent decides. An older service (404), a
+     * cool-down or any failure answers null: the agent then does the work
+     * itself, exactly as before.
+     */
+    async nextScenarios(planId, req, opts = {}) {
+        try {
+            if (!this.mayHotWait())
+                return null;
+            const answer = await this.request("POST", `/scenarios/${encodeURIComponent(planId)}/next`, JSON.stringify(req), { signal: opts.signal, timeoutMs: opts.timeoutMs ?? PROBE_TIMEOUT_MS });
+            const b = answer && typeof answer === "object" ? answer : {};
+            const next = Array.isArray(b.next)
+                ? b.next.filter((n) => !!n && typeof n === "object" && typeof n.scenarioId === "string")
+                : [];
+            return { next, decisionStep: typeof b.decisionStep === "number" ? b.decisionStep : null };
+        }
+        catch (err) {
+            if (!opts.signal?.aborted) {
+                logEvery("recorder.next_scenarios_failed", 30_000, "replay.next_failed", {
+                    error: errText(err),
+                    why: err instanceof ServiceError && err.status === 404
+                        ? "the service has no next scenarios — an older service, or not this account's plan"
+                        : "no next scenarios this time — the agent does the work after the decision",
+                });
+            }
+            return null;
+        }
+    }
     /**
      * The similar-prompt match for a run's create call (null = fresh run). Like
      * {@link runCreated}, answers null at once while a failure is on record —

package/dist/record/switchable-recorder.js

@@ -49,6 +49,8 @@ const NEUTRAL = {
     settledMatch: () => Promise.resolve(null),
     runCreated: () => Promise.resolve({ created: true }),
     matchIntent: () => Promise.resolve(null),
+    // Signed out: no scenario follows a decision (offer1.md O3); the agent goes on.
+    nextScenarios: () => Promise.resolve(null),
     reportExecution: () => undefined,
     backfillContext: () => undefined,
     probeIfFailing: () => undefined,

package/dist/replay/condition-words.d.ts

@@ -0,0 +1,28 @@
+/**
+ * condition-words — the request's own words for its decision (the service's
+ * segmentsbreakdown.md SB-18).
+ *
+ * When a plan stops at its decision, the hand-over note quotes the sentences
+ * of the live request that hold a word for a condition ("if … otherwise"), so
+ * the agent sees which choice is its own to make. Only the request's words:
+ * never the condition the service keeps, which is written from the recorded
+ * run and would hint at the half the recording took.
+ *
+ * The word lists are the service's (its src/scenarios/condition.ts), copied
+ * exactly. Keep the two the same: the service decides which requests may hold
+ * a condition with them, and this quotes the sentences they find.
+ */
+/** The longest quote a decision note carries, in characters. */
+export declare const MAX_DECISION_QUOTE = 600;
+/** Whether a text has a word for a condition in it: the service's `mayHoldCondition`. */
+export declare function mayHoldCondition(text: string): boolean;
+/**
+ * The sentences of `request` that hold a word for a condition, in order,
+ * each on one line of single spaces, joined by a space. Cut to at most `max`
+ * characters, ending in "…" when cut. Null when no sentence holds one.
+ *
+ * Lines are sentences of their own: the request is split at line breaks
+ * first, then at {@link SENTENCE_BREAK}.
+ */
+export declare function conditionSentences(request: string | null | undefined, max?: number): string | null;
+//# sourceMappingURL=condition-words.d.ts.map

package/dist/replay/condition-words.js

@@ -0,0 +1,59 @@
+/**
+ * condition-words — the request's own words for its decision (the service's
+ * segmentsbreakdown.md SB-18).
+ *
+ * When a plan stops at its decision, the hand-over note quotes the sentences
+ * of the live request that hold a word for a condition ("if … otherwise"), so
+ * the agent sees which choice is its own to make. Only the request's words:
+ * never the condition the service keeps, which is written from the recorded
+ * run and would hint at the half the recording took.
+ *
+ * The word lists are the service's (its src/scenarios/condition.ts), copied
+ * exactly. Keep the two the same: the service decides which requests may hold
+ * a condition with them, and this quotes the sentences they find.
+ */
+/** Words that say a part of a task depends on something: English, and the Hebrew the service reads. */
+const CONDITION_WORDS = /\b(if|otherwise|else|unless|only when|only if|in case|whether)\b/i;
+const HEBREW_CONDITION = /(^|[\s,.;:!?"'()\-])(אם|אחרת|אלא אם|במקרה ש|רק אם|רק כאשר)($|[\s,.;:!?"'()\-])/;
+/** The longest quote a decision note carries, in characters. */
+export const MAX_DECISION_QUOTE = 600;
+/** Whether a text has a word for a condition in it: the service's `mayHoldCondition`. */
+export function mayHoldCondition(text) {
+    return CONDITION_WORDS.test(text) || HEBREW_CONDITION.test(text);
+}
+/**
+ * Where one sentence ends and the next begins: after `.`, `!`, `?` or `…` and
+ * white space, in front of a capital letter, a letter of a script with no
+ * capitals (Hebrew), a quote mark or a bracket. Never in front of a digit or a
+ * small letter, so "Nov. 20" and "e.g. the" stay in one sentence.
+ */
+const SENTENCE_BREAK = /(?<=[.!?…])\s+(?=[\p{Lu}\p{Lo}"'“‘(\[])/u;
+/**
+ * The sentences of `request` that hold a word for a condition, in order,
+ * each on one line of single spaces, joined by a space. Cut to at most `max`
+ * characters, ending in "…" when cut. Null when no sentence holds one.
+ *
+ * Lines are sentences of their own: the request is split at line breaks
+ * first, then at {@link SENTENCE_BREAK}.
+ */
+export function conditionSentences(request, max = MAX_DECISION_QUOTE) {
+    if (typeof request !== "string" || request.trim() === "")
+        return null;
+    const sentences = request
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .flatMap((line) => line.split(SENTENCE_BREAK))
+        .map((s) => s.replace(/\s+/g, " ").trim())
+        .filter((s) => s !== "" && mayHoldCondition(s));
+    if (sentences.length === 0)
+        return null;
+    const quote = sentences.join(" ");
+    if (quote.length <= max)
+        return quote;
+    let cut = quote.slice(0, Math.max(0, max - 1));
+    // Never half of a character written as two code units (an emoji).
+    if (/[\uD800-\uDBFF]$/.test(cut))
+        cut = cut.slice(0, -1);
+    return `${cut.trimEnd()}…`;
+}
+//# sourceMappingURL=condition-words.js.map

package/dist/replay/controller.d.ts

@@ -240,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. */
@@ -398,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
@@ -485,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;
@@ -687,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. */
@@ -732,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.
      *
@@ -1021,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;
@@ -1096,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
@@ -1209,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 {