@skillstate/opencode 2.2.2 → 3.0.1

package/dist/runtime.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The runtime that owns the loop — the half of Algorithm 1 a plugin otherwise
+ * has to ask the model to do for it.
+ *
+ * ── What was missing, and why it was not a model problem ──────────────────
+ *
+ * A.4 tells the model to answer with `{state_patch, action}` and says nothing
+ * about who runs `action`, because in the paper a runtime does: Algorithm 1
+ * runs aₜ and feeds Oₜ₊₁ back. Everything here existed to compensate for that
+ * gap with prompts — a note in the system slot, a rule in the spec, a notice
+ * about drift. Measured on two models, in three placements: the run still
+ * ended after the first or second file.
+ *
+ * And the model was right to stop. It was asked for a patch, it produced a
+ * correct patch, and the instruction had been satisfied completely. Every
+ * prompt added to compensate made the ask larger without ever supplying the
+ * missing executor. The defect was that the step loop belonged to the model at
+ * all; it belongs here.
+ *
+ * ── The mechanism ────────────────────────────────────────────────────────
+ *
+ * When a patch is applied and its `action` is not terminal, this calls
+ * `session.prompt` to request the next step. The context hook then rebuilds
+ * (P, Σₜ, Oₜ) from the new state, the model reads the observation, and the
+ * cycle continues without the model having volunteered anything.
+ *
+ * The plugin still cannot invoke a tool on the model's behalf — the host owns
+ * that, and that is a real limit. What it can own is step advancement, and
+ * that is exactly the part the loop was missing. Aₜ is a request, and the
+ * model performs it; who decides that step t+1 happens at all is the
+ * runtime's job, and it is this.
+ */
+/**
+ * Default ceiling on runtime-driven steps before it stops asking.
+ *
+ * 100, not a number chosen here. §10.1's reference `Run` signature reads
+ * `Run(P, Σ0, O0, llm, execute, isDone, maxSteps = 100)`, and this value was 64
+ * until the paper was re-read for that line — with a comment claiming the paper
+ * did not give a number. It does.
+ *
+ * The cost of getting this wrong was measured rather than argued: at 64 a
+ * thirty-file task stopped at 25/30 having answered correctly, and the ceiling
+ * looked like the binding constraint when the real cause was that narration
+ * turns were each spending a step. Fixing the retry loop changed the pace;
+ * matching the paper's ceiling is what makes the two agree.
+ */
+export declare const DEFAULT_MAX_STEPS = 100;
+/**
+ * Why {@link RuntimeDriver.advance} declined to spend a step.
+ *
+ * `'terminal'` — the model emitted a terminal action: a real ending.
+ * `'max_steps'` — §10.1's ceiling arrived. NOT completion.
+ * `'no_action'` — the turn carried no action to advance on.
+ * `'host_refused'` — the host would not start a turn.
+ */
+export type StopReason = 'terminal' | 'max_steps' | 'no_action' | 'host_refused';
+/** What the loop driver needs from its host, injected so it is testable. */
+export interface RuntimeDriverOptions {
+    /**
+     * Ask the host for another step in `sessionID`. Returns true when the
+     * request was accepted, false when the host refused — a refusal is a fact
+     * to count, not an error to throw, because it usually means the session has
+     * already ended.
+     */
+    readonly prompt: (sessionID: string, text: string) => Promise<boolean>;
+    /** Hard ceiling on runtime-driven steps per session. */
+    readonly maxSteps?: number;
+    /** §5.1's `k`. Attempts per step are `k + 1`. */
+    readonly retries?: number;
+}
+/** One advancement the driver decided to make. */
+export interface RuntimeStep {
+    readonly sessionID: string;
+    /** The action the model asked for, carried forward verbatim. */
+    readonly action: string;
+    /** The step number, 1-based, for this session. */
+    readonly step: number;
+    /** True when this prompt was a §5.1 retry inside the current step. */
+    readonly retry: boolean;
+}
+/** §5.1 line 2: `k` retries, so `k + 1` attempts per step. */
+export declare const DEFAULT_VALIDATION_RETRIES = 2;
+/** §5.1 line 10: the sentinel a step returns when every attempt failed. */
+export declare const INVALID_PATCH = "__invalid_patch__";
+export declare class RuntimeDriver {
+    #private;
+    /** Every advancement made, for diagnostics and tests. */
+    readonly advanced: RuntimeStep[];
+    /** Every step that exhausted its attempts, for diagnostics and tests. */
+    readonly invalidated: string[];
+    constructor(options: RuntimeDriverOptions);
+    /**
+     * How many attempts the current step has spent, and what it should do next.
+     *
+     * `retry` means the step continues: the loop is asked again, the corrective
+     * feedback rides in Oₜ, and the step number does not move. `advance` means
+     * the attempts are spent and the next prompt opens step t+1. `done` means
+     * the step succeeded and needs no further prompting at all.
+     */
+    record(sessionID: string, applied: boolean): {
+        readonly action: 'retry' | 'advance';
+        readonly attempt: number;
+        readonly step: number;
+        readonly result: typeof INVALID_PATCH | null;
+    };
+    /**
+     * Whether an action ends the procedure.
+     *
+     * Exported as a function because the test for it is worth more than the
+     * call site: getting this wrong in the permissive direction costs tokens
+     * forever, and getting it wrong in the strict direction ends a run early,
+     * so both directions are pinned.
+     */
+    static isTerminal(action: string): boolean;
+    /**
+     * Why {@link RuntimeDriver.advance} last declined to spend a step.
+     *
+     * Four ways `advance` returns `null` and the caller cannot tell them from the
+     * return value: the model emitted a terminal action (a real ending), the host
+     * would not start a turn, the turn had no action at all, or the ceiling
+     * arrived. The last is the one that lies — a loop stopped at `maxSteps` is
+     * indistinguishable from a loop that ran its course.
+     *
+     * A 90-file run was read as "the model lost track of its running sum at file
+     * 78" when the ceiling had arrived at step 100, mid-file-79, with the work
+     * still going. Nothing in this driver said so, and the caller discards
+     * `advance`'s return value entirely. The honest fix is to make the reason
+     * readable, not to guess it back out of a transcript.
+     */
+    get lastStop(): {
+        reason: StopReason;
+        sessionID: string;
+        steps: number;
+    } | undefined;
+    /**
+     * Advance the loop for one applied patch.
+     *
+     * Returns the step it took, or `null` when it deliberately did not — a
+     * terminal action, an already-ended turn, or the ceiling. The ceiling is the
+     * important one: a runtime that asks forever against a model that keeps
+     * answering "continue" is a runaway, and the cost of that is paid at the
+     * provider.
+     */
+    advance(sessionID: string, action: string | undefined): Promise<RuntimeStep | null>;
+    /**
+     * What the runtime did at the end of the last step, for Oₜ.
+     *
+     * A REPORT, not an order, and the distinction is the whole of this method.
+     *
+     * The model's own action used to ride here. §2 forbids it — "the agent
+     * receives only Oₜ — never prior observations or actions" — and with it in
+     * place the model obeyed a stored order rather than choosing: 54 `read` calls
+     * for thirty files, and one grep used three times as a side errand, where a
+     * control with no step driver read one file, ran ONE grep and finished in six
+     * calls. The order was its own past action, so it never looked for a better
+     * way than the one already written down.
+     *
+     * Simply removing it was also wrong, and measurably so. The runtime re-prompts
+     * when a turn produced a patch but no tool call, and with nothing in Oₜ
+     * saying why, the model looped instead of converging: 98 text blocks against
+     * a baseline of 43, and 7.9M prompt tokens against 1.6M. It read 41 files
+     * rather than 53, so the re-reads did halve — and the run never finished.
+     *
+     * So the environment says what it did. Factual, not imperative, and the model
+     * still chooses its own next action, which is the division the paper draws:
+     * `execute(aₜ, Σ_{t+1})` is the runtime's, and choosing aₜ is the model's.
+     */
+    stepReport(sessionID: string): string | undefined;
+    /**
+     * Note what the environment executed on this session's behalf, and return how
+     * much of it is new.
+     *
+     * The context hook is the only place the host's own tool results are visible,
+     * and it runs on EVERY model request. A tool message that is still the newest
+     * one across two requests — which happens whenever the model is re-asked
+     * before it has produced a message of its own — would therefore be counted
+     * twice, and a report of "2 actions ran" for one `read` is a lie of exactly
+     * the kind this whole method exists to stop.
+     *
+     * So the driver keeps a watermark per session: the id of the last message it
+     * counted, and only results after it are new. Idempotent by construction —
+     * calling it with the same messages twice is a no-op, which is also what makes
+     * it testable without a host.
+     */
+    noteExecutions(sessionID: string, messages: ReadonlyArray<{
+        id: string;
+        role: string;
+        content: unknown;
+    }>): number;
+    /**
+     * Take the action this session was last asked to perform, if any.
+     *
+     * Taken exactly once per step, so a prompt built twice for one turn cannot
+     * show the model the same continuation twice — the same discipline the
+     * feedback queue uses, and for the same reason.
+     */
+    takeContinuation(sessionID: string): string | undefined;
+    /** Forget a session's pending action, on reset or teardown. */
+    forget(sessionID: string): void;
+    /** Steps taken for a session, for diagnostics. */
+    stepsFor(sessionID: string): number;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;AAEjF,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,2EAA2E;AAC3E,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD,qBAAa,aAAa;;IA2CxB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAM;IAGtC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAM;IAEpC,YAAY,OAAO,EAAE,oBAAoB,EAIxC;IAED;;;;;;;OAOG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,GACf;QACD,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;QACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,GAAG,IAAI,CAAC;KAC9C,CA8BA;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAI,QAAQ,IAAI;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAEnF;IAaD;;;;;;;;OAQG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAgCxF;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAmBhD;IAED;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,MAAM,CAwBjH;IAED;;;;;;OAMG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKtD;IAED,+DAA+D;IAC/D,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE9B;IAED,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElC;CACF"}

package/dist/runtime.js

@@ -0,0 +1,332 @@
+/**
+ * The runtime that owns the loop — the half of Algorithm 1 a plugin otherwise
+ * has to ask the model to do for it.
+ *
+ * ── What was missing, and why it was not a model problem ──────────────────
+ *
+ * A.4 tells the model to answer with `{state_patch, action}` and says nothing
+ * about who runs `action`, because in the paper a runtime does: Algorithm 1
+ * runs aₜ and feeds Oₜ₊₁ back. Everything here existed to compensate for that
+ * gap with prompts — a note in the system slot, a rule in the spec, a notice
+ * about drift. Measured on two models, in three placements: the run still
+ * ended after the first or second file.
+ *
+ * And the model was right to stop. It was asked for a patch, it produced a
+ * correct patch, and the instruction had been satisfied completely. Every
+ * prompt added to compensate made the ask larger without ever supplying the
+ * missing executor. The defect was that the step loop belonged to the model at
+ * all; it belongs here.
+ *
+ * ── The mechanism ────────────────────────────────────────────────────────
+ *
+ * When a patch is applied and its `action` is not terminal, this calls
+ * `session.prompt` to request the next step. The context hook then rebuilds
+ * (P, Σₜ, Oₜ) from the new state, the model reads the observation, and the
+ * cycle continues without the model having volunteered anything.
+ *
+ * The plugin still cannot invoke a tool on the model's behalf — the host owns
+ * that, and that is a real limit. What it can own is step advancement, and
+ * that is exactly the part the loop was missing. Aₜ is a request, and the
+ * model performs it; who decides that step t+1 happens at all is the
+ * runtime's job, and it is this.
+ */
+/** Actions that mean the model considers the procedure finished. */
+const TERMINAL_ACTIONS = new Set(['done', 'complete', 'completed', 'finished', 'stop', 'end', '']);
+/**
+ * Default ceiling on runtime-driven steps before it stops asking.
+ *
+ * 100, not a number chosen here. §10.1's reference `Run` signature reads
+ * `Run(P, Σ0, O0, llm, execute, isDone, maxSteps = 100)`, and this value was 64
+ * until the paper was re-read for that line — with a comment claiming the paper
+ * did not give a number. It does.
+ *
+ * The cost of getting this wrong was measured rather than argued: at 64 a
+ * thirty-file task stopped at 25/30 having answered correctly, and the ceiling
+ * looked like the binding constraint when the real cause was that narration
+ * turns were each spending a step. Fixing the retry loop changed the pace;
+ * matching the paper's ceiling is what makes the two agree.
+ */
+export const DEFAULT_MAX_STEPS = 100;
+/** §5.1 line 2: `k` retries, so `k + 1` attempts per step. */
+export const DEFAULT_VALIDATION_RETRIES = 2;
+/** §5.1 line 10: the sentinel a step returns when every attempt failed. */
+export const INVALID_PATCH = '__invalid_patch__';
+export class RuntimeDriver {
+    #prompt;
+    #maxSteps;
+    #retries;
+    #steps = new Map();
+    /** The action each session is mid-way through, read by the context hook. */
+    #pending = new Map();
+    /**
+     * Attempts spent on the CURRENT step, per session.
+     *
+     * §5.1 lines 2–8: a step is up to `k + 1` attempts at the *same* Aₜ, each
+     * after the first carrying the reason the last one failed. Only when all of
+     * them fail does the step return `__invalid_patch__` and the loop move on.
+     *
+     * This was missing, and it was not a small omission. Without it every failed
+     * attempt became its own step, so the corrective feedback arrived on a
+     * *different* Aₜ than the one it was correcting — which is precisely what
+     * §7's rollback-retry forbids. Measured consequence: the model narrated
+     * instead of patching on about 63% of turns, and because the state advances
+     * only on patching turns, the state grew at 37% of the step rate. Thirty
+     * files cost about 88 steps against a ceiling of 64, and the run stopped at
+     * 25/30 having answered correctly anyway.
+     *
+     * A narration turn is now an attempt, not a step.
+     */
+    #attempts = new Map();
+    /**
+     * Tool results seen since the last report, per session. The environment's own
+     * account of what it did — the only account that is not the model's claim.
+     */
+    #executed = new Map();
+    /**
+     * The id of the last message counted, per session.
+     *
+     * The context hook runs on every model request, so without this a tool
+     * message that stays newest across two requests is counted twice. See
+     * {@link noteExecutions}.
+     */
+    #counted = new Map();
+    /** What {@link record} decided, so `advance` does not re-decide it. */
+    #decisions = new Map();
+    /** Every advancement made, for diagnostics and tests. */
+    advanced = [];
+    #stops = new Map();
+    #lastStoppedSession = '';
+    /** Every step that exhausted its attempts, for diagnostics and tests. */
+    invalidated = [];
+    constructor(options) {
+        this.#prompt = options.prompt;
+        this.#maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+        this.#retries = options.retries ?? DEFAULT_VALIDATION_RETRIES;
+    }
+    /**
+     * How many attempts the current step has spent, and what it should do next.
+     *
+     * `retry` means the step continues: the loop is asked again, the corrective
+     * feedback rides in Oₜ, and the step number does not move. `advance` means
+     * the attempts are spent and the next prompt opens step t+1. `done` means
+     * the step succeeded and needs no further prompting at all.
+     */
+    record(sessionID, applied) {
+        if (applied) {
+            // Lines 11-13: the patch is applied and the step still opens the next
+            // one, chaining Oₜ into Oₜ₊₁. A success is not the end of the loop —
+            // only a terminal action or the ceiling is, and both live in `advance`.
+            this.#attempts.delete(sessionID);
+            this.#decisions.set(sessionID, 'advance');
+            return {
+                action: 'advance',
+                attempt: 0,
+                step: (this.#steps.get(sessionID) ?? 0) + 1,
+                result: null,
+            };
+        }
+        const attempt = (this.#attempts.get(sessionID) ?? 0) + 1;
+        this.#attempts.set(sessionID, attempt);
+        if (attempt > this.#retries) {
+            // Line 10: Σ_t is UNCHANGED and never written. The step is spent.
+            this.#attempts.delete(sessionID);
+            this.invalidated.push(sessionID);
+            this.#decisions.set(sessionID, 'advance');
+            return {
+                action: 'advance',
+                attempt,
+                step: (this.#steps.get(sessionID) ?? 0) + 1,
+                result: INVALID_PATCH,
+            };
+        }
+        this.#decisions.set(sessionID, 'retry');
+        return { action: 'retry', attempt, step: this.#steps.get(sessionID) ?? 0, result: null };
+    }
+    /**
+     * Whether an action ends the procedure.
+     *
+     * Exported as a function because the test for it is worth more than the
+     * call site: getting this wrong in the permissive direction costs tokens
+     * forever, and getting it wrong in the strict direction ends a run early,
+     * so both directions are pinned.
+     */
+    static isTerminal(action) {
+        return TERMINAL_ACTIONS.has(action.trim().toLowerCase());
+    }
+    /**
+     * Why {@link RuntimeDriver.advance} last declined to spend a step.
+     *
+     * Four ways `advance` returns `null` and the caller cannot tell them from the
+     * return value: the model emitted a terminal action (a real ending), the host
+     * would not start a turn, the turn had no action at all, or the ceiling
+     * arrived. The last is the one that lies — a loop stopped at `maxSteps` is
+     * indistinguishable from a loop that ran its course.
+     *
+     * A 90-file run was read as "the model lost track of its running sum at file
+     * 78" when the ceiling had arrived at step 100, mid-file-79, with the work
+     * still going. Nothing in this driver said so, and the caller discards
+     * `advance`'s return value entirely. The honest fix is to make the reason
+     * readable, not to guess it back out of a transcript.
+     */
+    get lastStop() {
+        return this.#stops.get(this.#lastStoppedSession);
+    }
+    #stop(reason, sessionID, steps) {
+        const entry = {
+            reason,
+            sessionID,
+            steps: steps ?? this.#steps.get(sessionID) ?? 0,
+        };
+        this.#stops.set(sessionID, entry);
+        this.#lastStoppedSession = sessionID;
+        return null;
+    }
+    /**
+     * Advance the loop for one applied patch.
+     *
+     * Returns the step it took, or `null` when it deliberately did not — a
+     * terminal action, an already-ended turn, or the ceiling. The ceiling is the
+     * important one: a runtime that asks forever against a model that keeps
+     * answering "continue" is a runaway, and the cost of that is paid at the
+     * provider.
+     */
+    async advance(sessionID, action) {
+        if (action === undefined)
+            return this.#stop('no_action', sessionID);
+        if (RuntimeDriver.isTerminal(action))
+            return this.#stop('terminal', sessionID);
+        // A retry re-asks within the CURRENT step and must not spend another one.
+        // §5.1 counts attempts inside a step, not steps: the whole point of the
+        // bounded retry is that the model gets its corrections without the loop
+        // moving on, and a retry that consumed a step would be indistinguishable
+        // from the behaviour this replaced.
+        const decision = this.#decisions.get(sessionID);
+        this.#decisions.delete(sessionID);
+        const isRetry = decision === 'retry';
+        const step = isRetry ? (this.#steps.get(sessionID) ?? 0) : (this.#steps.get(sessionID) ?? 0) + 1;
+        if (step > this.#maxSteps)
+            return this.#stop('max_steps', sessionID, step - 1);
+        // The action is remembered BEFORE the host is asked, because the context
+        // hook that follows reads it, and a host that starts the turn quickly must
+        // not find an empty slot. The text handed to `session.prompt` is only a
+        // wake-up: `applyPaperContext` clears the messages, so the model reads the
+        // action from Oₜ instead. See the `continuation` option.
+        this.#pending.set(sessionID, action);
+        const asked = await this.#prompt(sessionID, action);
+        if (!asked) {
+            this.#pending.delete(sessionID);
+            return this.#stop('host_refused', sessionID);
+        }
+        this.#steps.set(sessionID, step);
+        const record = { sessionID, action, step, retry: isRetry };
+        this.advanced.push(record);
+        return record;
+    }
+    /**
+     * What the runtime did at the end of the last step, for Oₜ.
+     *
+     * A REPORT, not an order, and the distinction is the whole of this method.
+     *
+     * The model's own action used to ride here. §2 forbids it — "the agent
+     * receives only Oₜ — never prior observations or actions" — and with it in
+     * place the model obeyed a stored order rather than choosing: 54 `read` calls
+     * for thirty files, and one grep used three times as a side errand, where a
+     * control with no step driver read one file, ran ONE grep and finished in six
+     * calls. The order was its own past action, so it never looked for a better
+     * way than the one already written down.
+     *
+     * Simply removing it was also wrong, and measurably so. The runtime re-prompts
+     * when a turn produced a patch but no tool call, and with nothing in Oₜ
+     * saying why, the model looped instead of converging: 98 text blocks against
+     * a baseline of 43, and 7.9M prompt tokens against 1.6M. It read 41 files
+     * rather than 53, so the re-reads did halve — and the run never finished.
+     *
+     * So the environment says what it did. Factual, not imperative, and the model
+     * still chooses its own next action, which is the division the paper draws:
+     * `execute(aₜ, Σ_{t+1})` is the runtime's, and choosing aₜ is the model's.
+     */
+    stepReport(sessionID) {
+        const step = this.#steps.get(sessionID);
+        if (step === undefined)
+            return undefined;
+        const executed = this.#executed.get(sessionID) ?? 0;
+        this.#executed.delete(sessionID);
+        // The count is the environment's, and it is read from tool RESULTS the host
+        // handed back — not from the action the model proposed. Those are different
+        // facts: a model can name an action and never cause it, which is precisely
+        // what happened for a week in this project.
+        //
+        // The sentence used to be unconditional, and it was wrong whenever a model
+        // both patched and acted in one turn. On the n=3 run it happened to be
+        // right — 45 patches, 58 tool calls, and not one turn containing both — but
+        // nothing enforced that, it was a property of the model that day, and a
+        // false report in O_t is worse than no report: O_t is the environment's
+        // channel and the whole contract is that what arrives there happened.
+        return executed === 0
+            ? `step ${step} ended; your state patch was applied; nothing was executed.`
+            : `step ${step} ended; your state patch was applied; ${executed} action${executed === 1 ? '' : 's'} ran.`;
+    }
+    /**
+     * Note what the environment executed on this session's behalf, and return how
+     * much of it is new.
+     *
+     * The context hook is the only place the host's own tool results are visible,
+     * and it runs on EVERY model request. A tool message that is still the newest
+     * one across two requests — which happens whenever the model is re-asked
+     * before it has produced a message of its own — would therefore be counted
+     * twice, and a report of "2 actions ran" for one `read` is a lie of exactly
+     * the kind this whole method exists to stop.
+     *
+     * So the driver keeps a watermark per session: the id of the last message it
+     * counted, and only results after it are new. Idempotent by construction —
+     * calling it with the same messages twice is a no-op, which is also what makes
+     * it testable without a host.
+     */
+    noteExecutions(sessionID, messages) {
+        const seen = this.#counted.get(sessionID);
+        // Everything up to and INCLUDING the watermark was already counted. Skipping
+        // only the matching id is not enough: a request that carries three new
+        // messages would advance the watermark three times, and the next request
+        // would re-count the first two.
+        const start = seen === undefined ? 0 : messages.findIndex((m) => m.id === seen) + 1;
+        let fresh = 0;
+        for (const message of messages.slice(start)) {
+            if (message.role === 'tool' && Array.isArray(message.content)) {
+                fresh += message.content.filter((part) => typeof part === 'object' &&
+                    part !== null &&
+                    String(part.type).startsWith('tool-result')).length;
+            }
+        }
+        const last = messages[messages.length - 1];
+        // A watermark that is not in this list means the host trimmed the history.
+        // Everything present is then new, and `start` is 0, so nothing is lost.
+        if (last !== undefined)
+            this.#counted.set(sessionID, last.id);
+        if (fresh > 0)
+            this.#executed.set(sessionID, (this.#executed.get(sessionID) ?? 0) + fresh);
+        return fresh;
+    }
+    /**
+     * Take the action this session was last asked to perform, if any.
+     *
+     * Taken exactly once per step, so a prompt built twice for one turn cannot
+     * show the model the same continuation twice — the same discipline the
+     * feedback queue uses, and for the same reason.
+     */
+    takeContinuation(sessionID) {
+        const action = this.#pending.get(sessionID);
+        if (action === undefined)
+            return undefined;
+        this.#pending.delete(sessionID);
+        return action;
+    }
+    /** Forget a session's pending action, on reset or teardown. */
+    forget(sessionID) {
+        this.#pending.delete(sessionID);
+    }
+    /** Steps taken for a session, for diagnostics. */
+    stepsFor(sessionID) {
+        return this.#steps.get(sessionID) ?? 0;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}