@basein/runner 0.3.13 → 0.3.15

package/dist/control/server.d.ts

@@ -1073,6 +1073,46 @@ export declare class ControlServer {
     private openFragment;
     /** What the fragment's create call said: `created: false` is a hit, not a recording. */
     private applyFragmentCreation;
+    /**
+     * Whether this matched turn's task is now the model's own, so its work is
+     * the repeat the service offered to record: offered, nothing recording, no
+     * fragment, and the prompt match's plan done with — retired, not running,
+     * not diverging — and either:
+     *
+     *  - it ran no step: the model does the whole task (newestRun.md N1); or
+     *  - it ran to its end, and the model, told to answer from its results,
+     *    called tools of its own instead (N7). Before 0.3.15 that work was
+     *    lost: a model that did not take the plan's result as the answer and
+     *    did the task again left nothing to fix the plan from.
+     *
+     * A plan that handed over is the fragment's to record (fallbk.md D7). One
+     * that ran part of the task and stopped without a hand-over records
+     * nothing, as before: the call where it stopped ran while it was still
+     * live, so a run of what came after would lack the step that matters.
+     */
+    private repeatDue;
+    /**
+     * Whether the prompt match's plan ran to its end before the model went on
+     * by itself (newestRun.md N7). False when it ran no step, which is N1.
+     */
+    private redoneAfterPlan;
+    /**
+     * Open the repeat run and record from this call on (newestRun.md N1, N7).
+     *
+     * The same swap as {@link openFragment}: nothing allocated before it belongs
+     * to it. Unlike a fragment it carries the turn's prompt. When no plan did
+     * any of the task, its cost and duration are the whole turn's; after a plan
+     * that ran to its end, they start here, as a fragment's do. Nothing waits
+     * for the service's answer: the steps queue behind the create, and a create
+     * answered `id: null` — the service records no repeat of it — drops them.
+     */
+    private openRepeat;
+    /**
+     * Why the matched turn's plan did not run, as the service shows it: what
+     * the service withheld it for, else the code of the gate that declined it
+     * here, a plan that was late included.
+     */
+    private repeatReason;
     /** Resolve with `p`, or null once `ms` passes or it rejects. */
     private withinBudget;
     /**

package/dist/control/server.js

@@ -697,6 +697,9 @@ export class ControlServer {
                 }
                 : null,
             fragment: s.run?.fragment ? { state: s.run.fragment.state } : null,
+            // The service's offer to record the turn as a recording's newest run,
+            // and what became of it (newestRun.md).
+            repeat: s.run?.repeat ? { state: s.run.repeat.state, of: s.run.repeat.runId } : null,
         }));
         const sending = this.recorderBacklog();
         return {
@@ -1673,6 +1676,12 @@ export class ControlServer {
             if (!match || run.runId !== runId)
                 return;
             run.recording = false;
+            // The service's offer to record the turn after all, should the model end
+            // up doing the task itself (newestRun.md N5). Taken up at the model's
+            // first call of its own, once no plan of this match runs (`repeatDue`).
+            if (match.repeat?.runId && !run.repeat) {
+                run.repeat = { runId: match.repeat.runId, withheld: match.withheld ?? undefined, state: "offered" };
+            }
             logLine("run.matched", {
                 run: runId,
                 matchedRun: match.runId,
@@ -2283,12 +2292,15 @@ export class ControlServer {
         this.reportExecution(session, run, durationMs, cost, cutShort);
         // A fragment is recorded from the hand-over on (fallbk.md D7), so its cost
         // and duration are the model's own work, not the steps the scenario did.
-        // Another host hands over one number for the whole run, and it is the
-        // fragment's: the plan's own steps made no model call, so all of it was
-        // spent after the hand-over.
+        // So is a repeat opened after the plan ran to its end (newestRun.md N7). Another host
+        // hands over one number for the whole run, and it is the fragment's: the
+        // plan's own steps made no model call, so all of it was spent after the
+        // hand-over.
         const fragment = run.fragment?.state === "open" ? run.fragment : undefined;
-        const recordedCost = fragment && !other ? this.costSince(session, fragment.usageMark) : cost;
-        const recordedMs = fragment?.startedAtMs ? Date.now() - fragment.startedAtMs : durationMs;
+        const repeatAfterPlan = !fragment && run.repeat?.state === "open" && run.repeat.startedAtMs !== undefined ? run.repeat : undefined;
+        const ownWork = fragment ?? repeatAfterPlan;
+        const recordedCost = ownWork && !other ? this.costSince(session, ownWork.usageMark) : cost;
+        const recordedMs = ownWork?.startedAtMs ? Date.now() - ownWork.startedAtMs : durationMs;
         if (run.recording) {
             const transcriptPath = session.transcriptPath;
             // The answer is the host's when it handed one over, and the
@@ -2934,6 +2946,12 @@ export class ControlServer {
                 this.noteHandover(run);
                 return this.preToolAnswer(this.replay.deliverInstead(note, toolName));
             }
+            // The model is doing the matched task itself, and the service asked for
+            // that run to be recorded as the recording's newest (newestRun.md N1).
+            // Opened before the probe below, so the turn is recorded from this call
+            // on like any recording turn — a plan an intent match arms in it too.
+            if (this.repeatDue(run))
+                this.openRepeat(session, run);
             // 2. The model is driving: look for a scenario by this iteration's intent.
             //    Never in plan mode, where nothing may run on the user's behalf.
             //    If the deadline answers first, it answers `{}`: the call runs as
@@ -3266,6 +3284,9 @@ export class ControlServer {
             });
         }
         this.noteHandover(run);
+        // The model doing the matched task itself, as in Claude Code (newestRun.md N1).
+        if (this.repeatDue(run))
+            this.openRepeat(session, run);
         const words = this.hostWords(payload);
         // Counted, never waited on, and never arming: see `tryIntentMatch`.
         await this.tryIntentMatch(session, run, toolName, words.intent, modelArgs);
@@ -3546,6 +3567,10 @@ export class ControlServer {
             out.add(prompt);
         if (run.fragment?.hitRunId)
             out.add(run.fragment.hitRunId);
+        // The recording the match offered a repeat of: the same recording, and
+        // known even when the match landed too late to be armed (newestRun.md).
+        if (run.repeat)
+            out.add(run.repeat.runId);
         return [...out];
     }
     /**
@@ -3985,8 +4010,16 @@ export class ControlServer {
     /** What the fragment's create call said: `created: false` is a hit, not a recording. */
     applyFragmentCreation(run, id, created) {
         const f = run.fragment;
-        if (created.created || !f || run.runId !== id)
+        if (!f || run.runId !== id)
+            return;
+        if (created.created) {
+            // Recorded as the newest run of the fragment it is a hit on (the
+            // service's newestRun.md N2): still that fragment's repeat, so no step
+            // hit may be counted against it (R-HIT-7).
+            if (created.fragmentOf)
+                f.hitRunId = created.fragmentOf.runId;
             return;
+        }
         run.recording = false;
         f.state = "hit";
         // Which run it hit matters from here on: this turn must not count step
@@ -4000,6 +4033,112 @@ export class ControlServer {
             why: "a hand-over at this step was recorded before — counted as a hit, not recorded",
         });
     }
+    /**
+     * Whether this matched turn's task is now the model's own, so its work is
+     * the repeat the service offered to record: offered, nothing recording, no
+     * fragment, and the prompt match's plan done with — retired, not running,
+     * not diverging — and either:
+     *
+     *  - it ran no step: the model does the whole task (newestRun.md N1); or
+     *  - it ran to its end, and the model, told to answer from its results,
+     *    called tools of its own instead (N7). Before 0.3.15 that work was
+     *    lost: a model that did not take the plan's result as the answer and
+     *    did the task again left nothing to fix the plan from.
+     *
+     * A plan that handed over is the fragment's to record (fallbk.md D7). One
+     * that ran part of the task and stopped without a hand-over records
+     * nothing, as before: the call where it stopped ran while it was still
+     * live, so a run of what came after would lack the step that matters.
+     */
+    repeatDue(run) {
+        const r = run.repeat;
+        if (!r || r.state !== "offered" || run.recording || run.finished || run.fragment)
+            return false;
+        const prompt = run.replays.find((s) => s.armedBy === "prompt");
+        if (!prompt?.plan)
+            return true;
+        if (!prompt.retired || prompt.diverging || this.runningPlans.has(prompt) || prompt.handover)
+            return false;
+        return prompt.stepsPinned === 0 || prompt.ranToEnd === true;
+    }
+    /**
+     * Whether the prompt match's plan ran to its end before the model went on
+     * by itself (newestRun.md N7). False when it ran no step, which is N1.
+     */
+    redoneAfterPlan(run) {
+        const prompt = run.replays.find((s) => s.armedBy === "prompt");
+        return prompt?.plan !== undefined && prompt.ranToEnd === true;
+    }
+    /**
+     * Open the repeat run and record from this call on (newestRun.md N1, N7).
+     *
+     * The same swap as {@link openFragment}: nothing allocated before it belongs
+     * to it. Unlike a fragment it carries the turn's prompt. When no plan did
+     * any of the task, its cost and duration are the whole turn's; after a plan
+     * that ran to its end, they start here, as a fragment's do. Nothing waits
+     * for the service's answer: the steps queue behind the create, and a create
+     * answered `id: null` — the service records no repeat of it — drops them.
+     */
+    openRepeat(session, run) {
+        const r = run.repeat;
+        if (!r || r.state !== "offered")
+            return;
+        const redone = this.redoneAfterPlan(run);
+        const reason = redone ? "redone" : this.repeatReason(run);
+        const repeatOf = reason ? { runId: r.runId, reason } : { runId: r.runId };
+        // The repeat is a run of the same host as the turn it records.
+        const framework = frameworkOf(session);
+        const id = this.recorder.startRun(run.input, { ...this.runMetadata(session), repeatOf }, framework ? { repeatOf, framework } : { repeatOf });
+        for (const c of run.correlations.values()) {
+            c.settled = true;
+            if (c.fallback)
+                clearTimeout(c.fallback);
+        }
+        run.builtIns.clear();
+        run.runId = id;
+        run.ordering = new StepIndexAllocator();
+        run.recording = true;
+        r.state = "open";
+        if (redone) {
+            // The plan's steps are not the model's work: this run is billed and
+            // timed from its own first call on, as a fragment is.
+            r.usageMark = markTranscriptUsage(session.transcriptPath);
+            r.startedAtMs = Date.now();
+        }
+        logLine("run.repeat", {
+            run: id,
+            of: r.runId,
+            reason,
+            why: redone
+                ? "the plan ran to its end, and the agent went on with calls of its own instead of answering from its results — recorded as that recording's newest run"
+                : "the agent is doing a recorded task itself — recorded as that recording's newest run",
+        });
+        if (!isRunCreationAware(this.recorder))
+            return;
+        void this.recorder
+            .runCreated(id)
+            .catch(() => ({ created: true }))
+            .then((created) => {
+            if (created.created || run.runId !== id)
+                return;
+            run.recording = false;
+            r.state = "refused";
+            logLine("run.repeat_refused", {
+                run: id,
+                of: r.runId,
+                why: "the service records no repeat of this recording — nothing recorded",
+            });
+        });
+    }
+    /**
+     * Why the matched turn's plan did not run, as the service shows it: what
+     * the service withheld it for, else the code of the gate that declined it
+     * here, a plan that was late included.
+     */
+    repeatReason(run) {
+        const prompt = run.replays.find((s) => s.armedBy === "prompt") ?? run.lateMatch;
+        return run.repeat?.withheld ?? prompt?.declined ?? undefined;
+    }
     /** Resolve with `p`, or null once `ms` passes or it rejects. */
     async withinBudget(p, ms) {
         let timer;

package/dist/record/recorder.d.ts

@@ -11,6 +11,19 @@ export interface StartRunOptions {
         scenarioId: string;
         stepIndex: number;
     };
+    /**
+     * Marks a *repeat* (the service's newestRun.md): a matched turn whose plan
+     * did not run, so the model is doing the recording's task itself — or whose
+     * plan ran to its end, after which the model went on with calls of its own
+     * instead of answering from its results (N7). Sent only when the match
+     * offered it ({@link RunMatch.repeat}). `reason` is why the plan did not
+     * run, or `redone` after a plan that ran to its end. The service never
+     * prompt-matches a repeat.
+     */
+    repeatOf?: {
+        runId: string;
+        reason?: string;
+    };
     /**
      * The run's `framework`, when the session named a host that is not Claude
      * Code: its `app`, or `app:scope` (`langchain`, `langchain:billing`). The
@@ -176,6 +189,15 @@ export interface RunMatch {
      * ordinary hand-out, and from an older service.
      */
     withheld?: string | null;
+    /**
+     * The service's offer (its newestRun.md N5): should the model end up doing
+     * this task itself — the plan declined, withheld, late or off — record the
+     * turn as a repeat of `runId`, the recording's newest run. Absent or null
+     * from a service that does not record repeats: then nothing is recorded.
+     */
+    repeat?: {
+        runId: string;
+    } | null;
 }
 /** Optional capability: `null` means "fresh run, keep recording". */
 export interface MatchAware {
@@ -202,10 +224,18 @@ export declare function isMatchAware(r: Recorder): r is Recorder & MatchAware;
 /** What the create call said about a run: fresh, or a hit on a fragment. */
 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, R-HIT-7) —
+     * with `created` too when the service recorded it all the same, as that
+     * fragment's newest run (its newestRun.md N2).
+     */
     fragmentOf?: {
         runId: string;
     };
+    /** Set when the service recorded the run as a repeat: the run it repeats. */
+    repeatOf?: {
+        runId: string;
+    };
 }
 export interface RunCreationAware {
     runCreated(runId: string): Promise<RunCreation>;

package/dist/record/remote-recorder.js

@@ -475,6 +475,9 @@ export class RemoteRecorder {
                         // A fragment (fallbk.md D7). Omitted, not null, so an older service
                         // that does not know the field sees the body it always saw.
                         ...(options?.fallbackOf ? { fallbackOf: options.fallbackOf } : {}),
+                        // 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,
@@ -496,7 +499,11 @@ export class RemoteRecorder {
                             why: "the create's first attempt failed, so the turn went ahead as a fresh one; the service kept its own run, and this one's steps are not sent",
                         });
                     }
-                    entry.settle(b.matched ?? null, { created: b.id !== null, fragmentOf: b.fragmentOf });
+                    entry.settle(b.matched ?? null, {
+                        created: b.id !== null,
+                        fragmentOf: b.fragmentOf,
+                        ...(b.repeatOf ? { repeatOf: b.repeatOf } : {}),
+                    });
                 }
                 catch (err) {
                     entry.settle(null, { created: true }); // fail-safe: on a create error, record normally

package/dist/replay/controller.d.ts

@@ -435,6 +435,24 @@ export interface ReplayState {
     sharedWith: string[];
     /** Set when the plan handed the task to the model part-way (fallbk.md). */
     handover?: Handover;
+    /**
+     * Every planned step ran and the model was handed the results to answer
+     * from: a steered plan whose last step threaded, a direct run that ran to
+     * its end, or a divergence whose bundle carried the rest of the chain. A
+     * call the model makes of its own after this is the task done again — it
+     * did not take the plan's result as the answer (the service's newestRun.md
+     * N7). Never set on a plan that handed over: the hand-over says the rest
+     * is the model's.
+     */
+    ranToEnd?: boolean;
+    /**
+     * A divergence is running the plan's remaining steps for real (§8). The
+     * plan is already retired by then, so this is what tells a call made beside
+     * that work from one made after it: a repeat never opens while steps are
+     * still landing, and whether the plan ran to its end or handed over is not
+     * known yet (the service's newestRun.md N7).
+     */
+    diverging?: boolean;
     /**
      * 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

package/dist/replay/controller.js

@@ -1375,6 +1375,7 @@ export class ReplayController {
         }
         if (done) {
             this.upgrade(state, "steered_full");
+            state.ranToEnd = true;
             // A completing retire: the last step threaded and the plan's work is over
             // (segmented.md R-MONEY-3). Everything the agent spends after this is the
             // agent's own, not this plan's.
@@ -1687,6 +1688,7 @@ export class ReplayController {
         // `runToCompletion` returned without a stop: the plan ran to its end, so
         // this is a completing retire (R-MONEY-3). The stopped path handed over
         // above and took no mark.
+        state.ranToEnd = true;
         this.retire(state, undefined, true);
         logLine("replay.done", {
             scenario: state.scenarioId ?? undefined,
@@ -2075,6 +2077,9 @@ export class ReplayController {
             step: `${plan.currentStepIndex}/${plan.stepCount}`,
             why,
         });
+        // Retired, and still working: until the bundle is composed, a call the
+        // model makes beside this one is beside the plan, not after it.
+        state.diverging = true;
         this.retire(state, undefined);
         // The bundle, and the note in front of it, must fit the channel it goes
         // out on whole: the host cuts a long Bash output in the middle.
@@ -2099,6 +2104,11 @@ export class ReplayController {
             });
             return { kind: "abort" };
         }
+        finally {
+            // Nothing below waits: what this divergence ends in — a hand-over, or
+            // a bundle that ran to the end — is settled before any other hook runs.
+            state.diverging = false;
+        }
         const stop = composed.stopped;
         // Same rule as `runArmed`: a recovered chain whose tools errored is
         // `failed`, and so is one that stopped at a step that broke — its logic
@@ -2175,6 +2185,11 @@ export class ReplayController {
             };
             text = `${state.handover.note}\n\n${composed.text}`;
         }
+        else if (!stop) {
+            // The bundle carries the rest of the chain, and its header tells the
+            // model the work is done: from here the model answers from it.
+            state.ranToEnd = true;
+        }
         // Bash-clean delivery: the model reaches for `Bash` when it cannot call a
         // scripted tool, and a genuine command output is trusted where a `deny`
         // reason is read as adversarial interception.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",