@basein/runner 0.3.21 → 0.3.23

package/dist/record/recorder.d.ts

@@ -7,9 +7,15 @@
  */
 import type { ExecutionStage, ExecutionStepResult, FallbackKind } from "../replay/types.js";
 export interface StartRunOptions {
+    /**
+     * Marks a *fragment* (fallbk.md D7). `counted`: the runner asked for this
+     * hand-over's continuation first, and the service counted the hand-over as
+     * a hit then, so this request must not count it again (Part 3).
+     */
     fallbackOf?: {
         scenarioId: string;
         stepIndex: number;
+        counted?: boolean;
     };
     /**
      * Marks a *repeat* (the service's newestRun.md): a matched turn whose plan
@@ -130,20 +136,18 @@ export interface Recorder {
         toolInput: string;
         context?: string;
         /**
-         * The thinking text this call was chosen in, when there was no written
-         * text (segmented.md R-INTENT-1). It travels to the service only to be
-         * embedded and is never stored as text (R-INTENT-2), which is why it is
-         * carried apart from `context` rather than folded into it.
+         * The thinking text this call was chosen in. The service keeps it for
+         * the recording page, for people to read and never for a model, which
+         * is why it is carried apart from `context` rather than folded into it.
          */
         intent?: {
             text: string;
             source: "thinking";
         };
         /**
-         * Set when a plan executed this step, to the plan's scenario id
-         * (R-INTENT-7), or made it before the agent redid the task (`byPlan`,
-         * AC2). The service stores such a step without a vector, so the
-         * system's own replays never count as recurrences of the work.
+         * Set when a plan executed this step, to the plan's scenario id, or made
+         * it before the agent redid the task (`byPlan`, AC2): how the service
+         * tells the system's own steps from the agent's work.
          */
         metadata?: StepMetadata;
     }): string;
@@ -197,28 +201,6 @@ 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).
- * `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;
-    verdict: "same" | "different" | "skipped";
-    reason?: string;
-}
-/** Where a handed-out segment sits in its recording (R-OUT-8). */
-export interface MatchSegment {
-    runId: string;
-    stepFrom: number;
-    stepTo: number;
-    /** `tool_selected` rows of the recording before `stepFrom` (R-OUT-6). */
-    firstPosition: number;
-    hitCount?: number;
-}
 export interface RunMatch {
     runId: string;
     scenarioId: string | null;
@@ -233,14 +215,6 @@ export interface RunMatch {
     fallback?: {
         maxStepFailures: number;
     };
-    /**
-     * What kind of row matched (segmented.md R-OUT-7). Absent from an older
-     * service, and then read as `scenario`.
-     */
-    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;
     /**
@@ -286,7 +260,7 @@ export declare function isMatchAware(r: Recorder): r is Recorder & MatchAware;
 export interface RunCreation {
     created: boolean;
     /**
-     * Set when this was a hit on an existing fragment (R-FALL-7, R-HIT-7) —
+     * Set when this was a hit on an existing fragment (R-FALL-7) —
      * with `created` too when the service recorded it all the same, as that
      * fragment's newest run (its newestRun.md N2).
      */
@@ -320,84 +294,47 @@ export declare function isServiceProber(r: Recorder): r is Recorder & ServicePro
 /** What a ReAct iteration sends to find a scenario by its intent (fallbk.md §Runner 4). */
 export interface IntentMatchRequest {
     /**
-     * The step's intent (segmented.md R-INTENT-1). May be empty: a call made with
-     * no reasoning still probes, and the service builds a line from the tool name
-     * and arguments instead (R-HIT-4).
+     * What the agent wrote, or was thinking, as it chose the call. Never empty
+     * on an intent probe. A continuation request ({@link handover}) is answered
+     * by the hand-over alone: it sends the text, possibly empty, and the service
+     * does not read it.
      */
     text: string;
     currentToolName?: string;
     /** Scenario ids already armed this turn. */
     exclude?: string[];
-    /** Which rung the text came from (R-INTENT-3). */
-    source?: IntentSourceName;
-    /** The same value as `currentToolName`; what the new server reads (R-HIT-6). */
-    toolName?: string;
-    /** Redacted and capped arguments of the call about to be made (R-HIT-4). */
-    toolInput?: string;
-    /** The turn's identity, fixed for its whole life (R-HIT-6). */
-    turnId?: string;
-    /** `run.ordering.next` — where this call sits in the turn. */
-    stepPosition?: number;
-    /** Recordings this turn must not count hits against (R-HIT-7). */
-    excludeRuns?: string[];
-    /**
-     * 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 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;
     /**
      * The host the turn runs in, as its runs' `framework` says it (see
      * {@link StartRunOptions.framework}). Left out for Claude Code, which is
      * what a missing value means to the service.
      */
     framework?: string;
+    /**
+     * A continuation request (the service's fallbk.md Part 3): the plan that
+     * just handed the task to the model, and the step it stopped in front of.
+     * The service answers with the plan of the work recorded after an earlier
+     * hand-over at that step, if there is one, and matches no words.
+     */
+    handover?: {
+        scenarioId: string;
+        stepIndex: number;
+    };
 }
-/** Which text a step's intent came from. */
-export type IntentSourceName = "text" | "thinking" | "tool";
-/** One recorded step a live step matched (R-HIT-6). */
-export interface StepHit {
-    runId: string;
-    stepIndex: number;
-    similarity: number;
-    hitCount?: number;
-}
-/** What a segment *would* have armed, when no ticket was issued (R-OUT-9). */
-export interface SegmentWouldArm {
-    scenarioId: string;
-    runId: string;
-    key?: MatchKey;
-    similarity: number;
-    band?: string;
-    verified?: MatchVerdict;
-    tool?: string;
-    firstTool?: string;
-    stepFrom?: number;
-    stepTo?: number;
-    hitCount?: number;
-}
-/**
- * The whole answer to a probe, not just its match. The counting fields are what
- * make the observe-only period readable (R-OUT-10), so they must survive the
- * trip rather than being discarded with the rest of the body.
- */
+/** The answer to a probe. */
 export interface IntentMatchAnswer {
     matched: RunMatch | null;
-    stepHit?: StepHit | null;
-    bestStepSimilarity?: number;
-    segmentWouldArm?: SegmentWouldArm;
+    /** The best score the service saw, matched or not — for the log, to tune by. */
+    bestSimilarity?: number | null;
+    /**
+     * The answer to a continuation request: the recording of the earlier
+     * hand-over at that step, and whether this hand-over was counted as a hit
+     * on it. Null when there is none; absent from a service that does not know
+     * continuations, which matched the text by words instead.
+     */
+    continuation?: {
+        runId: string;
+        counted?: boolean;
+    } | null;
 }
 /** How long a probe's caller will wait; the request is abandoned past it. */
 export interface IntentMatchOptions {
@@ -411,36 +348,6 @@ 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).
@@ -499,12 +406,14 @@ export interface ExecutionReport {
      */
     baselineEligible?: boolean;
     /**
-     * Segments of this plan's own recording that ran later in the same turn
-     * (segmented.md R-MONEY-4). The service freezes this row's baseline at what
-     * is left after their share, so one recording's steps are never counted in
-     * two baselines of one turn. The segments' own rows are untouched.
+     * Set on a continuation's report (the service's fallbk.md Part 3): the plan
+     * it continued in this turn, which handed over in front of it. That plan's
+     * report bills the whole turn against its own baseline, which covers this
+     * part of the task too, so the service books this one no saving.
      */
-    sharedWith?: string[];
+    continues?: {
+        scenarioId: string;
+    };
     /**
      * Which gate of the ladder declined, on a `not_steered` report.
      *

package/dist/record/recorder.js

@@ -20,9 +20,6 @@ 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, NextScenariosAnswer, NextScenariosRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } from "./recorder.js";
+import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, 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,14 +206,6 @@ 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

@@ -604,9 +604,6 @@ export class RemoteRecorder {
                         // A repeat (the service's newestRun.md). Sent only after a match
                         // that offered it, so a service that would not know it never sees it.
                         ...(options?.repeatOf ? { repeatOf: options.repeatOf } : {}),
-                        // A chain with calls is inlined for this runner rather than stopped in
-                        // front of its first call (segmented.md R-CALL-28).
-                        supportsCalls: true,
                     }), 
                     // The id is client-generated, so the service can tell a repeat. A
                     // hook waiting on this answer is let go before the retry: a match
@@ -616,9 +613,7 @@ export class RemoteRecorder {
                     const b = body && typeof body === "object"
                         ? body
                         : {};
-                    // `id: null` is the service saying it kept a run of its own. Which run
-                    // that was matters: a turn must not count step hits against the
-                    // recording it is itself a repeat of (R-HIT-7).
+                    // `id: null` is the service saying it kept a run of its own.
                     if (entry.released && b.id === null) {
                         logLine("recorder.matched_after_retry", {
                             run: id,
@@ -679,23 +674,18 @@ export class RemoteRecorder {
             const body = {
                 ...req,
                 text: capText(req.text ?? "", TEXT_CAPS.intent, redactText),
-                ...(typeof req.toolInput === "string"
-                    ? { toolInput: capJsonText(req.toolInput, DEFAULT_MAX_PAYLOAD_BYTES, redactJsonText) }
-                    : {}),
             };
             const answer = await this.request("POST", "/scenarios/match-intent", JSON.stringify(body), {
                 signal: opts.signal,
                 timeoutMs: opts.timeoutMs ?? PROBE_TIMEOUT_MS,
             });
-            // The whole answer, not just `matched`: the counting fields are what make
-            // the observe-only period readable (segmented.md R-OUT-10), and an older
-            // server simply sends none of them (R-COMPAT-2).
             const b = answer && typeof answer === "object" ? answer : {};
             return {
                 matched: b.matched ?? null,
-                stepHit: b.stepHit ?? null,
-                bestStepSimilarity: b.bestStepSimilarity,
-                segmentWouldArm: b.segmentWouldArm,
+                ...(typeof b.bestSimilarity === "number" ? { bestSimilarity: b.bestSimilarity } : {}),
+                // Null and absent mean different things: no continuation, or a
+                // service that does not know continuations (fallbk.md Part 3).
+                ...(b.continuation !== undefined ? { continuation: b.continuation } : {}),
             };
         }
         catch (err) {
@@ -713,36 +703,6 @@ 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 —
@@ -805,8 +765,7 @@ export class RemoteRecorder {
         const intentSource = data.intent?.source;
         this.enqueueRun(runId, "step", sizeOf(toolInput, context, intentText), () => 
         // `intent` and `metadata` are omitted, not nulled, when absent, so an
-        // older service sees the body it has always seen (segmented.md
-        // R-COMPAT-1).
+        // older service sees the body it has always seen.
         this.post(`/recordings/runs/${runId}/steps`, {
             id,
             stepIndex,
@@ -1084,7 +1043,9 @@ export class RemoteRecorder {
                     fallbackStepIndex: report.fallbackStepIndex,
                     fallbackKind: report.fallbackKind,
                     baselineEligible: report.baselineEligible,
-                    sharedWith: report.sharedWith,
+                    // A continuation's report: the plan it continued, whose report
+                    // books the turn (the service's fallbk.md Part 3). Additive.
+                    continues: report.continues,
                     // Why nothing ran, when nothing ran. Additive: an older service drops
                     // the field and books the cost exactly as it always did.
                     declined: report.declined,
@@ -1114,8 +1075,9 @@ export class RemoteRecorder {
                     steps: report.steps?.length,
                     stepsFailed: failed || undefined,
                     baselineEligible: report.baselineEligible === false ? false : undefined,
-                    sharedWith: report.sharedWith?.length,
                     declined: report.declined,
+                    // A continuation's report: the plan whose report books the turn.
+                    continues: report.continues?.scenarioId,
                     // `bir investigate` prints it beside the outcome: "redone by run_…".
                     redoneBy: report.redoneBy?.runId,
                     ownCalls: report.redoneBy?.ownCalls,

package/dist/record/switchable-recorder.js

@@ -49,8 +49,6 @@ 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/bundle.d.ts

@@ -51,8 +51,8 @@ export interface AssembleOptions {
     /** The plan stopped part-way and the model is to carry on (fallbk.md). */
     handover?: boolean;
     /**
-     * The plan was armed mid-task by intent (segmented.md R-OUT-13). Its results
-     * feed the agent's own task, which continues. `handover` wins over this.
+     * The plan was armed mid-task by intent. Its results feed the agent's own
+     * task, which continues. `handover` wins over this.
      */
     subTask?: boolean;
     /**

package/dist/replay/bundle.js

@@ -100,8 +100,8 @@ const HANDOVER_HEADER = "[BaseInstRunner calculated replay] The tool calls below
     "continue the task yourself from where they end.";
 const HANDOVER_FOOTER = "\n\nThe calls above are done. Continue the rest of the task yourself, calling tools as needed.";
 /**
- * The plan ran inside the agent's own task (segmented.md R-OUT-13): it finished,
- * but the task did not, so the model must not be told to answer without tools.
+ * The plan ran inside the agent's own task (armed mid-task by intent): it
+ * finished, but the task did not, so the model must not be told to answer without tools.
  * This is {@link HANDOVER_HEADER} without "The scenario stopped before the task
  * was finished" — nothing stopped, the sub-task is simply done.
  */
@@ -121,7 +121,7 @@ export function assembleBundle(entries, maxChars, opts = {}) {
     const anyRecorded = entries.some((e) => e.recorded);
     // A hand-over outranks a sub-task: it says "continue" too, and it also has to
     // say that the plan stopped short. A sub-task outranks the live and mixed
-    // headers, whose wording forbids further tool calls (segmented.md 10.8 §6).
+    // headers, whose wording forbids further tool calls.
     const header = opts.handover
         ? HANDOVER_HEADER
         : opts.subTask