@animalabs/agent-framework 0.22.1 → 0.22.2

package/dist/src/agent.js

@@ -65,15 +65,38 @@ export class Agent {
      * closure) so the next activation can close whatever its predecessor left
      * open — see failOpenKvSubmissions. */
     kvOpenQueue = null;
+    /** The current stream's fresh input so far, as membrane's usage event
+     *  reports it (cumulative across the tool loop): what the maxStreamTokens
+     *  budget checks. */
     lastStreamInputTokens = 0;
-    /** Real prefix size of the last usage event: fresh + cache creation +
-     *  cache read. THE window-shaped number — `lastStreamInputTokens` alone
-     *  omits cached tokens, which are most of a warm stream's window. */
+    /** Real prompt size of the stream's latest provider call that reported a
+     *  prompt, which is what the provider billed it: fresh + cache creation +
+     *  cache read. A call that reports none leaves it as it was (see
+     *  lastStreamUnreportedTokens). Membrane's usage events are cumulative, so
+     *  this is the call's share of its event (cumulativeDelta): the whole event
+     *  for a stream's first call, and the event's own value where a counter
+     *  went back. THE window-shaped number — `lastStreamInputTokens` alone
+     *  omits cached tokens, which are most of a warm stream's window. 0 until a
+     *  call on this stream reports a prompt, and the physical-window
+     *  projection runs only once one has. */
     lastStreamRealInputTokens = 0;
-    /** Output tokens of the last usage event — the prior round's generated
-     *  thinking/text/tool_use, which becomes part of the NEXT round's input
-     *  and so belongs in the physical-window projection. */
+    /** Output tokens of the same call as lastStreamRealInputTokens, or
+     *  maxTokens, the bound on them, when it reported none (a call that ends at
+     *  a tool boundary wrote a tool_use, so a 0 is a count left unreported) —
+     *  the prior round's generated thinking/text/tool_use, which becomes part
+     *  of the NEXT round's input and so belongs in the physical-window
+     *  projection. */
     lastStreamOutputTokens = 0;
+    /** What the stream has grown by since the call lastStreamRealInputTokens
+     *  describes, for the physical-window projection: the blocks appended at
+     *  each boundary the stream continued past (counted only for an agent with
+     *  physicalWindowTokens, whose projection is this field's one reader), and
+     *  the output of each call that reported no prompt (its reported output,
+     *  or maxTokens, the bound on it, when it reported none either). After
+     *  calls that report no prompt, the next request holds the prompt and
+     *  output of the call lastStreamRealInputTokens describes, plus this. 0 at
+     *  stream start and whenever a call reports a prompt. */
+    lastStreamUnreportedTokens = 0;
     maxStreamTokens;
     /** Provider hard context cap (see AgentConfig.physicalWindowTokens). */
     physicalWindowTokens;
@@ -87,6 +110,51 @@ export class Agent {
     configuredSameRoundThinkTextPolicy;
     contextBudgetTargetTokens;
     runtimeSettingsOverrides = {};
+    /**
+     * Counts changes of the live budget (an update, a reset, a restore, a
+     * settle). A compile speaks for the budget it planned at only if the live
+     * budget didn't change while it ran, and what it showed stands only until
+     * the next change.
+     */
+    liveBudgetEpoch = 0;
+    /**
+     * Counts changes of the descent (each arm of one, the same target included,
+     * a reset, a cancel, a settle). A settle proves its target only to a
+     * compile that began under that same descent.
+     */
+    descentEpoch = 0;
+    /** The live budget the last compile planned at, whether it fit, and the live budget's epoch then. */
+    lastCompiledBudget;
+    /** Counts compiles at the live budget as they start. */
+    compilesStarted = 0;
+    /** The start numbers of the compiles at the live budget still running. */
+    compilesRunning = new Set();
+    /**
+     * For each budget, the start of the latest-started compile that has ended
+     * there with a fit or a refusal, whether or not what it showed was
+     * credited. Of two compiles at one budget, the later-started one planned
+     * at the newer store, so an earlier-started one that ends after it is
+     * ignored. That rests on the context manager selecting at the start of
+     * `compile`, before anything it awaits, so start order is selection order;
+     * a context manager that awaits before its select breaks it. (Injections
+     * are added after the select, so compiles with and without them plan
+     * alike.) An entry is
+     * kept only while a compile that started before it is still running, the
+     * only kind it can turn away, so the map is empty whenever no compile
+     * runs.
+     */
+    latestEndedStart = new Map();
+    /** The last outcome the listener recorded; a failed record is told again, and so is any after a change. */
+    recordedCompiledBudget;
+    /**
+     * A boot restore applied a proven budget below the live one at once. Until
+     * the budget is next written (an update that carries one, or a reset of
+     * it) or a compile at it fits, a refusal of a compile at it restores it
+     * paced instead.
+     */
+    restoredAtOnce = false;
+    /** Told when that changes (the framework records it beside the persisted budget). */
+    compiledBudgetListener;
     contextManager;
     membrane;
     constructor(config, contextManager, membrane) {
@@ -208,9 +276,15 @@ export class Agent {
     getRuntimeSettings() {
         const hot = this.getHotContextSettings();
         return {
-            contextBudgetTokens: this.contextBudgetTargetTokens ??
+            // The budget it's set to: the override, where there is one. That is
+            // the target of a descent toward it, or else the live budget, except
+            // while it's kept unapplied: at boot (keepRuntimeSettings), or after a
+            // refused at-once budget couldn't be restored paced (compileAtLiveBudget).
+            contextBudgetTokens: this.runtimeSettingsOverrides.contextBudgetTokens ??
+                this.contextBudgetTargetTokens ??
                 this.contextBudgetTokens ??
                 DEFAULT_CONTEXT_BUDGET_TOKENS,
+            effectiveContextBudgetTokens: this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS,
             ...(hot ? { tailTokens: hot.tailTokens } : {}),
             ...(hot?.transitionPaceTokens !== undefined
                 ? { transitionPaceTokens: hot.transitionPaceTokens }
@@ -232,6 +306,179 @@ export class Agent {
     getRuntimeSettingsOverrides() {
         return { ...this.runtimeSettingsOverrides };
     }
+    /**
+     * Set (or clear) the one listener told when a compile at the live budget
+     * comes out differently from the last: it fit at a budget the last one
+     * didn't plan at (after a settle, the target), or the context manager
+     * refused a budget the last one fit at.
+     */
+    onContextBudgetCompiled(listener) {
+        this.compiledBudgetListener = listener;
+    }
+    /**
+     * The live budget the last compile planned at and fit, if it fit and the
+     * live budget hasn't changed since.
+     */
+    getProvenContextBudgetTokens() {
+        const last = this.lastCompiledBudget;
+        return last?.fit && last.epoch === this.liveBudgetEpoch ? last.budget : undefined;
+    }
+    /**
+     * Set the live budget and the descent target, counting a change of each.
+     * `armed` counts a descent armed here as a change even when its target is
+     * the one already set: a compile that began under the earlier arm isn't
+     * credited with this one's settle.
+     */
+    setContextBudget(budget, target, armed = false) {
+        if (budget !== this.contextBudgetTokens)
+            this.liveBudgetEpoch++;
+        if (armed || target !== this.contextBudgetTargetTokens)
+            this.descentEpoch++;
+        this.contextBudgetTokens = budget;
+        this.contextBudgetTargetTokens = target;
+    }
+    /**
+     * Claim the place of the latest compile to end at `budget` for the one that
+     * started as the `started`th, and say whether it got it: a compile that
+     * started before one that has already ended there is ignored, whichever
+     * finishes last.
+     */
+    claimLatestAt(budget, started) {
+        if (started < (this.latestEndedStart.get(budget) ?? 0))
+            return false;
+        this.latestEndedStart.set(budget, started);
+        return true;
+    }
+    /**
+     * Note what a compile at `budget`, planned at the live budget's `epoch`,
+     * showed. It speaks for the live budget only if that hasn't changed since;
+     * the listener is told either way, so a refusal withdraws the record's
+     * marker for the budget it planned at whatever changed meanwhile.
+     */
+    noteCompiledBudget(budget, fit, epoch) {
+        if (epoch === this.liveBudgetEpoch)
+            this.lastCompiledBudget = { budget, fit, epoch };
+        const recorded = this.recordedCompiledBudget;
+        if (recorded?.budget === budget && recorded.fit === fit && recorded.epoch === epoch)
+            return;
+        // A listener that couldn't record it returns false: nothing is assumed
+        // recorded then, so the next compile tells it again whatever it shows.
+        this.recordedCompiledBudget = this.compiledBudgetListener?.(budget, fit) !== false ? { budget, fit, epoch } : undefined;
+    }
+    /** Compile at the live budget (no explicit one), noting whether it fit. */
+    async compileAtLiveBudget(compile) {
+        const started = ++this.compilesStarted;
+        this.compilesRunning.add(started);
+        try {
+            return await this.compileAtLiveBudgetNoting(compile, started);
+        }
+        finally {
+            this.compilesRunning.delete(started);
+            const earliest = Math.min(...this.compilesRunning);
+            for (const [budget, start] of this.latestEndedStart) {
+                if (start < earliest)
+                    this.latestEndedStart.delete(budget);
+            }
+        }
+    }
+    /** The compile at the live budget that started as the `started`th, and what it showed. */
+    async compileAtLiveBudgetNoting(compile, started) {
+        // The budget this compile plans at, and the descent under way when it
+        // started: a change of either while it runs is no part of what it shows.
+        const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+        const epoch = this.liveBudgetEpoch;
+        const descent = this.descentEpoch;
+        let result;
+        try {
+            result = await compile();
+        }
+        catch (error) {
+            if (error?.name !== 'OverBudgetError')
+                throw error;
+            // A refusal shows the budget it planned at doesn't fit, whatever
+            // changed while it ran: the record's marker for it is withdrawn, and
+            // nothing is credited, unless a compile that started later has already
+            // ended at that budget.
+            if (this.claimLatestAt(live, started))
+                this.noteCompiledBudget(live, false, epoch);
+            // A budget a boot restore applied at once, refused at its first test,
+            // before anything wrote the budget: restore it paced instead, as the
+            // boot would have without its proof, and compile again from the
+            // recipe's budget. (While restoredAtOnce holds, the live budget is the
+            // one the boot applied: every write of the budget clears it, and no
+            // compile runs before the boot's restore.)
+            if (!this.restoredAtOnce)
+                throw error;
+            this.restoredAtOnce = false;
+            // The persisted budget stays in the overrides, so if it can't be
+            // restored paced, no later write erases it.
+            this.setContextBudget(this.configuredContextBudgetTokens, undefined);
+            let outcome;
+            try {
+                this.updateRuntimeSettings({ contextBudgetTokens: live });
+                outcome = 'restored it as a paced descent from the recipe\'s budget';
+            }
+            catch (fallback) {
+                outcome = `couldn't restore it paced (${fallback instanceof Error ? fallback.message : String(fallback)}), ` +
+                    `so it compiles at the recipe's budget, with contextBudgetTokens=${live} kept set`;
+            }
+            console.error(`[agent-settings] ${this.name}: the context manager refused contextBudgetTokens=${live}, which the boot ` +
+                `applied at once; ${outcome}`);
+            return this.compileAtLiveBudget(compile);
+        }
+        this.restoredAtOnce = false;
+        // A settle, here, of the descent this compile began under proves its
+        // target: the frontier fits the window prepared for it. Without a settle,
+        // the compile proves the budget it planned at. Either only if the live
+        // budget didn't change while it ran; a settle of a descent armed while it
+        // ran proves nothing (the next compile at the target does).
+        // A compile that ends here with a fit takes its place in the start order
+        // at the budget it planned at, credited or not; a settle credits its
+        // target only from the latest compile to end there.
+        const latest = this.claimLatestAt(live, started);
+        const sameLive = this.liveBudgetEpoch === epoch;
+        const sameDescent = this.descentEpoch === descent;
+        const settled = this.settleRuntimeSettingsTransition();
+        if (latest && sameLive && settled && sameDescent && this.claimLatestAt(this.contextBudgetTokens, started)) {
+            this.noteCompiledBudget(this.contextBudgetTokens, true, this.liveBudgetEpoch);
+        }
+        else if (latest && sameLive && !settled)
+            this.noteCompiledBudget(live, true, epoch);
+        return result;
+    }
+    /**
+     * The budget compiles plan at, the path a patch's budget takes from it, and
+     * whether a descent is in flight, from the agent's own state alone: what a
+     * runtime-settings preview can still say while the context manager refuses
+     * its queries.
+     * @internal For the framework's runtime-settings preview; not a host API.
+     */
+    runtimeBudgetPath(patch) {
+        const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+        const budget = patch?.contextBudgetTokens;
+        return {
+            liveBudgetTokens: live,
+            path: budget === undefined ? 'none' : budget >= live || patch?.immediate ? 'immediate' : 'paced',
+            transition: this.contextBudgetTargetTokens === undefined ? 'stable' : 'converging',
+        };
+    }
+    /**
+     * Whether the context manager answers its queries, as its readiness says.
+     * It refuses them while its strategy's initialization is pending or has
+     * failed, until a switchBranch or setStrategy succeeds, and a strategy can
+     * refuse its readiness on its own, as the autobiographical one does for a
+     * branch it hasn't reloaded.
+     * @internal For the framework's runtime-settings preview; not a host API.
+     */
+    contextManagerAnswers() {
+        try {
+            this.contextManager.isReady();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Read-only mirror of `updateRuntimeSettings`' budget semantics: derive what
      * the next compile would actually plan at if `patch` were applied, WITHOUT
@@ -248,41 +495,48 @@ export class Agent {
      * - `path: 'none'` — patch absent or budget untouched.
      *
      * `overrides` uses strategy-config names (`recentWindowTokens`,
-     * `kvStableReachTokens`) suitable for `previewContext`. `preparedWindowTokens`
-     * is deliberately never mapped: it is strategy instance state, not config,
-     * and cannot be simulated by a preview. A `kvStableReachTokens` override is
-     * omitted while a prepared window is in flight — the live runtime pace
-     * shadows the config value there, so the override would not be observed.
+     * `kvStableReachTokens`) suitable for `previewContext`. The reach is the one
+     * the next compile plans at (context-manager's kv-stable picker): a
+     * descent's pace while a window is prepared for it, one this patch arms (a
+     * paced decrease) or one in flight that it leaves alone (a patch without a
+     * budget), and the configured reach otherwise. Config is a preview's only
+     * lever: `preparedWindowTokens` and the live runtime pace are strategy
+     * instance state, which a preview can't set. So a preview taken during a
+     * descent plans under that descent's prepared window, and at its live pace
+     * whenever the strategy carries one, which the picker reads before the
+     * configured reach. A boot restore's preflight never meets this: a new
+     * strategy has no window.
      */
     planRuntimeSettings(patch) {
         if (patch && Object.keys(patch).length > 0) {
             this.validateRuntimeSettingsPatch(patch);
         }
         const hot = this.getHotContextSettings();
-        const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+        const { liveBudgetTokens: live, path } = this.runtimeBudgetPath(patch);
+        const budget = patch?.contextBudgetTokens;
         const overrides = {};
         if (patch?.tailTokens !== undefined) {
             overrides.recentWindowTokens = patch.tailTokens;
         }
-        if (patch?.transitionPaceTokens !== undefined &&
-            hot?.preparedWindowTokens === undefined) {
-            overrides.kvStableReachTokens = patch.transitionPaceTokens;
+        // A window is prepared at the next compile when this patch arms a
+        // descent, or leaves one in flight alone; an immediate change clears it.
+        const prepared = hot !== null && (path === 'paced' || (path === 'none' && hot.preparedWindowTokens !== undefined));
+        const reach = prepared
+            ? patch?.transitionPaceTokens ?? hot.transitionPaceTokens ?? DEFAULT_TRANSITION_PACE_TOKENS
+            : this.configuredTransitionPaceTokens;
+        if (reach !== undefined && reach !== this.configuredTransitionPaceTokens) {
+            overrides.kvStableReachTokens = reach;
         }
-        if (patch?.contextBudgetTokens === undefined) {
+        if (budget === undefined) {
             return { effectiveBudgetTokens: live, liveBudgetTokens: live, path: 'none', overrides };
         }
-        if (patch.contextBudgetTokens >= live || patch.immediate) {
-            return {
-                effectiveBudgetTokens: patch.contextBudgetTokens,
-                liveBudgetTokens: live,
-                path: 'immediate',
-                overrides,
-            };
+        if (path === 'immediate') {
+            return { effectiveBudgetTokens: budget, liveBudgetTokens: live, path, overrides };
         }
         return {
             effectiveBudgetTokens: live,
             liveBudgetTokens: live,
-            advisoryTargetTokens: patch.contextBudgetTokens,
+            advisoryTargetTokens: budget,
             path: 'paced',
             overrides,
         };
@@ -306,6 +560,8 @@ export class Agent {
         let nextContextBudget = this.contextBudgetTokens;
         let nextContextTarget = this.contextBudgetTargetTokens;
         let appliedDefaultPace = false;
+        // A paced decrease arms a descent, even to the target already set.
+        let armed = false;
         const hotPatch = {};
         if (patch.tailTokens !== undefined)
             hotPatch.tailTokens = patch.tailTokens;
@@ -335,23 +591,25 @@ export class Agent {
                 }
                 hotPatch.preparedWindowTokens = patch.contextBudgetTokens - this.maxTokens;
                 nextContextTarget = patch.contextBudgetTokens;
+                armed = true;
             }
         }
         if (Object.keys(hotPatch).length > 0) {
             this.updateHotContextSettings(hotPatch);
         }
-        this.contextBudgetTokens = nextContextBudget;
-        this.contextBudgetTargetTokens = nextContextTarget;
+        this.setContextBudget(nextContextBudget, nextContextTarget, armed);
+        // A budget written here is a decision about it, whatever its value: the
+        // boot's at-once fallback (restoredAtOnce) no longer speaks for it.
+        if (patch.contextBudgetTokens !== undefined)
+            this.restoredAtOnce = false;
         if (appliedDefaultPace) {
             this.runtimeSettingsOverrides.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
         }
-        for (const [key, value] of Object.entries(patch)) {
-            if (key === 'sameRoundThinkTextPolicy')
-                continue;
-            if (key === 'immediate')
-                continue; // a mode for this apply, never a persisted setting
-            if (value !== undefined)
-                this.runtimeSettingsOverrides[key] = value;
+        // Only settings reach the override map: `immediate` is a mode for this
+        // apply, and nothing else a caller passes is a setting.
+        for (const key of ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens']) {
+            if (patch[key] !== undefined)
+                this.runtimeSettingsOverrides[key] = patch[key];
         }
         if (patch.sameRoundThinkTextPolicy !== undefined) {
             this.runtimeSettingsOverrides.sameRoundThinkTextPolicy = patch.sameRoundThinkTextPolicy;
@@ -362,6 +620,8 @@ export class Agent {
         const reset = new Set(keys ?? ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens', 'sameRoundThinkTextPolicy']);
         let nextContextBudget = this.contextBudgetTokens;
         let nextContextTarget = this.contextBudgetTargetTokens;
+        // A reset to a recipe budget below the live one arms a descent to it.
+        let armed = false;
         const hotPatch = {};
         if (reset.has('contextBudgetTokens')) {
             const configured = this.configuredContextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
@@ -375,6 +635,7 @@ export class Agent {
                     hotPatch.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
                 }
                 nextContextTarget = configured;
+                armed = true;
             }
             else {
                 nextContextBudget = this.configuredContextBudgetTokens;
@@ -395,10 +656,11 @@ export class Agent {
         }
         if (Object.keys(hotPatch).length > 0)
             this.updateHotContextSettings(hotPatch);
-        this.contextBudgetTokens = nextContextBudget;
-        this.contextBudgetTargetTokens = nextContextTarget;
-        if (reset.has('contextBudgetTokens'))
+        this.setContextBudget(nextContextBudget, nextContextTarget, armed);
+        if (reset.has('contextBudgetTokens')) {
             delete this.runtimeSettingsOverrides.contextBudgetTokens;
+            this.restoredAtOnce = false;
+        }
         if (reset.has('tailTokens'))
             delete this.runtimeSettingsOverrides.tailTokens;
         if (reset.has('transitionPaceTokens')) {
@@ -412,7 +674,7 @@ export class Agent {
     cancelRuntimeSettingsTransition() {
         if (this.contextBudgetTargetTokens !== undefined) {
             this.updateHotContextSettings({ preparedWindowTokens: null });
-            this.contextBudgetTargetTokens = undefined;
+            this.setContextBudget(this.contextBudgetTokens, undefined);
             const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
             if (live === (this.configuredContextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS)) {
                 delete this.runtimeSettingsOverrides.contextBudgetTokens;
@@ -423,10 +685,52 @@ export class Agent {
         }
         return this.getRuntimeSettings();
     }
-    restoreRuntimeSettings(overrides) {
-        return this.updateRuntimeSettings(overrides);
+    /**
+     * Apply persisted settings at construction. `provenBudget` is a budget the
+     * caller has shown fits (the framework, from the record and a preflight),
+     * applied at once: it stands as the last compile's until a compile here
+     * says otherwise. When it's below the live budget, where the proof is what
+     * took the restore off the paced path, a refusal of a compile at it
+     * restores it paced instead, until the budget is next written or a compile
+     * at it fits. At or above the live budget, the restore is at once either
+     * way, and a refusal has nothing to fall back to.
+     */
+    restoreRuntimeSettings(settings, opts) {
+        if (Object.keys(settings).length === 0)
+            return this.getRuntimeSettings();
+        const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+        const snapshot = this.updateRuntimeSettings(settings);
+        if (opts?.provenBudget !== undefined) {
+            this.lastCompiledBudget = { budget: opts.provenBudget, fit: true, epoch: this.liveBudgetEpoch };
+            this.restoredAtOnce = opts.provenBudget < live;
+        }
+        return snapshot;
+    }
+    /**
+     * Keep a persisted budget, tail or pace that couldn't be applied at
+     * construction: it stays in the override map, unapplied, so a later
+     * persisting write keeps it in the record. A budget is reported as the one
+     * set (`contextBudgetTokens`) beside the one compiles plan at
+     * (`effectiveContextBudgetTokens`); a tail or pace stays the strategy's.
+     */
+    keepRuntimeSettings(settings) {
+        for (const key of ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens']) {
+            if (settings[key] !== undefined)
+                this.runtimeSettingsOverrides[key] = settings[key];
+        }
     }
     validateRuntimeSettingsPatch(patch) {
+        this.checkRuntimeSettingsPatch(patch);
+        if ((patch.tailTokens !== undefined || patch.transitionPaceTokens !== undefined) &&
+            !this.getHotContextSettings()) {
+            throw new Error('The active context strategy does not support live tail/transition settings');
+        }
+    }
+    /**
+     * The checks of a runtime-settings patch that need nothing from the context manager.
+     * @internal For the framework's runtime-settings preview; not a host API.
+     */
+    checkRuntimeSettingsPatch(patch) {
         if (Object.keys(patch).length === 0)
             throw new Error('At least one setting is required');
         if (patch.contextBudgetTokens !== undefined) {
@@ -447,20 +751,17 @@ export class Agent {
             patch.sameRoundThinkTextPolicy !== 'private') {
             throw new Error("sameRoundThinkTextPolicy must be 'public' or 'private'");
         }
-        if ((patch.tailTokens !== undefined || patch.transitionPaceTokens !== undefined) &&
-            !this.getHotContextSettings()) {
-            throw new Error('The active context strategy does not support live tail/transition settings');
-        }
     }
+    /** Settle a converging budget once the window is prepared; true if it settled. */
     settleRuntimeSettingsTransition() {
         if (this.contextBudgetTargetTokens === undefined)
-            return;
+            return false;
         const hot = this.getHotContextSettings();
         if (!hot?.prepared)
-            return;
-        this.contextBudgetTokens = this.contextBudgetTargetTokens;
-        this.contextBudgetTargetTokens = undefined;
+            return false;
+        this.setContextBudget(this.contextBudgetTargetTokens, undefined);
         this.updateHotContextSettings({ preparedWindowTokens: null });
+        return true;
     }
     /**
      * RFC-006 consumed watermark: the newest stored message at the last compile
@@ -498,29 +799,56 @@ export class Agent {
             return null;
         }
     }
+    /** A committing compile, as for a request that is sent: the context
+     * manager commits what it commits for one, the consumed watermark moves,
+     * and a prepared budget change settles. To inspect what the agent would
+     * see, use the framework's `previewActivation`, which compiles as a dry
+     * run. */
     async compileContext(budget) {
         // RFC-006 §3.3: consumption is determined at assembly — a compile that
         // fails assembled nothing, so the watermark moves only on success.
         const watermark = this.pendingWatermark();
-        const result = await this.contextManager.compile(this.compileBudget(budget));
+        const compile = () => this.contextManager.compile(this.compileBudget(budget));
+        const result = budget ? await compile() : await this.compileAtLiveBudget(compile);
         if (watermark)
             this.consumedWatermark = watermark;
-        if (!budget)
-            this.settleRuntimeSettingsTransition();
         return result;
     }
     /**
-     * Compile the context with injections.
-     * Same as compileContext but forwards injections (e.g. from MCPL servers)
-     * to the context manager so they are merged into the compiled messages.
+     * Compile the context with injections (e.g. from MCPL servers), which the
+     * context manager merges into the compiled messages. Without
+     * `opts.dryRun` it commits as `compileContext` does: the consumed
+     * watermark moves, and a compile at the live window settles a prepared
+     * budget change. With `opts.dryRun`, for a compile that will never be
+     * sent, it does neither (see below).
      */
     async compileWithInjections(budget, injections, opts) {
-        const watermark = this.pendingWatermark();
-        const result = await this.contextManager.compile(this.compileBudget(budget), injections, opts);
+        // A dry run is a compile that will never be sent. The context manager
+        // persists no fold resolutions for it and queues none of the compression
+        // or merge work its fold plan calls for. Its thinking binding
+        // (context-manager#160, not yet released) will commit stamps and add a
+        // compile awaiting acceptance for a committing compile only. Here nothing
+        // moves either: the agent never read what a dry run assembled, so the
+        // consumed watermark stays. A dry run proves nothing about the budget
+        // either, so it goes straight to the compile, around
+        // compileAtLiveBudget: it settles no descent (a prepared budget change
+        // waits for the compile that is sent), notes no compiled budget, and
+        // restores nothing the boot applied at once, whether it fits or is
+        // refused.
+        //
+        // Context-manager 0.14 leaves what a select leaves behind as the last
+        // committing compile left it, on every path out of a dry run, throws
+        // included: no chunk record and no compression queued for a chunk the
+        // dry run closes, no calibration, and none of the bookkeeping the next
+        // compile or an observer reads (its `SelectOptions.dryRun` gives the
+        // contract). The one thing a dry run can still leave is the release of a
+        // compression hold whose deadline has passed, which `compile` does for
+        // any compile before it selects.
+        const watermark = opts?.dryRun ? null : this.pendingWatermark();
+        const compile = () => this.contextManager.compile(this.compileBudget(budget), injections, opts);
+        const result = budget || opts?.dryRun ? await compile() : await this.compileAtLiveBudget(compile);
         if (watermark)
             this.consumedWatermark = watermark;
-        if (!budget)
-            this.settleRuntimeSettingsTransition();
         return result;
     }
     // ==========================================================================
@@ -673,10 +1001,13 @@ export class Agent {
      *
      * This is the single source of truth for request assembly, shared by the
      * real activation path (`startStreamWithInjections`) and debug/preview
-     * tooling (`Framework.previewActivation`). It is pure and non-mutating:
-     * it does not touch agent state and does not call the membrane, and
-     * `ContextManager.compile` is itself side-effect-free (compression runs in
-     * the background). Safe to call regardless of the agent's current status.
+     * tooling (`Framework.previewActivation`). It does not call the membrane.
+     * A compile that is sent commits what the context manager commits for it
+     * (fold resolutions, the compression its fold plan calls for, the consumed
+     * watermark); a preview passes `options.dryRun`, so its compile commits
+     * none of that (see `compileWithInjections` for what a dry run still
+     * leaves). Either way the context manager is handed the compression tool
+     * definitions. Safe to call regardless of the agent's current status.
      * It doesn't wait for the tool-result guard's annotations, so a preview
      * never waits on a workspace write (rollback, undo and redo report one), and
      * may show a withheld stub before its place is added; the activation waits
@@ -704,7 +1035,12 @@ export class Agent {
                 system: this.buildSystemPrompt(prospectiveSystemInjections),
             })
             : undefined;
-        let { messages, systemInjections } = await this.compileWithInjections(budget, injections, immutablePrefixHash ? { kvUnifiedImmutablePrefixHash: immutablePrefixHash } : undefined);
+        let { messages, systemInjections } = await this.compileWithInjections(budget, injections, immutablePrefixHash || options.dryRun
+            ? {
+                ...(immutablePrefixHash ? { kvUnifiedImmutablePrefixHash: immutablePrefixHash } : {}),
+                ...(options.dryRun ? { dryRun: true } : {}),
+            }
+            : undefined);
         // Sanitize: strip empty/whitespace text blocks and drop messages left with
         // no content. The Anthropic API rejects empty text blocks with 400
         // "messages: text content blocks must be non-empty"; when such a block
@@ -817,10 +1153,13 @@ export class Agent {
         // the prior stream's window size — on the physical-window restart path
         // that inherited value IS the oversized number that caused the restart,
         // and projecting on it before this stream's first usage event would
-        // restart again (loop). The `> 0` guard downstream means "no usage
-        // observed on THIS stream yet" only because of this reset.
+        // restart again (loop). The `> 0` guard downstream means "no call on
+        // THIS stream has reported a prompt yet" only because of this reset (a
+        // call that reports none leaves these as they were, and adds to
+        // lastStreamUnreportedTokens instead).
         this.lastStreamRealInputTokens = 0;
         this.lastStreamOutputTokens = 0;
+        this.lastStreamUnreportedTokens = 0;
         // Compiled only once each withheld stub's annotation has finished,
         // including one that began during the compile, and after a stub edit that
         // failed has been retried (see afterAnnotations).