@basein/runner 0.3.21 → 0.3.23

package/dist/control/server.d.ts

@@ -272,19 +272,25 @@ export interface ControlServerOptions {
      */
     onStopRequested?: () => void;
     /**
-     * Whether an intent probe may arm a plan inside the `PreToolUse` that sent it
-     * (fallbk.md §Runner 4).
+     * Whether a match found mid-turn may arm a plan in the place of the call
+     * that found it (fallbk.md §Runner 4).
      *
      * Arming there means *waiting* there, on every unsteered tool call, for a
-     * service round trip. It waits (at most `BIR_INTENT_ARM_BUDGET_MS`, 500 ms,
-     * and never while the service is failing) when segment arming is on — the
-     * recorder's default from 0.3.19, `BIR_SEGMENT_ARM` unset or `1` — or when
-     * `BIR_INTENT_ARM=1` asks for whole-scenario intent arming. `BIR_INTENT_ARM=0`
-     * never waits. Otherwise, as in a server built with neither (a test, an
-     * embedder), the probe is sent without waiting, for hit counting only, and
-     * nothing arms mid-turn.
+     * service round trip — so it is off by default: no probe is sent and nothing
+     * arms mid-turn. `BIR_INTENT_ARM=1` turns it on, and then each call waits at
+     * most `BIR_INTENT_ARM_BUDGET_MS` (500 ms), and never while the service is
+     * failing. Unset or `BIR_INTENT_ARM=0` is off.
      */
     intentArm?: boolean;
+    /**
+     * Whether the model's first call after a plan handed over asks the service
+     * for the plan of the work recorded after an earlier hand-over at that step,
+     * and runs it when that call is its first step (the service's fallbk.md
+     * Part 3). On by default: it is one request per hand-over, never per call.
+     * `BIR_CONTINUATIONS=0` turns it off; so does `BIR_INTENT_MATCH=0`, which
+     * turns off every mid-turn request.
+     */
+    continuations?: boolean;
     /**
      * The verdict hot paths consult before they wait on the service. Defaults to
      * the process-wide one every service call reports to; tests pass their own.
@@ -441,8 +447,8 @@ export declare class ControlServer {
     private readonly deriveRecentResults;
     /**
      * Which rungs of R-INTENT-1 the runner may send (`BIR_INTENT_SOURCES`). It
-     * governs only what is *sent*: with every source off, the probe still goes out
-     * with an empty text and the server builds the tool line (R-HIT-4).
+     * governs only what is *sent*: with every source off, a step goes out with no
+     * text, and no intent probe is sent for it.
      */
     private readonly intentSources;
     constructor(opts: ControlServerOptions);
@@ -1144,154 +1150,98 @@ export declare class ControlServer {
      */
     private replayOverran;
     /**
-     * Recordings this turn must not count a step hit against (segmented.md
-     * R-HIT-7).
-     *
-     * A repeat of a recording's own prompt is *prompt* recurrence, counted as
-     * `iterations`, never step recurrence. Without this, three prompt repeats
-     * would reach `SEGMENT_MIN_HITS` on every step of the whole recording and the
-     * detector would build a whole-run-sized segment beside the whole-run
-     * scenario.
-     */
-    private excludeRunsFor;
-    /**
-     * Per plan of this turn, its recording and how far the plan got in its own
-     * chain (segmented.md R-OUT-6).
-     *
-     * The server uses it to refuse a segment that starts *before* where this turn
-     * already is: re-running steps the turn has just done is worse than not
-     * replaying at all. The position is the plan's own: the step it handed over
-     * at (its decision included), or its last step when it ran to its end. The
-     * server maps it onto the recording — a segment's first position, a
-     * decision's step before it — and takes the largest per recording (the
-     * service's segmentsbreakdown.md D18). One entry per plan, so that two plans
-     * of one recording, whose own positions are on different scales, never
-     * hide each other. A plan declined for anything but a known-bad first step
-     * reports nothing — it ran none of the recording, so it blocks none of it.
-     *
-     * Rebuilt on every probe rather than cached: a plan that hands over between
-     * two calls changes the answer.
-     */
-    private ranThroughFor;
-    /**
-     * Intent matching in the ReAct loop (fallbk.md §Runner 4, segmented.md 10.3).
+     * Intent matching in the ReAct loop (fallbk.md §Runner 4).
      *
-     * Called only while the model is driving. Every unsteered, non-housekeeping
-     * tool call is sent: the service counts it as a hit on whatever recorded step
-     * it matches, and may hand back a scenario or a segment to run in its place.
+     * Called only while the model is driving, and only when a match may arm a
+     * plan in the call's place ({@link intentArming}, off unless
+     * `BIR_INTENT_ARM=1`): the reasoning the call was made with is sent, and the
+     * service may hand back a whole scenario whose intent it matches. A call made
+     * with no reasoning sends nothing — there is no intent to match. Every
+     * failure is a miss.
      *
-     * A call made with **no reasoning at all** still probes (R-HIT-4): the server
-     * builds an intent from the tool name and arguments, and a step the agent took
-     * without narrating it is exactly as much a recurrence as one it explained.
-     * Every failure is a miss.
-     *
-     * THE PROBE IS NOT WAITED ON unless it may arm ({@link intentArming}). Hit
-     * counting needs no answer at all, and waiting for one put a service round
-     * trip — 70-450 ms healthy, the whole 4 s budget on a hung service — in front
-     * of every Read, Grep, Edit and Bash of every signed-in user. When it may arm,
-     * the wait is {@link intentArmBudgetMs} at most, and none while the service is
+     * The probe sits in front of the call, so it is waited on
+     * {@link intentArmBudgetMs} at most, and not at all while the service is
      * failing. Delivering a match on a *later* call instead is not an option: the
      * matched call has run by then, and the plan's first step would repeat it.
      */
     private tryIntentMatch;
     /**
-     * Whether the model's call is plausibly `state`'s first step: its tool, and
-     * arguments the pin guard would pin to that step's input. The input is
-     * computed only for a step of the plan's own frame (a called segment's first
-     * step would build that segment's parameters here); anything that cannot be
-     * computed is "no" — the directive then rides on the call's PostToolUse.
-     */
-    private isFirstStep;
-    /**
-     * The agent's call against `state`'s first step, value for value (the
-     * service's offer1.md O5): `hit` when every argument is the step's own,
-     * `missing` when the only differences are values the plan does not have
-     * (a target the reading left empty, which the agent's call may hold), and
-     * `other` otherwise.
-     */
-    private firstStepVerdict;
-    /**
-     * Whether `state`'s plan calls `toolName` in a step it would run: what makes
-     * a plan started after a call of that tool make it a second time (the
-     * service's offer1.md O8). A tool that only reads never counts — reading
-     * twice changes nothing — by the service's own rule ({@link readsOnly}): a
-     * `crm_search_customers` mid-task never keeps a plan that searches later from
-     * starting.
-     */
-    private planCallsTool;
-    /**
-     * A plan of this turn stopped at its decision: ask the service, once per
-     * plan, which calculated scenarios can follow it, and arm each in the
-     * background while the agent reads the note and decides (offer1.md O3, O4).
-     * Called wherever a hand-over is first seen; a second call for the same plan
-     * does nothing.
-     */
-    private noteDecision;
-    /**
-     * Ask for a decision's next scenarios (offer1.md O3): each is checkable as
-     * soon as the service answers, and armed in the background, each on its own
-     * (O4). Resolves when the service has answered, not when the arms have.
-     * Never rejects.
+     * A continuation (the service's fallbk.md Part 3), on the model's first call
+     * after a plan handed over.
+     *
+     * The model's work after an earlier hand-over of the same plan at the same
+     * step was recorded once, as a fragment, and the service may have calculated
+     * it into a plan. Until 0.3.23 nothing asked for that plan: the only way a
+     * plan started mid-task was a match of the model's words against plan
+     * intents ({@link tryIntentMatch}, off by default), and a one-line note
+     * after a hand-over does not read like a plan's intent paragraph. Here the
+     * hand-over itself is the question — the plan and the step — so the service
+     * names one recording and matches no words.
+     *
+     * It arms only when the call the model is making is that plan's first step —
+     * its tool, and arguments the pin guard would pin to the step's input — and
+     * is then answered in that call's place, as an intent plan whose first step
+     * the call is. The plan before it stopped because the next step needed a
+     * judgement. This call is the model's judgement; a plan that starts with
+     * another call is a way the model did not take, and must not run.
+     *
+     * Its values are read from the turn's own request — the rest of the task is
+     * the one the user asked for — with the model's words, the call it was about
+     * to make and this turn's tool results beside it, as for any plan started at
+     * a tool call.
+     *
+     * Asked once per hand-over, waited on {@link CONTINUATION_PROBE_MS} and
+     * {@link CONTINUATION_ARM_MS} at most, and not at all while the service is
+     * failing. Every way it does not arm leaves the turn as it was: the model's
+     * call runs, and its work is recorded as the fragment. A plan handed out and
+     * not armed is reported for its ticket, with the reason.
      */
-    private fetchNext;
+    private tryContinuation;
     /**
-     * Arm one next scenario in the background (offer1.md O4): its values read
-     * from the turn's request and its results so far — or, once more, with the
-     * agent's own call (O5) — and settled, so a call is compared with the first
-     * step as it would really run. Never rejects.
+     * A continuation handed out and not armed: kept, retired, for its ticket's
+     * report at the seal (`not_steered`, with the reason, unmeasured). `code`
+     * says why when no gate did.
      */
-    private armNext;
+    private keepDeclinedContinuation;
+    /** A continuation request's answer that came after the call it was for went ahead. */
+    private noteLateContinuation;
     /**
-     * The agent's call after a decision, against the scenarios that can follow
-     * it (offer1.md O5, O6). A hit — the call is a scenario's first step, value
-     * for value — is answered in the call's place with that scenario's directive:
-     * the agent calls `run_scenario`, and the scenario runs every step, this one
-     * included, once. Undefined otherwise: the call runs as the agent wrote it.
+     * Every scenario this turn was handed and armed or declined: never handed
+     * out again in it. A plan that handed over is among them, so its own
+     * continuation request can never return it.
      */
-    private tryNextScenarios;
-    /** A next scenario's hit: bookkeeping as for any plan armed mid-task, then its directive in the call's place. */
-    private nextHit;
+    private armedScenarioIds;
     /**
-     * A next scenario hit after the agent's own calls — looks — opened the
-     * fragment of its work after the decision: the fragment ends here, with what
-     * the agent did itself, and nothing more of this turn is recorded into it.
-     * The scenario's own calls, pinned in steer mode or run in direct mode, are
-     * not the agent's work, and would make the fragment a copy of that scenario
-     * (offer1.md O7). A fragment still due is dropped instead
-     * ({@link dropDecisionFragment}).
+     * Whether the model's call is a continuation's first step: its tool, and
+     * the step's own input in every argument the two share (pin-guard.ts
+     * `sameFirstCall`). Anything that cannot be computed is "no".
      */
-    private closeDecisionFragment;
+    private isContinuationFirstCall;
+    /** Whether continuations are asked for: on unless `BIR_CONTINUATIONS=0`. */
+    private continuationsOn;
     /**
-     * End this turn's next scenarios (offer1.md O6): every one but the hit is
-     * never announced, so never runs and is never reported.
+     * Whether the model's call is plausibly `state`'s first step: its tool, and
+     * arguments the pin guard would pin to that step's input. Anything that
+     * cannot be computed is "no" — the directive then rides on the call's
+     * PostToolUse.
      */
-    private endNext;
+    private isFirstStep;
     /**
-     * Whether an intent probe may arm a plan in its own `PreToolUse` — and so
-     * whether that hook waits for it. See {@link ControlServerOptions.intentArm}.
+     * Whether a match found mid-turn may arm a plan in its own `PreToolUse` — and
+     * so whether a probe is sent and waited for at all. Off unless
+     * `BIR_INTENT_ARM=1`. See {@link ControlServerOptions.intentArm}.
      */
     private intentArming;
     /** How long an arming probe is waited on: `BIR_INTENT_ARM_BUDGET_MS`, never past the probe's own budget. */
     private intentArmBudgetMs;
-    /** The bookkeeping half of a probe's answer: what `/health` and the log show. */
+    /** A probe's answer, for the log. Never throws: a malformed answer is a log line. */
     private noteProbe;
-    private noteProbeUnsafe;
     /**
      * Schedule a fragment once a matched turn's plan has handed over (fallbk.md
      * D7). Only a turn that is not already recording needs one: an unmatched turn
      * whose intent-armed plan handed over is recording the model's work anyway.
      */
     private noteHandover;
-    /**
-     * Drop a fragment scheduled at a decision (the service's
-     * segmentsbreakdown.md SB-16) when a plan the intent check armed takes the
-     * agent's next call: what follows is that plan's half, not the other one,
-     * and recorded as the other half it would become a wrong segment C. Cleared
-     * rather than ended, so a later hand-over of that plan schedules its own
-     * fragment, as any plan's does in a turn with none. Any other fragment is
-     * left as it is.
-     */
-    private dropDecisionFragment;
     /**
      * Open the fragment run and record from this call on (fallbk.md D7).
      *