@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/agent.ts

@@ -3,6 +3,7 @@ import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import type { CacheWireReceipt, KvUnifiedRequestHooks } from './kv-unified-wire.js';
 import { ToolResultGuard } from './tool-result-guard.js';
+import { assertBooleanSetting, holdsSettings } from './config-checks.js';
 import {
   indexSilentTickRows,
   separateSilentHeartbeatTicks,
@@ -20,6 +21,9 @@ import {
 export interface ActivationRequestOptions {
   /** The silent heartbeat tick this request answers, if any. */
   silentHeartbeat?: SilentHeartbeatTick;
+  /** A request that will never be sent (a preview): compile it as a dry
+   *  run (see `compileWithInjections` for what that leaves alone). */
+  dryRun?: boolean;
 }
 
 export interface StartStreamResult {
@@ -72,6 +76,53 @@ const DEFAULT_CONTEXT_BUDGET_TOKENS = 100_000;
 const DEFAULT_TRANSITION_PACE_TOKENS = 16_000;
 const DEFAULT_SAME_ROUND_THINK_TEXT_POLICY: SameRoundThinkTextPolicy = '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: AgentConfig): void {
+  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.
  */
@@ -120,15 +171,38 @@ export class Agent {
    * closure) so the next activation can close whatever its predecessor left
    * open — see failOpenKvSubmissions. */
   private kvOpenQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> | null = 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: number;
   /** Provider hard context cap (see AgentConfig.physicalWindowTokens). */
   readonly physicalWindowTokens?: number;
@@ -141,7 +215,52 @@ export class Agent {
   private readonly configuredTransitionPaceTokens?: number;
   private readonly configuredSameRoundThinkTextPolicy?: SameRoundThinkTextPolicy;
   private contextBudgetTargetTokens?: number;
-  private runtimeSettingsOverrides: AgentRuntimeSettingsOverrides = {};
+  private runtimeSettingsOverrides: AgentRuntimeSettingsPatch = {};
+  /**
+   * 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.
+   */
+  private 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.
+   */
+  private descentEpoch = 0;
+  /** The live budget the last compile planned at, whether it fit, and the live budget's epoch then. */
+  private lastCompiledBudget?: { budget: number; fit: boolean; epoch: number };
+  /** Counts compiles at the live budget as they start. */
+  private compilesStarted = 0;
+  /** The start numbers of the compiles at the live budget still running. */
+  private readonly compilesRunning = new Set<number>();
+  /**
+   * 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.
+   */
+  private readonly latestEndedStart = new Map<number, number>();
+  /** The last outcome the listener recorded; a failed record is told again, and so is any after a change. */
+  private recordedCompiledBudget?: { budget: number; fit: boolean; epoch: number };
+  /**
+   * 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.
+   */
+  private restoredAtOnce = false;
+  /** Told when that changes (the framework records it beside the persisted budget). */
+  private compiledBudgetListener?: (budget: number, fit: boolean) => boolean;
   private contextManager: ContextManager;
   private membrane: Membrane;
 
@@ -150,6 +269,7 @@ export class Agent {
     contextManager: ContextManager,
     membrane: Membrane
   ) {
+    assertAgentSwitches(config);
     this.name = config.name;
     this.model = config.model;
     this.systemPrompt = config.systemPrompt;
@@ -159,11 +279,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;
@@ -280,10 +400,16 @@ export class Agent {
   getRuntimeSettings(): AgentRuntimeSettingsSnapshot {
     const hot = this.getHotContextSettings();
     return {
+      // 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 }
@@ -307,6 +433,179 @@ export class Agent {
     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: ((budget: number, fit: boolean) => boolean) | undefined): void {
+    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(): number | undefined {
+    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.
+   */
+  private setContextBudget(budget: number | undefined, target: number | undefined, armed = false): void {
+    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.
+   */
+  private claimLatestAt(budget: number, started: number): boolean {
+    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.
+   */
+  private noteCompiledBudget(budget: number, fit: boolean, epoch: number): void {
+    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. */
+  private async compileAtLiveBudget(compile: () => Promise<CompileResult>): Promise<CompileResult> {
+    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. */
+  private async compileAtLiveBudgetNoting(compile: () => Promise<CompileResult>, started: number): Promise<CompileResult> {
+    // 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: CompileResult;
+    try {
+      result = await compile();
+    } catch (error) {
+      if ((error as { name?: unknown } | null)?.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: string;
+      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?: AgentRuntimeSettingsPatch): {
+    liveBudgetTokens: number;
+    path: 'immediate' | 'paced' | 'none';
+    transition: 'stable' | 'converging';
+  } {
+    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(): boolean {
+    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
@@ -323,11 +622,17 @@ 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?: AgentRuntimeSettingsPatch): {
     effectiveBudgetTokens: number;
@@ -343,34 +648,33 @@ export class Agent {
       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: Record<string, unknown> = {};
     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,
     };
@@ -397,6 +701,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: {
       tailTokens?: number;
       transitionPaceTokens?: number | null;
@@ -428,21 +734,24 @@ 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 as Record<string, unknown>)[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'] as const) {
+      if (patch[key] !== undefined) this.runtimeSettingsOverrides[key] = patch[key];
     }
     if (patch.sameRoundThinkTextPolicy !== undefined) {
       this.runtimeSettingsOverrides.sameRoundThinkTextPolicy = patch.sameRoundThinkTextPolicy;
@@ -454,6 +763,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: {
       tailTokens?: number;
       transitionPaceTokens?: number | null;
@@ -471,6 +782,7 @@ export class Agent {
           hotPatch.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
         }
         nextContextTarget = configured;
+        armed = true;
       } else {
         nextContextBudget = this.configuredContextBudgetTokens;
         nextContextTarget = undefined;
@@ -487,9 +799,11 @@ export class Agent {
           : this.configuredTransitionPaceTokens ?? null;
     }
     if (Object.keys(hotPatch).length > 0) this.updateHotContextSettings(hotPatch);
-    this.contextBudgetTokens = nextContextBudget;
-    this.contextBudgetTargetTokens = nextContextTarget;
-    if (reset.has('contextBudgetTokens')) delete this.runtimeSettingsOverrides.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')) {
       delete this.runtimeSettingsOverrides.transitionPaceTokens;
@@ -503,7 +817,7 @@ export class Agent {
   cancelRuntimeSettingsTransition(): AgentRuntimeSettingsSnapshot {
     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;
@@ -514,11 +828,56 @@ export class Agent {
     return this.getRuntimeSettings();
   }
 
-  restoreRuntimeSettings(overrides: AgentRuntimeSettingsOverrides): AgentRuntimeSettingsSnapshot {
-    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: AgentRuntimeSettingsPatch,
+    opts?: { provenBudget?: number },
+  ): AgentRuntimeSettingsSnapshot {
+    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: Pick<AgentRuntimeSettingsPatch, 'contextBudgetTokens' | 'tailTokens' | 'transitionPaceTokens'>): void {
+    for (const key of ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens'] as const) {
+      if (settings[key] !== undefined) this.runtimeSettingsOverrides[key] = settings[key];
+    }
   }
 
   private validateRuntimeSettingsPatch(patch: AgentRuntimeSettingsPatch): void {
+    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: AgentRuntimeSettingsPatch): void {
     if (Object.keys(patch).length === 0) throw new Error('At least one setting is required');
     if (patch.contextBudgetTokens !== undefined) {
       if (!Number.isSafeInteger(patch.contextBudgetTokens) || patch.contextBudgetTokens <= this.maxTokens) {
@@ -538,37 +897,56 @@ 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');
-    }
   }
 
-  private settleRuntimeSettingsTransition(): void {
-    if (this.contextBudgetTargetTokens === undefined) return;
+  /** Settle a converging budget once the window is prepared; true if it settled. */
+  private settleRuntimeSettingsTransition(): boolean {
+    if (this.contextBudgetTargetTokens === undefined) return false;
     const hot = this.getHotContextSettings();
-    if (!hot?.prepared) return;
-    this.contextBudgetTokens = this.contextBudgetTargetTokens;
-    this.contextBudgetTargetTokens = undefined;
+    if (!hot?.prepared) 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.
    */
   private consumedWatermark: { branch: string; sequence: number } | null = 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). */
+  private watermarkMarks = 0;
 
   getConsumedWatermark(): { branch: string; sequence: number } | null {
     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(): void {
     // 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).
+   */
+  private applyCompileWatermark(watermark: { branch: string; sequence: number }, marksBefore: number): void {
+    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). */
@@ -591,32 +969,61 @@ export class Agent {
     }
   }
 
+  /** 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?: TokenBudget): Promise<CompileResult> {
     // 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));
-    if (watermark) this.consumedWatermark = watermark;
-    if (!budget) this.settleRuntimeSettingsTransition();
+    const marksBefore = this.watermarkMarks;
+    const compile = () => this.contextManager.compile(this.compileBudget(budget));
+    const result = budget ? await compile() : await this.compileAtLiveBudget(compile);
+    if (watermark) 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?: TokenBudget,
     injections?: ContextInjection[],
-    opts?: { kvUnifiedImmutablePrefixHash?: string },
+    opts?: { kvUnifiedImmutablePrefixHash?: string; dryRun?: boolean },
   ): Promise<CompileResult> {
-    const watermark = this.pendingWatermark();
-    const result = await this.contextManager.compile(
-      this.compileBudget(budget), injections, opts as never,
-    );
-    if (watermark) this.consumedWatermark = watermark;
-    if (!budget) this.settleRuntimeSettingsTransition();
+    // 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 as never);
+    const result = budget || opts?.dryRun ? await compile() : await this.compileAtLiveBudget(compile);
+    if (watermark) this.applyCompileWatermark(watermark, marksBefore);
     return result;
   }
 
@@ -692,15 +1099,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();
@@ -780,7 +1180,12 @@ export class Agent {
 
     // 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,
+      };
     }
   }
 
@@ -799,12 +1204,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
@@ -845,7 +1256,12 @@ export class Agent {
     let { messages, systemInjections } = await this.compileWithInjections(
       budget,
       injections,
-      immutablePrefixHash ? { kvUnifiedImmutablePrefixHash: immutablePrefixHash } : undefined,
+      immutablePrefixHash || options.dryRun
+        ? {
+            ...(immutablePrefixHash ? { kvUnifiedImmutablePrefixHash: immutablePrefixHash } : {}),
+            ...(options.dryRun ? { dryRun: true } : {}),
+          }
+        : undefined,
     );
 
     // Sanitize: strip empty/whitespace text blocks and drop messages left with
@@ -897,15 +1313,30 @@ 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' as const } : {}),
+    };
+  }
+
+  /**
+   * 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.
+   */
+  private requestSettings(): Pick<NormalizedRequest,
+    'config' | 'promptCaching' | 'cacheTtl' | 'prefillUserMessage' | 'providerParams' | 'assistantParticipant'> {
+    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' as const } : {}),
       cacheTtl: this.cacheTtl,
       ...(this.prefillUserMessage && { prefillUserMessage: this.prefillUserMessage }),
       ...(this.providerParams && { providerParams: this.providerParams }),
@@ -966,16 +1397,28 @@ export class Agent {
     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
@@ -1063,9 +1506,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: ToolCall[], stream: YieldingStream): void {
+  enterWaitingForTools(calls: ToolCall[], stream: YieldingStream, supportsInjectedMessages?: boolean): void {
     const pending = new Map<ToolCallId, PendingToolCall>();
     for (const call of calls) {
       pending.set(call.id, {
@@ -1075,7 +1519,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 };
   }
 
   /**
@@ -1118,18 +1562,42 @@ export class Agent {
     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. */
+  private _pendingCancel: { reason?: string } | undefined;
+
   /**
-   * 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(): void {
-    if (this._state.status === 'streaming') {
-      this._state.stream.cancel();
-    } else if (this._state.status === 'waiting_for_tools' && this._state.stream) {
+  cancelStream(reason?: string): void {
+    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(): { reason?: string } | undefined {
+    const c = this._pendingCancel;
+    this._pendingCancel = undefined;
+    return c;
+  }
+
   /**
    * Check if agent has pending tool calls.
    */
@@ -1162,20 +1630,20 @@ export class Agent {
   }
 
   /**
-   * 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.
    */
   private buildSystemPrompt(systemInjections: ContentBlock[]): string {
     if (systemInjections.length === 0) {
       return this.systemPrompt;
     }
 
-    const injectedText = systemInjections
-      .filter((block): block is ContentBlock & { type: 'text' } => 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');
   }
@@ -1187,10 +1655,9 @@ export class Agent {
       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 };
     }