@genesislcap/ai-assistant 15.22.2 → 15.23.1-FUI-0.4

package/dist/dts/react.d.ts

@@ -47,18 +47,6 @@ interface HTMLWCProps extends React.AriaAttributes {
   onInput?(e: Event): void;
 }
 
-export declare const FoundationAiAssistant: React.ForwardRefExoticComponent<
-  React.PropsWithChildren<
-    Omit<PublicOf<FoundationAiAssistantWC>, 'children' | 'style'> &
-    HTMLWCProps & {
-      onBudgetRefreshRequested?: (event: CustomEvent<unknown>) => void;
-      onChatHeaderMousedown?: (event: CustomEvent<ChatHeaderMouseDownDetail>) => void;
-      onSessionCleared?: (event: CustomEvent<SessionClearedDetail>) => void;
-    }
-  > & React.RefAttributes<FoundationAiAssistantWC>
->;
-export type FoundationAiAssistantRef = FoundationAiAssistantWC;
-
 export declare const AiFlowingWavesIndicator: React.ForwardRefExoticComponent<
   React.PropsWithChildren<
     Omit<PublicOf<AiFlowingWavesIndicatorWC>, 'children' | 'style'> &
@@ -95,6 +83,18 @@ export declare const AiWavesIndicator: React.ForwardRefExoticComponent<
 >;
 export type AiWavesIndicatorRef = AiWavesIndicatorWC;
 
+export declare const FoundationAiAssistant: React.ForwardRefExoticComponent<
+  React.PropsWithChildren<
+    Omit<PublicOf<FoundationAiAssistantWC>, 'children' | 'style'> &
+    HTMLWCProps & {
+      onBudgetRefreshRequested?: (event: CustomEvent<unknown>) => void;
+      onChatHeaderMousedown?: (event: CustomEvent<ChatHeaderMouseDownDetail>) => void;
+      onSessionCleared?: (event: CustomEvent<SessionClearedDetail>) => void;
+    }
+  > & React.RefAttributes<FoundationAiAssistantWC>
+>;
+export type FoundationAiAssistantRef = FoundationAiAssistantWC;
+
 export declare const ChatSuggestions: React.ForwardRefExoticComponent<
   React.PropsWithChildren<
     Omit<PublicOf<ChatSuggestionsWC>, 'children' | 'style'> &

package/dist/dts/utils/context-tokens.d.ts

@@ -16,6 +16,52 @@ import type { ChatMessage } from '@genesislcap/foundation-ai';
  * shed as tokens) — one definition so the two never drift.
  */
 export declare const APPROX_CHARS_PER_TOKEN = 4;
+/**
+ * Token cost of everything a request carries that is NOT a message — the system
+ * prompt, the tool definitions, and the framed tail (GENC-1582).
+ *
+ * **Why this is measured per call rather than derived.** The preamble used to be
+ * inferred as a residual: the first measured prompt minus the char estimate of the
+ * messages it covered. That derivation is accurate at the time, but it is taken
+ * ONCE and never updated, while the preamble changes every time the agent changes
+ * — each agent brings its own system prompt and its own tool surface. Every
+ * attempt to patch the staleness downstream made it worse; the cap that used to
+ * sit in `calibrate` compared stored CHARACTERS against a wire-measured TOKEN
+ * total and collapsed the preamble to zero on any condensed session, which is the
+ * same category error this module exists to fix. Measuring what is actually being
+ * sent removes the whole class of problem.
+ *
+ * **What is measured and what is not.** From the isa-platform session of
+ * 2026-09-03 (project 067f0fca, `claude-sonnet-5`), the first anchor measured
+ * 5,249 tokens against a single 290-character user message, so:
+ *
+ * | quantity | value | how |
+ * |---|---|---|
+ * | whole preamble, Bootstrap's first call | **5,173 tok** | MEASURED (5,249 − ~76 for the message) |
+ * | system prompt | **8,387 chars** | MEASURED (diag `turn` records it verbatim) |
+ * | system prompt in tokens | 2,097 | prose ratio applied to the measured chars |
+ * | 3 tool definitions | 3,076 tok (~1,025/tool) | **INFERRED as the residual** |
+ *
+ * The tools figure is a residual in TOKENS, not a ratio: diagnostics record
+ * `toolNames` only, never the schemas, so their character count is unavailable and
+ * `PREAMBLE_JSON_CHARS_PER_TOKEN` could not be calibrated from it. It is consistent
+ * with 3 — ~1,025 tokens per tool implies ~3,075 characters of schema per tool,
+ * which is the right order for a Create tool carrying descriptions and enum
+ * options — but consistent is not measured, and the next person should not read it
+ * as such. To calibrate it properly, log serialized schema characters alongside the
+ * first anchor for one real session and solve for the ratio.
+ *
+ * `tailContext` counts. It is regenerated per turn rather than accumulated, so
+ * compaction cannot remove it any more than it can remove the system prompt, which
+ * is the property that matters to every consumer of this figure.
+ */
+export declare function estimatePreambleTokens(input: {
+    systemPrompt?: string;
+    toolDefinitions?: readonly {
+        name: string;
+    }[];
+    tailContext?: string;
+}): number;
 /**
  * Allowance for the summary a compaction will produce, used when projecting the
  * post-compaction size before the summarizer has run. The system prompt asks for
@@ -83,48 +129,48 @@ export declare function reachesProvider(m: ChatMessage): boolean;
  */
 export declare function isContextMeasurable(history: readonly ChatMessage[]): boolean;
 /**
- * Per-message token estimates, calibrated against measured prompt sizes wherever
- * the transcript provides them.
- *
- * **How the calibration works.** `inputTokens` on the message produced by a call
- * is the size of that call's WHOLE prompt (the cache buckets break it down
- * rather than add to it), so it covers `history[0 … i-1]`. Two consecutive
- * anchors therefore bracket a segment whose exact measured cost is their
- * difference: `inputTokens[b] − inputTokens[a]` is what `history[a … b-1]` cost.
- * Within a segment the measured total is redistributed across its messages in
- * proportion to their baseline estimate — segment granularity is all that is
- * needed, since compaction only ever cuts on boundaries.
- *
- * A non-positive delta means history SHRANK between the two calls (a compaction
- * or a `condenseWhen` collapse landed in between); there is nothing to
- * distribute, so those messages keep their baseline.
- *
- * The region before the first anchor keeps its baseline too: that anchor's
- * measurement also contains the system prompt and tool definitions, which are
- * not attributable to any message — see {@link estimateSystemOverhead}.
+ * Per-message token estimates — each message's share of {@link calibrate}'s
+ * total, in proportion to how big that message is NOW.
+ *
+ * Used to choose and evaluate a compaction cut, so what matters is that the
+ * shares are in the same unit as the total and that they track the current size
+ * of each message. A payload `condenseWhen` has stubbed costs what the stub
+ * costs; under the segment-chained scheme this replaced, it kept the cost it had
+ * when it was full and the difference was merely redistributed to its neighbours.
+ *
+ * Sums to exactly `estimateContextTokens(history) - estimateSystemOverhead(history)`.
  */
-export declare function estimateMessageTokens(history: readonly ChatMessage[]): number[];
+export declare function estimateMessageTokens(history: readonly ChatMessage[], preambleTokens?: number): number[];
 /**
  * Context consumed by everything that is NOT a message — the system prompt and
  * the tool definitions.
  *
  * Derived rather than guessed: the first measured prompt covers the messages
- * before it plus that fixed preamble, so subtracting our estimate of those
- * messages leaves the preamble. Floored at zero, since an over-estimate of the
- * early messages would otherwise produce a negative overhead.
+ * before it plus the preamble, so subtracting our estimate of those messages
+ * leaves the preamble. Floored at zero, since an over-estimate of the early
+ * messages would otherwise produce a negative overhead, and capped at what the
+ * current total has left after paying for each message's characters — see
+ * {@link calibrate} for why that cap is load-bearing.
+ *
+ * It is NOT a constant, which the first cut of this assumed. Each agent brings its
+ * own system prompt and its own tool surface, so it steps up and down as agents
+ * hand over; what is true is that it does not shrink when the MESSAGES do.
  *
  * It matters for the gate because it is real context the user never sees in the
- * transcript, it does not shrink when history does, and on an agent with a large
- * tool surface it is far from negligible.
+ * transcript, and on an agent with a large tool surface it is far from negligible.
  */
-export declare function estimateSystemOverhead(history: readonly ChatMessage[]): number;
+export declare function estimateSystemOverhead(history: readonly ChatMessage[], preambleTokens?: number): number;
 /**
- * Total estimated context for a transcript — the preamble plus every message.
+ * Total estimated context for a transcript — the figure the gauge shows and the
+ * composer gate is judged against.
+ *
+ * The most recent usable measurement plus the char estimate of everything
+ * appended since it, which is as close as anything gets to "how big is the prompt
+ * we are about to send". See {@link calibrate} for why it is anchored on that one
+ * measurement rather than accumulated across all of them.
  *
- * On a transcript with measured anchors this lands close to the last observed
- * `inputTokens` by construction; the value of computing it rather than reading
- * that figure is that it stays defined for a hypothetical history (the tail a
- * compaction would leave behind), which is what {@link projectCompaction} needs.
+ * Stays defined for a hypothetical history (the tail a compaction would leave
+ * behind), which is what {@link projectCompaction} needs.
  */
 export declare function estimateContextTokens(history: readonly ChatMessage[]): number;
 /**
@@ -137,18 +183,29 @@ export declare function estimateContextTokens(history: readonly ChatMessage[]):
  * log. A guard that measured stored history would therefore refuse turns whose
  * real request is a fraction of the size.
  *
- * Naively estimating the transformed copy does NOT work either, and the reason is
- * subtle: `inputTokens` anchors live on the stored messages and measured the
- * untransformed prompt, so calibrating against them re-inflates the estimate back
- * to roughly what it was before the transform — exactly the figure we were trying
- * to avoid.
- *
- * So the calibrated total is scaled by how much smaller the request is in
- * characters. That keeps the accuracy the measurements buy while still reflecting
- * what the transform removed. The preamble is carried across unscaled: the system
- * prompt and tool definitions are not what condensation touches.
+ * So the request is estimated from its OWN characters, plus the preamble. Nothing
+ * is scaled: `requestHistory` IS the payload, so `baselineTokens` is already
+ * measuring the right bytes, and there is no transform left to correct for.
+ *
+ * **This previously applied a ratio, and a docblock here previously claimed it did
+ * not.** Both were wrong, and the second is the part worth recording. The original
+ * expression scaled the stored-history total by `requestChars / storedChars`,
+ * reasoning that `inputTokens` "measured the untransformed prompt". That premise is
+ * false — `inputTokens` measures the prompt that was SENT, transform already
+ * applied — and it is what made every figure in this module too large. The GENC-1582
+ * rewrite claimed to drop the ratio but only re-factored it: `scale` is
+ * `(total - overhead) / storedBaseline`, so `overhead + requestBaseline * scale` is
+ * the identical expression rearranged. With the total now anchored on a measurement
+ * of an already-condensed prompt, that discounted the same shrinkage twice —
+ * measured at **5,034 against a last measured prompt of 120,000**, i.e. a guard that
+ * believed it had 995k spare. Under-estimating is the one direction this figure must
+ * not err in, since its only job is refusing an overflow.
+ *
+ * The preamble must be passed in for the same reason: `requestBaseline` counts
+ * message characters, and the system prompt and tool definitions are not messages,
+ * so without it the guard silently ignores the entire tool surface.
  */
-export declare function estimateRequestTokens(storedHistory: readonly ChatMessage[], requestHistory: readonly ChatMessage[]): number;
+export declare function estimateRequestTokens(storedHistory: readonly ChatMessage[], requestHistory: readonly ChatMessage[], preambleTokens?: number): number;
 /** What a compaction at a given cut would cost and reclaim. */
 export interface CompactionProjection {
     /** Index the verbatim tail starts at — everything before it is summarized. */
@@ -174,5 +231,5 @@ export interface CompactionProjection {
  * The system preamble is carried across unchanged: compaction removes messages,
  * never the system prompt or the tool definitions.
  */
-export declare function projectCompaction(history: readonly ChatMessage[], cut: number, summaryTokens?: number): CompactionProjection;
+export declare function projectCompaction(history: readonly ChatMessage[], cut: number, summaryTokens?: number, preambleTokens?: number): CompactionProjection;
 //# sourceMappingURL=context-tokens.d.ts.map

package/dist/dts/utils/context-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-tokens.d.ts","sourceRoot":"","sources":["../../../src/utils/context-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAexC;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,OAAQ,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAKvD;AAmGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,EAAE,CAmC/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAO9E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAK7E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,SAAS,WAAW,EAAE,EACrC,cAAc,EAAE,SAAS,WAAW,EAAE,GACrC,MAAM,CAaR;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,GAAG,EAAE,MAAM,EACX,aAAa,GAAE,MAA0C,GACxD,oBAAoB,CAkBtB"}
+{"version":3,"file":"context-tokens.d.ts","sourceRoot":"","sources":["../../../src/utils/context-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AA6CxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAiBT;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,OAAQ,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAKvD;AA6SD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,EAAE,CAEV;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAE7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,SAAS,WAAW,EAAE,EACrC,cAAc,EAAE,SAAS,WAAW,EAAE,EACtC,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,CAKR;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,GAAG,EAAE,MAAM,EACX,aAAa,GAAE,MAA0C,EACzD,cAAc,CAAC,EAAE,MAAM,GACtB,oBAAoB,CAkBtB"}

package/dist/dts/utils/history-transform.d.ts

@@ -81,13 +81,19 @@ export declare function isSafeCompactionCut(history: readonly ChatMessage[], i:
  * enormous, indivisible tool group, which no cut can shrink because a cut cannot
  * split a message.
  */
-export declare function findCompactionCut(history: readonly ChatMessage[], tailTokenBudget?: number): number | null;
+export declare function findCompactionCut(history: readonly ChatMessage[], tailTokenBudget?: number, preambleTokens?: number): number | null;
 /** Options for {@link planCompaction}. */
 export interface CompactionPlanOptions {
     /** Token budget for the verbatim tail. */
     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;
 }
 /**
  * The single answer to "what would compacting do right now, and is it worth it?"

package/dist/dts/utils/history-transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history-transform.d.ts","sourceRoot":"","sources":["../../../src/utils/history-transform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EACL,KAAK,oBAAoB,EAI1B,MAAM,kBAAkB,CAAC;AAoC1B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAsBjG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CAG3F;AAID;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CASvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,eAAe,GAAE,MAAkC,GAClD,MAAM,GAAG,IAAI,CAkBf;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,GAAG,IAAI,CAS7B;AAkCD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,CAYA;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAanF;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAG7D"}
+{"version":3,"file":"history-transform.d.ts","sourceRoot":"","sources":["../../../src/utils/history-transform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,kBAAkB,CAAC;AAoC1B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAsBjG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CAG3F;AAID;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CASvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,eAAe,GAAE,MAAkC,EACnD,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,GAAG,IAAI,CAkBf;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,GAAG,IAAI,CAc7B;AAkCD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,CAYA;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAanF;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAG7D"}

package/dist/dts/utils/resolve-context-budget.d.ts

@@ -77,15 +77,18 @@ export interface ContextBudgetInput {
     /** Context window reported by the active provider, if any. */
     contextLimit?: number;
     /**
-     * Reserve declared by the active agent, if any — overrides the configured
-     * global reserve for this agent only.
+     * Reserve declared by the agent the next turn could land on, if any — overrides
+     * the configured global reserve for that agent only.
      */
     agentReserveTokens?: number;
     /**
-     * Estimated system prompt + tool definitions. Subtracted when sizing the tail,
-     * since compaction removes messages and never the preamble.
+     * Extra tokens above {@link ContextBudgetInput.agentReserveTokens} at which the
+     * warning appears, when that agent declared one (GENC-1582). Takes precedence
+     * over `warnMultiplier`, which cannot express it: the multiplier scales the whole
+     * reserve, so an agent that peaks large and keeps little gets a warning line
+     * every one of its turns crosses transiently and then clears.
      */
-    systemOverhead?: number;
+    agentWarnAheadTokens?: number;
 }
 /**
  * Resolve the headroom thresholds for the active model and agent.

package/dist/dts/utils/resolve-context-budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-context-budget.d.ts","sourceRoot":"","sources":["../../../src/utils/resolve-context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,UAAU,EAAE,UAAU,CAAC;IACvB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,qBAAqB,CAmDrF"}
+{"version":3,"file":"resolve-context-budget.d.ts","sourceRoot":"","sources":["../../../src/utils/resolve-context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAM7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,UAAU,EAAE,UAAU,CAAC;IACvB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,qBAAqB,CAgFrF"}

package/dist/esm/components/chat-driver/chat-driver.js

@@ -5,7 +5,7 @@ import { resolveChatProvider } from '../../config/validate-providers';
 import { clearSession, getMetaEvents, mergeMetaEvents, recordMetaEvent, recordTurnError, recordTurnRetry, } from '../../state/debug-event-log';
 import { createInteractionContext, } from '../../state/interaction-context';
 import { applyCondensation, condenseForPersistence, } from '../../utils/condense-history';
-import { estimateRequestTokens } from '../../utils/context-tokens';
+import { estimatePreambleTokens, estimateRequestTokens, } from '../../utils/context-tokens';
 import { applyHistoryCap, buildCompactionSummaryPrompt, planCompaction, normalizeForProvider, } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { messageUsage, sumUsage } from '../../utils/sum-usage';
@@ -1037,7 +1037,14 @@ export class ChatDriver extends EventTarget {
                 },
             ]
             : requestHistory;
-        const estimated = estimateRequestTokens(this.history, request);
+        // The preamble is passed EXPLICITLY, and this guard is the reason the parameter
+        // exists (GENC-1582). `requestBaseline` counts message characters, and the
+        // system prompt and tool definitions are not messages — so without it the
+        // guard silently ignores the entire tool surface and, on a history with no
+        // usable anchor, the whole preamble. `lastPreambleTokens` is assigned for THIS
+        // request earlier in the same loop iteration, so it is fresh rather than a
+        // previous turn's.
+        const estimated = estimateRequestTokens(this.history, request, this.lastPreambleTokens);
         if (estimated < threshold)
             return undefined;
         logger.error(`ChatDriver: ending the turn — the request would fill the context window (~${estimated} of ${limit})`);
@@ -1280,6 +1287,10 @@ export class ChatDriver extends EventTarget {
             return summaryMessage;
         });
     }
+    /** {@inheritDoc AiDriver.getPreambleTokens} */
+    getPreambleTokens() {
+        return this.lastPreambleTokens;
+    }
     isBusy() {
         return this.busy;
     }
@@ -2458,6 +2469,15 @@ export class ChatDriver extends EventTarget {
                 const attachmentsForCall = currentAttachments;
                 currentInput = '';
                 currentAttachments = undefined;
+                // Record what this request's preamble costs, at the one point everything it
+                // is made of has been resolved (GENC-1582). Read back by the host through
+                // `getPreambleTokens()` to size the context gate and the compaction target
+                // against the ACTIVE agent's surface rather than a stale first-call residual.
+                this.lastPreambleTokens = estimatePreambleTokens({
+                    systemPrompt,
+                    toolDefinitions: this.toolDefinitions,
+                    tailContext,
+                });
                 const options = {
                     systemPrompt,
                     // Strip fold-only properties (foldEvent, foldPath) before sending to provider

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -46,6 +46,40 @@ function isSpecialist(agent) {
 function isFallback(agent) {
     return agent.fallback === true;
 }
+/**
+ * Flatten a `contextReserve` declaration to the two numbers the gate reads
+ * (GENC-1582), or `undefined` when the agent declared nothing.
+ *
+ * A bare number is the peak-only form and leaves the warning to the host's
+ * `warnMultiplier`. Non-positive `tokens` is treated as no declaration rather
+ * than as "needs no headroom": zero would resolve to a reserve of 0, which sets
+ * `blockAt` to the whole window and switches the gate off for every agent the
+ * turn could reach — the opposite of what declaring a reserve is for.
+ *
+ * **Validated at runtime, not just by the type.** `contextReserve` is host-supplied
+ * `@beta` config and can arrive from JS, from JSON, or from a dynamic source, so
+ * `tokens` may be absent or not a number whatever the signature says. That matters
+ * more than a violated return type: `undefined <= 0` is `false`, so a bare
+ * comparison passed a malformed reserve straight through as `{ tokens: undefined }`,
+ * and the caller's `reserve.tokens > winner.tokens` then compared against
+ * `undefined` — always false. One malformed entry on an earlier-listed agent
+ * therefore SUPPRESSED every valid reserve behind it, and the gate fell back to the
+ * ambient default while still naming the malformed agent. Silent, because
+ * `resolveContextBudget` coalesces an undefined reserve to that same default
+ * (reviewer catch on #2504).
+ */
+function normalizeContextReserve(input) {
+    if (input == null)
+        return undefined;
+    const positive = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+    if (typeof input === 'number')
+        return positive(input) ? { tokens: input } : undefined;
+    if (!positive(input.tokens))
+        return undefined;
+    return positive(input.warnAheadTokens)
+        ? { tokens: input.tokens, warnAheadTokens: input.warnAheadTokens }
+        : { tokens: input.tokens };
+}
 /**
  * Placeholder a consumer can put in its fallback prompt to position
  * {@link UNROUTABLE_INSTRUCTION} itself, instead of having it appended.
@@ -293,6 +327,10 @@ export class OrchestratingDriver 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);
@@ -499,6 +537,60 @@ export class OrchestratingDriver extends EventTarget {
     primeRestoredAgentState(snapshots) {
         this.restoredAgentStates = Object.assign({}, snapshots);
     }
+    /**
+     * {@inheritDoc AiDriver.getContextReserve}
+     *
+     * Two cases, because routing has two modes and they need opposite answers.
+     */
+    getContextReserve() {
+        // LOCKED — a user pin or a flow-owner lock. `handleTurn` routes straight to
+        // this agent and the handoff branch at the bottom of the routing loop refuses
+        // to route away while a lock is held, so no other agent's headroom can come
+        // into play until it clears. Its reserve is the whole requirement.
+        const locked = this.resolvePinnedAgent();
+        if (locked) {
+            const reserve = normalizeContextReserve(locked.contextReserve);
+            return reserve == null ? undefined : Object.assign(Object.assign({}, reserve), { agentName: locked.name, basis: 'locked' });
+        }
+        // AUTOMATIC — the classifier picks a specialist, may fall through to the
+        // fallback, and may hand off and re-classify more than once inside the one
+        // turn. Any of them could be the agent that runs, and the send is allowed or
+        // refused before we know which, so the requirement is the largest reserve
+        // among them: the turn has to fit whichever way it routes.
+        //
+        // The MAX, not the sum, even though a handoff chain really does add each leg's
+        // growth on top of the last. Summing every reachable agent would reserve room
+        // for a journey nobody is taking and strand most of the window on a two-line
+        // question; the mid-loop context guard is what bounds a chain that does run
+        // long. The max is the smallest reserve that makes the FIRST leg safe, which
+        // is the only leg this gate can speak for.
+        //
+        // `excludeFromClassifier` agents are absent by construction — they are
+        // reachable only by pin or by a restored flow-owner lock, and both of those
+        // are the locked arm above. The active agent is folded in as a floor: on the
+        // turn after a lock clears it is still the agent holding the context, and it
+        // need not be one the classifier could have picked.
+        const candidates = [...this.specialists];
+        if (this.fallback)
+            candidates.push(this.fallback);
+        if (this.activeAgent)
+            candidates.push(this.activeAgent);
+        // Compared on `tokens` — the figure that decides whether a turn may start.
+        // `warnAheadTokens` is not a candidate for the max in its own right; it rides
+        // along with whichever agent wins.
+        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 ? Object.assign(Object.assign({}, winner), { agentName, basis: 'reachable-max' }) : undefined;
+    }
     /** {@inheritDoc AiDriver.getActiveAgent} */
     getActiveAgent() {
         return this.activeAgent;

package/dist/esm/config/define-stateful-agent.js

@@ -264,6 +264,7 @@ export function defineStatefulAgent(opts) {
         onUnresolvedTool: wrappedOnUnresolvedTool,
         resumable: wrappedResumable,
         notResumableMessage: opts.notResumableMessage,
+        contextReserve: opts.contextReserve,
         onActivate: (ctx) => __awaiter(this, void 0, void 0, function* () {
             state = yield opts.init(ctx);
             // Sample once with the init state to fail loud on fold misuse at the