@animalabs/agent-framework 0.22.1 → 0.22.3

package/dist/src/agent.js

@@ -1,6 +1,7 @@
 import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import { ToolResultGuard } from './tool-result-guard.js';
+import { assertBooleanSetting, holdsSettings } from './config-checks.js';
 import { indexSilentTickRows, separateSilentHeartbeatTicks, silentHeartbeatSeparatorTurn, } from './silent-heartbeat.js';
 import { nonErrorResultText, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
 function stableHash(value) {
@@ -18,6 +19,32 @@ function stableHash(value) {
 const DEFAULT_CONTEXT_BUDGET_TOKENS = 100_000;
 const DEFAULT_TRANSITION_PACE_TOKENS = 16_000;
 const DEFAULT_SAME_ROUND_THINK_TEXT_POLICY = 'public';
+/**
+ * Refuse an agent config whose `promptCaching`, `toolResultGuard`,
+ * `toolWrapperProseGuard`, `thinking.enabled` or `refusalHandling.autoRewind`
+ * holds anything but true or false (assertBooleanSetting), or whose `thinking`
+ * or `refusalHandling` is anything but an object, null or false
+ * (holdsSettings). The constructor runs it first, so the rule holds wherever
+ * an Agent is built. `create()` also runs it for each of its agents before
+ * anything opens, and `createEphemeralAgent` before it reserves the name, so a
+ * refusal there leaves nothing behind. Membrane reads `thinking.enabled`, and
+ * the refusal is here because the setting is AgentConfig's.
+ */
+export function assertAgentSwitches(config) {
+    const agent = `Agent "${config.name}"`;
+    assertBooleanSetting(`${agent} promptCaching`, config.promptCaching, 'true or leaving it out marks requests for prompt caching, and false leaves the markers off, for transports that refuse them');
+    if (holdsSettings(`${agent} thinking`, config.thinking, '{ enabled: true }')) {
+        assertBooleanSetting(`${agent} thinking.enabled`, config.thinking.enabled, 'true asks the provider for extended thinking, and false or leaving it out doesn\'t');
+    }
+    if (holdsSettings(`${agent} refusalHandling`, config.refusalHandling, '{ autoRewind: true }')) {
+        assertBooleanSetting(`${agent} refusalHandling.autoRewind`, config.refusalHandling.autoRewind, 'true redacts the turn that tripped a refusal and runs again, up to maxRewinds times, ' +
+            'and false or leaving it out doesn\'t');
+    }
+    assertBooleanSetting(`${agent} toolResultGuard`, config.toolResultGuard, 'true turns on tool-output admission, with one guarded retry after a provider refusal, ' +
+        'and false or leaving it out doesn\'t');
+    assertBooleanSetting(`${agent} toolWrapperProseGuard`, config.toolWrapperProseGuard, 'true keeps a response whose whole prose is a tool-call-shaped wrapper from running or entering the agent\'s history, ' +
+        'and false or leaving it out doesn\'t');
+}
 /**
  * An agent wraps a context manager and manages inference state.
  */
@@ -65,15 +92,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,9 +137,55 @@ 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) {
+        assertAgentSwitches(config);
         this.name = config.name;
         this.model = config.model;
         this.systemPrompt = config.systemPrompt;
@@ -99,11 +195,11 @@ export class Agent {
         this.temperature = config.temperature;
         this.thinking = config.thinking;
         this.refusalHandling = config.refusalHandling;
-        this.toolResultGuard = new ToolResultGuard(config.name, contextManager, config.toolResultGuard);
+        this.toolResultGuard = new ToolResultGuard(config.name, contextManager, config.toolResultGuard === true);
         this.proseRouting = config.proseRouting ?? 'locus';
-        this.toolWrapperProseGuard = config.toolWrapperProseGuard ?? false;
+        this.toolWrapperProseGuard = config.toolWrapperProseGuard === true;
         this.cacheTtl = config.cacheTtl ?? '1h';
-        this.promptCaching = config.promptCaching ?? true;
+        this.promptCaching = config.promptCaching !== false;
         this.prefillUserMessage = config.prefillUserMessage;
         this.providerParams = config.providerParams;
         this.sameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
@@ -208,9 +304,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 +334,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 +523,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 +588,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 +619,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 +648,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 +663,7 @@ export class Agent {
                     hotPatch.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
                 }
                 nextContextTarget = configured;
+                armed = true;
             }
             else {
                 nextContextBudget = this.configuredContextBudgetTokens;
@@ -395,10 +684,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 +702,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 +713,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,35 +779,54 @@ 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
-     * of a model request, per branch. Everything above it has never been in a
+     * of a model request, or at the last tool boundary that injected messages
+     * into a live one, per branch. Everything above it has never been in a
      * request and may still be replaced or withdrawn in place by its sender.
      */
     consumedWatermark = null;
+    /** Counts marks: a compile writes its watermark back only if no mark was
+     *  made while it ran (a tool boundary's, or another compile's). */
+    watermarkMarks = 0;
     getConsumedWatermark() {
         return this.consumedWatermark;
     }
-    /** Mark everything currently stored as consumed (boot, branch switch). */
+    /** Mark everything currently stored as consumed (the agent's creation, at
+     *  boot or later, and a tool boundary that injected messages into the live
+     *  stream). */
     markContextConsumed() {
         // Tolerates partial context-manager doubles (tests build Agents over
         // stubs): without a watermark nothing is ever treated as unread.
         this.consumedWatermark = this.pendingWatermark();
+        this.watermarkMarks++;
+    }
+    /**
+     * A finished compile's watermark, taken before it awaited. Within a branch
+     * the watermark only advances: if a mark was made while the compile ran,
+     * the compile's (older) one is applied only where it is later on that
+     * mark's branch, so a boundary's mark is never rolled back by a compile
+     * that started before it (a preview during a live turn).
+     */
+    applyCompileWatermark(watermark, marksBefore) {
+        const current = this.consumedWatermark;
+        if (this.watermarkMarks !== marksBefore && current
+            && (current.branch !== watermark.branch || current.sequence >= watermark.sequence))
+            return;
+        this.consumedWatermark = watermark;
+        this.watermarkMarks++;
     }
     /** The watermark a successful compile will establish (taken before, applied after). */
     pendingWatermark() {
@@ -498,29 +849,58 @@ 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 marksBefore = this.watermarkMarks;
+        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();
+            this.applyCompileWatermark(watermark, marksBefore);
         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 marksBefore = this.watermarkMarks;
+        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();
+            this.applyCompileWatermark(watermark, marksBefore);
         return result;
     }
     // ==========================================================================
@@ -577,15 +957,8 @@ export class Agent {
             return {
                 messages: this.toolResultGuard.prepareRequest(messages, true),
                 system: this.buildSystemPrompt(systemInjections),
-                config: {
-                    model: this.model,
-                    maxTokens: this.maxTokens,
-                    ...(this.temperature !== undefined && { temperature: this.temperature }),
-                    ...(this.thinking !== undefined && { thinking: this.thinking }),
-                },
                 tools: tools.length > 0 ? tools : undefined,
-                ...(this.providerParams && { providerParams: this.providerParams }),
-                assistantParticipant: this.name,
+                ...this.requestSettings(),
             };
         };
         const request = await assemble();
@@ -657,7 +1030,12 @@ export class Agent {
         this._state.completed.push(completed);
         // If all tools done, transition to ready
         if (this._state.pending.size === 0) {
-            this._state = { status: 'ready', toolResults: this._state.completed, stream: this._state.stream };
+            this._state = {
+                status: 'ready',
+                toolResults: this._state.completed,
+                stream: this._state.stream,
+                supportsInjectedMessages: this._state.supportsInjectedMessages,
+            };
         }
     }
     /**
@@ -671,12 +1049,18 @@ export class Agent {
      * Build the membrane-normalized request that WOULD be emitted for this
      * agent's next activation, given the supplied tools and injections.
      *
-     * 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.
+     * This is the single source of truth for a framework turn's request,
+     * shared by the real activation path (`startStreamWithInjections`) and
+     * debug/preview tooling (`Framework.previewActivation`). It does not call
+     * the membrane. The direct API (`runInferenceWithInjections`) assembles its
+     * own messages, system prompt and tools, and both take the agent's
+     * settings from `requestSettings()`.
+     * 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 +1088,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
@@ -751,15 +1140,28 @@ export class Agent {
         return {
             messages: this.toolResultGuard.prepareRequest(messages),
             system: this.buildSystemPrompt(systemInjections),
+            tools: availableTools.length > 0 ? availableTools : undefined,
+            ...this.requestSettings(),
+            ...(kvUnified ? { cacheMarkers: 'cm-owned' } : {}),
+        };
+    }
+    /**
+     * The request fields that come from this agent's own settings: its model
+     * config, prompt caching and cache TTL, prefill message, provider
+     * parameters and participant name. Every request the agent sends takes
+     * them from here, a framework turn's (buildActivationRequest) and the
+     * direct API's (runInferenceWithInjections), so a setting reaches both or
+     * neither.
+     */
+    requestSettings() {
+        return {
             config: {
                 model: this.model,
                 maxTokens: this.maxTokens,
                 ...(this.temperature !== undefined && { temperature: this.temperature }),
                 ...(this.thinking !== undefined && { thinking: this.thinking }),
             },
-            tools: availableTools.length > 0 ? availableTools : undefined,
             promptCaching: this.promptCaching,
-            ...(kvUnified ? { cacheMarkers: 'cm-owned' } : {}),
             cacheTtl: this.cacheTtl,
             ...(this.prefillUserMessage && { prefillUserMessage: this.prefillUserMessage }),
             ...(this.providerParams && { providerParams: this.providerParams }),
@@ -811,16 +1213,28 @@ export class Agent {
         // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
         this.failOpenKvSubmissions();
         this._streamId++;
+        // A pending cancel belongs to the stream that was live when cancelStream()
+        // ran. The stream driver collects it on that stream's terminal event, or
+        // at the loop's end when the iterator closed without one, while the
+        // stream still owns the agent. This clear is for the records no driver
+        // collects: a dropped turn's, whose stream no driver iterates; one whose
+        // stream's terminal came after another stream took the agent; or a
+        // cancel after the stream's complete event. A fresh stream must not
+        // inherit one and read its own later error as a deliberate stop.
+        this._pendingCancel = undefined;
         this._inferenceStartedAt = Date.now();
         this.lastStreamInputTokens = 0;
         // Reset the cache-inclusive counters too: a new stream must not inherit
         // 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).
@@ -898,9 +1312,10 @@ export class Agent {
     }
     /**
      * Transition to waiting_for_tools when stream yields tool calls.
-     * Called by framework's driveStream.
+     * Called by framework's driveStream, with what the stream declared about
+     * carrying injected messages with this round's results (see AgentState).
      */
-    enterWaitingForTools(calls, stream) {
+    enterWaitingForTools(calls, stream, supportsInjectedMessages) {
         const pending = new Map();
         for (const call of calls) {
             pending.set(call.id, {
@@ -910,7 +1325,7 @@ export class Agent {
                 startedAt: Date.now(),
             });
         }
-        this._state = { status: 'waiting_for_tools', pending, completed: [], stream };
+        this._state = { status: 'waiting_for_tools', pending, completed: [], stream, supportsInjectedMessages };
     }
     /**
      * Add an assistant response to context.
@@ -946,18 +1361,39 @@ export class Agent {
     setStreaming(stream) {
         this._state = { status: 'streaming', stream };
     }
+    /** The most recent cancelStream() of a live stream, until the stream
+     *  driver collects it on that stream's terminal event. Its presence is
+     *  the signal (a reasonless Stop is still a deliberate stop); its reason
+     *  is the caller's own word. Membrane reports every cancel() as reason
+     *  'user' — the call, not the actor — and a stream implementation may
+     *  report the cancel as `error` with no reason at all, so this record is
+     *  the only provenance a host-side cancel has. */
+    _pendingCancel;
     /**
-     * Cancel any active stream and reset to idle.
+     * Cancel the stream this agent's state holds (streaming, waiting on its
+     * tools, or ready at a tool boundary with every result in), and reset to
+     * idle. `reason` is provenance for the framework's inference:aborted trace
+     * and marker metadata (e.g. 'zombie_reclaim', 'subagent_cancel'); it never
+     * reaches the provider.
      */
-    cancelStream() {
-        if (this._state.status === 'streaming') {
-            this._state.stream.cancel();
-        }
-        else if (this._state.status === 'waiting_for_tools' && this._state.stream) {
+    cancelStream(reason) {
+        if ('stream' in this._state && this._state.stream) {
+            this._pendingCancel = { reason };
             this._state.stream.cancel();
         }
         this._state = { status: 'idle' };
     }
+    /** Collect (and clear) the cancel that ended the current stream, if this
+     *  side issued one. The stream driver calls it once, while the stream
+     *  still owns the agent, at the stream's terminal event (`aborted`
+     *  normally, `error` for implementations that report cancel() that way)
+     *  or at the loop's end when the stream closed without one. A record no
+     *  driver collects is cleared when the agent's next stream starts. */
+    takeCancel() {
+        const c = this._pendingCancel;
+        this._pendingCancel = undefined;
+        return c;
+    }
     /**
      * Check if agent has pending tool calls.
      */
@@ -986,18 +1422,18 @@ export class Agent {
         return this.contextManager;
     }
     /**
-     * Build the effective system prompt, appending any system-position injections.
+     * Build the effective system prompt, appending any system-position
+     * injections, their blocks joined by line breaks. The system prompt is
+     * text, so a block of another type, such as an image a server or module
+     * injected there, can't go in it: a line in its place says so. The hook
+     * orchestrator tells a server's operator once per server and namespace,
+     * and the module registry tells a module's once per module and namespace.
      */
     buildSystemPrompt(systemInjections) {
         if (systemInjections.length === 0) {
             return this.systemPrompt;
         }
-        const injectedText = systemInjections
-            .filter((block) => block.type === 'text')
-            .map((block) => block.text);
-        if (injectedText.length === 0) {
-            return this.systemPrompt;
-        }
+        const injectedText = systemInjections.map((block) => block.type === 'text' ? block.text : `[${block.type} block not shown: the system prompt carries text only.]`);
         return this.systemPrompt + '\n' + injectedText.join('\n');
     }
     abortInference(reason) {
@@ -1006,10 +1442,9 @@ export class Agent {
             this._state.abortController.abort(reason);
             return { aborted: true, durationMs };
         }
-        if (this._state.status === 'streaming' ||
-            (this._state.status === 'waiting_for_tools' && this._state.stream)) {
+        if ('stream' in this._state && this._state.stream) {
             const durationMs = Date.now() - this._inferenceStartedAt;
-            this.cancelStream();
+            this.cancelStream(reason);
             return { aborted: true, durationMs };
         }
         return false;