@genesislcap/ai-assistant 15.23.0 → 15.23.1-FUI-2603.9

package/dist/ai-assistant.d.ts

@@ -645,6 +645,39 @@ export declare interface AiDriver extends EventTarget {
      * retain the active config implement it.
      */
     getActiveAgent?(): AgentConfig | undefined;
+    /**
+     * Headroom the next turn could need, and which agent set that requirement
+     * (GENC-1582). `undefined` when no agent the turn could land on declares a
+     * `contextReserve`, which leaves the ambient default in force.
+     *
+     * The host cannot work this out for itself: it depends on the user pin, the
+     * flow-owner lock and the classifier's candidate set, none of which it can see.
+     * Reading the ACTIVE agent instead — which is what the gate did first — asks the
+     * wrong question, because the agent that last ran is not the agent about to run.
+     * Under automatic routing they are routinely different, and the turn that hands
+     * over is exactly the one that needs the room.
+     *
+     * Optional — only drivers that route implement it.
+     */
+    getContextReserve?(): ContextReserveResolution | undefined;
+    /**
+     * Token cost of the last request's preamble — system prompt, tool definitions
+     * and framed tail (GENC-1582). `undefined` before the first call of a turn.
+     *
+     * A live getter rather than a field stamped on each message, deliberately: every
+     * consumer wants the CURRENT preamble, never its history, and a message field
+     * would mean a type change in `@genesislcap/foundation-ai` plus churn in every
+     * persisted session for a value nobody reads twice.
+     *
+     * It exists because the preamble cannot be derived reliably. Inferring it as
+     * "first measured prompt minus the messages it covered" is accurate once and then
+     * goes stale, since each agent brings its own prompt and tool surface — and every
+     * attempt to compensate downstream ended up comparing stored characters against
+     * wire tokens. The driver is the only place that knows what it just sent.
+     *
+     * Optional — only drivers that build requests implement it.
+     */
+    getPreambleTokens?(): number | undefined;
     /**
      * Set the mid-loop context guard (GENC-1567). `undefined` disables it.
      *
@@ -1175,13 +1208,15 @@ declare interface BaseAgentConfig {
      * room it needs so that it does not have to be. An agent whose flow runs a long
      * tool loop, or returns large payloads, needs more than the global default.
      *
-     * **When it takes effect.** The reserve is read from the agent that is already
-     * ACTIVE, so it governs the gate from that agent's next send onwards — one turn
-     * later than a true pre-flight. It is deliberately not enforced at flow entry:
-     * `flow-owner-changed` fires while the driver is already routing the turn, so
-     * gating there would mean aborting a turn in flight. An agent that activates
-     * mid-turn therefore gets its first turn under the global reserve; the mid-loop
-     * context guard is what stops that turn running away.
+     * **When it takes effect.** Before the send, as a real pre-flight (GENC-1582).
+     * The driver resolves it against how routing is currently constrained — the
+     * pinned or flow-owning agent when there is one, otherwise the largest reserve
+     * among the agents the classifier could route to — so a turn is refused before
+     * it can start rather than after. This used to read the agent that was already
+     * ACTIVE, which is a different agent from the one about to run whenever the
+     * orchestrator is doing its job, and the handover turn is exactly the one that
+     * needs the room. The mid-loop context guard remains the backstop for a turn
+     * that outgrows what it reserved.
      *
      * **Set this from measurement, not from a guess.** Per-turn `inputTokens` is
      * recorded for every call, so a single real run of the flow tells you its peak
@@ -1278,6 +1313,11 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      */
     private interactionContexts;
     private systemPrompt?;
+    /**
+     * Preamble cost of the most recent request, set at the request-build site.
+     * Read through {@link ChatDriver.getPreambleTokens}.
+     */
+    private lastPreambleTokens?;
     /**
      * Resolved tool definitions visible to the LLM. Folds mutate this in place
      * (push/pop on open/close). When `toolDefinitionsFactory` is set, this is
@@ -1950,6 +1990,8 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * nothing worth compacting or the default provider cannot summarize.
      */
     compact(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
+    /** {@inheritDoc AiDriver.getPreambleTokens} */
+    getPreambleTokens(): number | undefined;
     isBusy(): boolean;
     /**
      * Wire a parent driver as the host for this driver's interactions. When set,
@@ -2240,6 +2282,12 @@ declare interface CompactionPlanOptions {
     tailTokenBudget?: number;
     /** Minimum reclaim for the plan to be considered worth running. */
     minReclaimTokens?: number;
+    /**
+     * Measured preamble cost, from `AiDriver.getPreambleTokens()` (GENC-1582).
+     * Without it the projection sizes the post-compaction context as if the system
+     * prompt and tool definitions were free, so it lands above the line it aimed at.
+     */
+    preambleTokens?: number;
 }
 
 /** What a compaction at a given cut would cost and reclaim. */
@@ -2310,21 +2358,87 @@ export declare interface ContextGuardPolicy {
 }
 
 /**
- * Context headroom an agent reserves for itself, in tokens.
+ * Context headroom an agent reserves for itself (GENC-1582).
+ *
+ * Two figures, because a turn has two costs and only one of them is permanent.
+ *
+ * @beta
+ */
+export declare interface ContextReserve {
+    /**
+     * Tokens that must be free before one of this agent's turns may START — the
+     * agent's PEAK growth, not its lasting cost.
+     *
+     * The peak is the binding figure even for an agent that sheds most of it again:
+     * `condenseWhen` stubs a spent payload at the end of the turn, so the room has
+     * to be there while the turn is running, before any of that fires.
+     */
+    tokens: number;
+    /**
+     * Extra tokens ABOVE {@link ContextReserve.tokens} at which the warning
+     * appears. Omit to fall back to `chatConfig.context.warnMultiplier`.
+     *
+     * The figure that belongs here is what one of this agent's turns costs
+     * PERMANENTLY — its growth measured after condensation, not at its peak. That
+     * makes the warning land exactly two turns before the block: at the warning
+     * line there is room for a full turn plus the residue it leaves, which is one
+     * turn, and then room for one more.
+     *
+     * It exists because the multiplier cannot express that. `warnMultiplier` scales
+     * the whole reserve, so an agent that peaks at 400k and keeps 30k gets a warning
+     * 800k below the window — a line every one of its turns crosses transiently and
+     * then clears, which is noise rather than a signal.
+     */
+    warnAheadTokens?: number;
+}
+
+/**
+ * Context headroom an agent reserves for itself: a token count, or a
+ * {@link ContextReserve} when the agent also wants to say where the warning goes.
  *
- * A plain number, unlike the value-or-resolver shape `provider` / `temperature` /
- * `resumable` use. The resolver form was drafted for it and removed before
- * release: the gate is recomputed from a synchronous getter with no turn context
- * to resolve against, so no path could ever have invoked one. Accepting a
- * type-correct option that is guaranteed to do nothing is worse than not
- * offering it — a warning after the fact still leaves the configuration inert.
+ * NOT the value-or-resolver shape `provider` / `temperature` / `resumable` use.
+ * The resolver form was drafted and removed before release: the gate is recomputed
+ * from a synchronous getter with no turn context to resolve against, so no path
+ * could ever have invoked one. Accepting a type-correct option guaranteed to do
+ * nothing is worse than not offering it.
  *
- * It can widen to a resolver later without breaking a caller, since every
- * existing `number` stays valid.
+ * The object arm was added the way the plain form's docblock anticipated —
+ * additively, so every existing `number` stays valid and means what it did.
  *
  * @beta
  */
-export declare type ContextReserveInput = number;
+export declare type ContextReserveInput = number | ContextReserve;
+
+/**
+ * How much context headroom the next turn needs, and where that figure came from
+ * (GENC-1582).
+ *
+ * @internal
+ */
+declare interface ContextReserveResolution {
+    /** Tokens to keep free for one turn — the winning agent's peak growth. */
+    tokens: number;
+    /**
+     * Extra tokens above {@link ContextReserveResolution.tokens} at which the
+     * warning appears, when the winning agent declared one. Travels WITH the winner
+     * rather than being resolved separately: the two figures describe the same
+     * agent's turn, and pairing a lean agent's warning with a hungry agent's block
+     * would put the warning on the wrong side of it.
+     */
+    warnAheadTokens?: number;
+    /** The agent whose `contextReserve` this is. */
+    agentName: string;
+    /**
+     * Why this agent's reserve governs — which is what lets a blocked composer say
+     * something TRUE about an agent the user has not invoked yet.
+     *
+     * `locked`: a user pin or a flow-owner lock means the next turn can only go to
+     * this agent, so its reserve is the whole requirement. `reachable-max`: routing
+     * is automatic, so the turn could land on any agent the classifier can pick, and
+     * the hungriest of them is the one that has to fit.
+     */
+    basis: 'locked' | 'reachable-max';
+}
 
 /** A model used during a recorded cost session. */
 export declare interface CostSessionModelEntry {
@@ -2734,12 +2848,66 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * redux actions re-renders without this; a store *swap* needs it.)
      */
     private _sessionRef?;
+    /**
+     * {@link FoundationAiAssistant.contextTokens} as of the last moment no turn was
+     * running — the figure {@link FoundationAiAssistant.contextGate} is judged
+     * against (GENC-1582).
+     *
+     * **Why the gate reads a held figure and the gauge does not.** They answer
+     * different questions. The gauge is a meter: "how much context is in play right
+     * now", and a build that momentarily fills 900k of a 1M window should say so.
+     * The gate answers "may the next turn START", which is only meaningful when no
+     * turn is running — the composer is disabled by `busy` throughout one anyway, so
+     * a warning raised mid-turn is unactionable by construction.
+     *
+     * Reading the live figure meant the pill went amber part-way through every large
+     * build and cleared itself at the end, because a `condenseWhen` agent's context
+     * peaks mid-turn and is shed before the turn finishes. A signal that fires and
+     * withdraws on its own each time teaches people to ignore it.
+     *
+     * **Held, not latched.** The distinction matters, because `contextGate` is
+     * documented as derived-never-latched and the reason is a real dead end: a figure
+     * pinned to a conversation that has since shrunk blocks the user out of the very
+     * actions that would fix it. This holds only for the duration of a turn and is
+     * refreshed the moment one settles, so no shrink can outlive it — a compaction
+     * runs under `compacting` rather than `busy` and therefore updates it as it goes,
+     * and Clear drops it outright. What it costs is one turn of lag: a turn that
+     * balloons the resting size does not warn until it ends, which is the same trade
+     * the flow-owner soften already makes deliberately.
+     *
+     * Unset falls back to the live figure, which is correct wherever there is no held
+     * value yet — first paint, and a remount, both of which happen at rest.
+     */
+    private _gateContextTokens?;
     get messages(): ChatMessage[];
     set messages(value: ChatMessage[]);
     get state(): AiAssistantState;
     set state(value: AiAssistantState);
     /** Whether a state value counts as "busy" — a turn is active. */
     private isBusyState;
+    /**
+     * Re-arm {@link FoundationAiAssistant.contextGate} against the size the turn
+     * just left behind (GENC-1582).
+     *
+     * The final call of a turn is made AFTER `agentEnd` condensation fires, so by
+     * the time a turn settles `contextTokens` is the resting figure rather than the
+     * mid-turn peak — which is the number the reserve's thresholds are drawn
+     * against.
+     *
+     * **Called from BOTH settle paths, and it has to be.** A turn does not end
+     * through the `state` setter: `send()`'s `finally` writes `setState('idle')`
+     * straight to the captured session ref, because the element may have
+     * disconnected mid-turn, and that block then replicates the parts of the
+     * setter's settle that matter. Arming the gate inline in the setter therefore
+     * armed it on the one path a real turn never takes — the gate silently kept
+     * falling back to the live figure and the hold did nothing at all. Found by
+     * driving a real UI Builder turn and reading `_gateContextTokens`, which was
+     * `undefined` from start to finish; no unit test noticed, because the test
+     * harness sets `state` through the property.
+     *
+     * One method rather than two assignments so the two paths cannot drift again.
+     */
+    private rearmContextGate;
     /**
      * True while a turn is active — `loading` or `cancelling` (a stop was
      * requested but the turn is still winding down). The single "is a turn
@@ -4053,11 +4221,11 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * Context-headroom thresholds for the active model (GENC-1567) — the warning
      * and block lines, plus the tail budget compaction aims at.
      *
-     * The agent's own `contextReserve` is deliberately NOT folded in here. This is
-     * the AMBIENT budget, which protects any turn from any agent; a per-agent
-     * reserve is an additional, larger requirement checked when that agent takes
-     * ownership of a flow, where there is a turn context to resolve its function
-     * form against.
+     * The per-agent `contextReserve` IS folded in, via the driver (GENC-1582). It
+     * used to be described here as a separate, later check made when an agent took
+     * ownership of a flow — but there is no such check, and by flow entry the send
+     * has already been allowed. Resolving it here, before the send, is what makes it
+     * a gate rather than a label.
      *
      * Overhead is read off `messages` (the Redux mirror) rather than the driver's
      * own history, which the compaction plan uses. That is safe rather than sloppy:
@@ -4067,22 +4235,26 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get contextBudget(): ResolvedContextBudget;
     /**
-     * The active agent's declared `contextReserve`, when it is a plain number.
+     * Headroom the next turn needs, resolved against how routing is currently
+     * constrained (GENC-1582), and which agent set it.
+     *
+     * The driver owns the answer because the driver owns routing: whether a pin or a
+     * flow-owner lock is in force, which agents the classifier can reach, and which
+     * one is active. This used to read `getActiveAgent()?.contextReserve` — the agent
+     * that LAST ran — which is a different agent from the one about to run whenever
+     * the orchestrator is doing its job, and the handover turn is precisely the one
+     * that needs the room.
      *
-     * Read off the LIVE active agent rather than checked at flow entry, which is
-     * where the design first put it. `flow-owner-changed` turned out to fire while
-     * the driver is already routing the turn — after the send was allowed — so it
-     * is not a pre-flight hook, and gating there would mean aborting a turn in
-     * flight. Reading the active agent instead means a hungry agent's reserve
-     * governs the gate from its next send onwards: one turn later than a true
-     * pre-flight, but synchronous, and it never has to interrupt anything.
+     * Falls back to the active agent for a host-supplied driver that does not
+     * implement the resolution, so an existing single-agent driver keeps the old
+     * behaviour rather than silently losing its reserve.
      *
      * `contextReserve` is a plain number by design — see `ContextReserveInput` for
      * why a resolver form was dropped rather than accepted and ignored.
      *
      * @internal
      */
-    private get activeAgentReserveTokens();
+    private get contextReserve();
     /**
      * What compacting right now would reclaim, or `null` when it would not be
      * worth it (GENC-1567). Sized against {@link FoundationAiAssistant.contextBudget},
@@ -4122,6 +4294,36 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * and gating on the way out is the lesser harm; the headroom reserve exists so
      * this is rare rather than routine.
      */
+    /**
+     * WHY the composer is blocked, when it is (GENC-1582). `undefined` unless
+     * {@link FoundationAiAssistant.contextGate} is `'blocked'`.
+     *
+     * A cause rather than a fourth gate level: the severity is identical — sends are
+     * refused either way — and every consumer switches on the three levels. What
+     * differs is what the user can do about it, which is worth splitting because the
+     * two answers have no remedy in common.
+     *
+     * - `'transcript'` — the conversation has grown into the reserve. Compacting or
+     *   clearing helps, and the copy says so.
+     * - `'model'` — the active agent's reserve meets or exceeds the whole window, so
+     *   `blockAt` is 0 and EVERY message is refused, including the first of an empty
+     *   chat. Neither compacting nor clearing can help: the constraint is the model,
+     *   not the transcript. Before this existed the user was told to clear the chat,
+     *   did, and hit the identical block with no way to understand why.
+     *
+     * Keyed off `blockAt === 0`, deliberately NOT off whether a compaction plan
+     * exists. A null plan has two unrelated causes — nothing left worth summarizing,
+     * versus a window that cannot host the agent at all — and conflating them is what
+     * produced the misleading copy.
+     *
+     * Note the block itself is correct in both cases and must stay: an agent that
+     * measurably cannot complete a turn in this window would otherwise start one and
+     * die mid-loop on a provider context error, with partial writes and no clean
+     * exit. Refusing up front is the better failure.
+     *
+     * @internal
+     */
+    get contextBlockCause(): 'transcript' | 'model' | undefined;
     get contextGate(): 'ok' | 'warn' | 'blocked';
     /**
      * What the composer notice says about the context gate.
@@ -5008,6 +5210,8 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     compact(options?: CompactionPlanOptions): Promise<ChatMessage | null>;
     /** {@inheritDoc AiDriver.canCompact} */
     canCompact(options?: CompactionPlanOptions): boolean;
+    /** {@inheritDoc AiDriver.getPreambleTokens} */
+    getPreambleTokens(): number | undefined;
     /** {@inheritDoc AiDriver.getCompactionPlan} */
     getCompactionPlan(options?: CompactionPlanOptions): CompactionProjection | null;
     /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
@@ -5020,6 +5224,12 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
     /** {@inheritDoc AiDriver.primeRestoredAgentState} */
     primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    /**
+     * {@inheritDoc AiDriver.getContextReserve}
+     *
+     * Two cases, because routing has two modes and they need opposite answers.
+     */
+    getContextReserve(): ContextReserveResolution | undefined;
     /** {@inheritDoc AiDriver.getActiveAgent} */
     getActiveAgent(): AgentConfig | undefined;
     private applyAgent;
@@ -5745,6 +5955,21 @@ export declare interface StatefulAgentInit<S> {
      * (fail-safe — never drop a resumable chat on a predicate bug).
      */
     resumable?: (ctx: StatefulAgentPersistenceContext<S>) => boolean | Promise<boolean>;
+    /**
+     * Tokens of context headroom to keep free for one of this agent's turns —
+     * see `AgentConfig.contextReserve`, which this is passed straight through to.
+     *
+     * The third member of the flow-safety group with {@link StatefulAgentInit.resumable}
+     * and {@link StatefulAgentInit.notResumableMessage}, and the one that was missing
+     * (GENC-1582): a stateful flow is the case the reserve was designed for — it is
+     * what runs the long tool loop — and yet the helper for building one could not
+     * express it. Both agents that needed it in the field are built here.
+     *
+     * Set it from measurement. Per-turn `inputTokens` is recorded for every call, so
+     * one real run of the flow gives you its peak growth; leaving it unset inherits
+     * the global default, which is the right starting position.
+     */
+    contextReserve?: ContextReserveInput;
     /**
      * Message shown on return when {@link StatefulAgentInit.resumable} returned
      * `false`. Falls back to a built-in default when omitted.

package/dist/chat-driver.cjs

@@ -3858,6 +3858,21 @@ function createInteractionContext(interactionId) {
 var APPROX_CHARS_PER_TOKEN = 4;
 var IMAGE_TOKEN_ESTIMATE = 1600;
 var PER_MESSAGE_FRAMING_TOKENS = 4;
+var PREAMBLE_PROSE_CHARS_PER_TOKEN = 4;
+var PREAMBLE_JSON_CHARS_PER_TOKEN = 3;
+var PER_TOOL_FRAMING_TOKENS = 8;
+function estimatePreambleTokens(input) {
+  const prose = (input.systemPrompt?.length ?? 0) + (input.tailContext?.length ?? 0);
+  let json = 0;
+  for (const def of input.toolDefinitions ?? []) {
+    try {
+      json += JSON.stringify(def).length;
+    } catch {
+      json += def.name?.length ?? 0;
+    }
+  }
+  return Math.ceil(prose / PREAMBLE_PROSE_CHARS_PER_TOKEN) + Math.ceil(json / PREAMBLE_JSON_CHARS_PER_TOKEN) + (input.toolDefinitions?.length ?? 0) * PER_TOOL_FRAMING_TOKENS;
+}
 var COMPACTION_SUMMARY_TOKEN_ESTIMATE = 1200;
 function reachesProvider(m) {
   if (m.role === "system-event" || m.role === "synthetic-user") return false;
@@ -3902,66 +3917,66 @@ function usableAnchor(m, compactedAt) {
 function firstAnchor(history, compactedAt) {
   return history.findIndex((m) => usableAnchor(m, compactedAt));
 }
-function estimateMessageTokens(history) {
-  const estimates = history.map(baselineTokens);
-  const compactedAt = compactedAtOf(history);
-  const anchors = [];
-  history.forEach((m, i) => {
-    if (usableAnchor(m, compactedAt)) anchors.push(i);
-  });
-  for (let a = 0; a < anchors.length - 1; a += 1) {
-    const from = anchors[a];
-    const to = anchors[a + 1];
-    const measured = history[to].inputTokens - history[from].inputTokens;
-    if (measured <= 0) continue;
-    let baseline = 0;
-    for (let i = from; i < to; i += 1) baseline += estimates[i];
-    if (baseline <= 0) {
-      estimates[from] = measured;
-      continue;
-    }
-    const scale = measured / baseline;
-    let assigned = 0;
-    for (let i = from; i < to - 1; i += 1) {
-      estimates[i] = Math.round(estimates[i] * scale);
-      assigned += estimates[i];
-    }
-    estimates[to - 1] = measured - assigned;
+function lastAnchor(history, compactedAt) {
+  for (let i = history.length - 1; i >= 0; i -= 1) {
+    if (usableAnchor(history[i], compactedAt)) return i;
   }
-  return estimates;
+  return -1;
 }
-function estimateSystemOverhead(history) {
-  const first = firstAnchor(history, compactedAtOf(history));
-  if (first < 0) return 0;
-  const estimates = estimateMessageTokens(history);
-  let messages = 0;
-  for (let i = 0; i < first; i += 1) messages += estimates[i];
-  return Math.max(0, history[first].inputTokens - messages);
-}
-function estimateContextTokens(history) {
-  const estimates = estimateMessageTokens(history);
-  let total = estimateSystemOverhead(history);
-  for (const t of estimates) total += t;
-  return total;
-}
-function estimateRequestTokens(storedHistory, requestHistory) {
-  const overhead = estimateSystemOverhead(storedHistory);
-  const calibratedMessages = Math.max(0, estimateContextTokens(storedHistory) - overhead);
-  let storedBaseline = 0;
-  for (const m of storedHistory) storedBaseline += baselineTokens(m);
+function calibrate(history, preambleTokens) {
+  const baselines = history.map(baselineTokens);
+  let baselineTotal = 0;
+  for (const b of baselines) baselineTotal += b;
+  const compactedAt = compactedAtOf(history);
+  const first = firstAnchor(history, compactedAt);
+  const last = lastAnchor(history, compactedAt);
+  if (first < 0 || last < 0) {
+    const measured = Math.max(0, preambleTokens ?? 0);
+    return {
+      overhead: measured,
+      total: baselineTotal + measured,
+      estimates: baselines,
+      scale: 1
+    };
+  }
+  let sinceLast = 0;
+  for (let i = last; i < baselines.length; i += 1) sinceLast += baselines[i];
+  const total = history[last].inputTokens + sinceLast;
+  let beforeFirst = 0;
+  for (let i = 0; i < first; i += 1) beforeFirst += baselines[i];
+  const derived = Math.max(0, history[first].inputTokens - beforeFirst);
+  const claimed = preambleTokens ?? derived;
+  const contradicted = baselineTotal > 0 && claimed >= total;
+  const overhead = Math.min(contradicted ? derived : claimed, total);
+  const messages = Math.max(0, total - overhead);
+  if (baselineTotal <= 0) {
+    return { overhead, total, estimates: baselines, scale: 1 };
+  }
+  const scale = messages / baselineTotal;
+  const estimates = baselines.map((b) => Math.round(b * scale));
+  let assigned = 0;
+  let heaviest = -1;
+  for (let i = 0; i < estimates.length; i += 1) {
+    assigned += estimates[i];
+    if (baselines[i] > 0 && (heaviest < 0 || baselines[i] > baselines[heaviest])) heaviest = i;
+  }
+  if (heaviest >= 0) estimates[heaviest] += messages - assigned;
+  return { overhead, total, estimates, scale };
+}
+function estimateMessageTokens(history, preambleTokens) {
+  return calibrate(history, preambleTokens).estimates;
+}
+function estimateRequestTokens(storedHistory, requestHistory, preambleTokens) {
+  const { overhead } = calibrate(storedHistory, preambleTokens);
   let requestBaseline = 0;
   for (const m of requestHistory) requestBaseline += baselineTokens(m);
-  if (storedBaseline <= 0) return overhead + requestBaseline;
-  return Math.round(overhead + calibratedMessages * (requestBaseline / storedBaseline));
+  return Math.round(overhead + requestBaseline);
 }
-function projectCompaction(history, cut, summaryTokens = COMPACTION_SUMMARY_TOKEN_ESTIMATE) {
-  const estimates = estimateMessageTokens(history);
-  const overhead = estimateSystemOverhead(history);
+function projectCompaction(history, cut, summaryTokens = COMPACTION_SUMMARY_TOKEN_ESTIMATE, preambleTokens) {
+  const { estimates, overhead, total } = calibrate(history, preambleTokens);
   let tail = 0;
   for (let i = cut; i < estimates.length; i += 1) tail += estimates[i];
-  let all = 0;
-  for (const t of estimates) all += t;
-  const tokensBefore = overhead + all;
+  const tokensBefore = total;
   const tokensAfter = overhead + summaryTokens + tail;
   return {
     cut,
@@ -4229,8 +4244,8 @@ function isSafeCompactionCut(history, i) {
   }
   return true;
 }
-function findCompactionCut(history, tailTokenBudget = DEFAULT_TAIL_TOKEN_BUDGET) {
-  const estimates = estimateMessageTokens(history);
+function findCompactionCut(history, tailTokenBudget = DEFAULT_TAIL_TOKEN_BUDGET, preambleTokens) {
+  const estimates = estimateMessageTokens(history, preambleTokens);
   let messagesTotal = 0;
   for (const t of estimates) messagesTotal += t;
   if (messagesTotal <= tailTokenBudget) return null;
@@ -4251,9 +4266,14 @@ function planCompaction(history, options = {}) {
     tailTokenBudget = DEFAULT_TAIL_TOKEN_BUDGET,
     minReclaimTokens = DEFAULT_MIN_RECLAIM_TOKENS
   } = options;
-  const cut = findCompactionCut(history, tailTokenBudget);
+  const cut = findCompactionCut(history, tailTokenBudget, options.preambleTokens);
   if (cut == null) return null;
-  const projection = projectCompaction(history, cut);
+  const projection = projectCompaction(
+    history,
+    cut,
+    COMPACTION_SUMMARY_TOKEN_ESTIMATE,
+    options.preambleTokens
+  );
   return projection.reclaimed >= minReclaimTokens ? projection : null;
 }
 function renderMessageForSummary(m) {
@@ -5217,7 +5237,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
         attachments: pendingInput.attachments
       }
     ] : requestHistory;
-    const estimated = estimateRequestTokens(this.history, request);
+    const estimated = estimateRequestTokens(this.history, request, this.lastPreambleTokens);
     if (estimated < threshold) return void 0;
     logger2.error(
       `ChatDriver: ending the turn \u2014 the request would fill the context window (~${estimated} of ${limit})`
@@ -5405,6 +5425,10 @@ Output format (strict):
     this.loadHistory([summaryMessage, ...tail]);
     return summaryMessage;
   }
+  /** {@inheritDoc AiDriver.getPreambleTokens} */
+  getPreambleTokens() {
+    return this.lastPreambleTokens;
+  }
   isBusy() {
     return this.busy;
   }
@@ -6267,6 +6291,11 @@ ${tailBody}
       const attachmentsForCall = currentAttachments;
       currentInput = "";
       currentAttachments = void 0;
+      this.lastPreambleTokens = estimatePreambleTokens({
+        systemPrompt,
+        toolDefinitions: this.toolDefinitions,
+        tailContext
+      });
       const options = {
         systemPrompt,
         // Strip fold-only properties (foldEvent, foldPath) before sending to provider
@@ -6936,6 +6965,13 @@ function isSpecialist(agent) {
 function isFallback(agent) {
   return agent.fallback === true;
 }
+function normalizeContextReserve(input) {
+  if (input == null) return void 0;
+  const positive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+  if (typeof input === "number") return positive(input) ? { tokens: input } : void 0;
+  if (!positive(input.tokens)) return void 0;
+  return positive(input.warnAheadTokens) ? { tokens: input.tokens, warnAheadTokens: input.warnAheadTokens } : { tokens: input.tokens };
+}
 var UNROUTABLE_PLACEHOLDER = "{{unroutable}}";
 var UNROUTABLE_INSTRUCTION = `When the request is substantive but nothing above covers it, say so directly. Do not offer to do it yourself, and do not imply a specialist will pick it up.
 
@@ -7137,6 +7173,10 @@ var OrchestratingDriver = class extends EventTarget {
   canCompact(options) {
     return this.chatDriver.canCompact(options);
   }
+  /** {@inheritDoc AiDriver.getPreambleTokens} */
+  getPreambleTokens() {
+    return this.chatDriver.getPreambleTokens();
+  }
   /** {@inheritDoc AiDriver.getCompactionPlan} */
   getCompactionPlan(options) {
     return this.chatDriver.getCompactionPlan(options);
@@ -7258,6 +7298,32 @@ var OrchestratingDriver = class extends EventTarget {
   primeRestoredAgentState(snapshots) {
     this.restoredAgentStates = { ...snapshots };
   }
+  /**
+   * {@inheritDoc AiDriver.getContextReserve}
+   *
+   * Two cases, because routing has two modes and they need opposite answers.
+   */
+  getContextReserve() {
+    const locked = this.resolvePinnedAgent();
+    if (locked) {
+      const reserve = normalizeContextReserve(locked.contextReserve);
+      return reserve == null ? void 0 : { ...reserve, agentName: locked.name, basis: "locked" };
+    }
+    const candidates = [...this.specialists];
+    if (this.fallback) candidates.push(this.fallback);
+    if (this.activeAgent) candidates.push(this.activeAgent);
+    let winner;
+    let agentName = "";
+    for (const agent of candidates) {
+      const reserve = normalizeContextReserve(agent.contextReserve);
+      if (!reserve) continue;
+      if (!winner || reserve.tokens > winner.tokens) {
+        winner = reserve;
+        agentName = agent.name;
+      }
+    }
+    return winner ? { ...winner, agentName, basis: "reachable-max" } : void 0;
+  }
   /** {@inheritDoc AiDriver.getActiveAgent} */
   getActiveAgent() {
     return this.activeAgent;
@@ -7767,6 +7833,7 @@ function defineStatefulAgent(opts) {
     onUnresolvedTool: wrappedOnUnresolvedTool,
     resumable: wrappedResumable,
     notResumableMessage: opts.notResumableMessage,
+    contextReserve: opts.contextReserve,
     onActivate: async (ctx) => {
       state = await opts.init(ctx);
       if (opts.toolHandlers) {