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

package/dist/esm/utils/context-tokens.js

@@ -26,6 +26,90 @@ export const APPROX_CHARS_PER_TOKEN = 4;
 const IMAGE_TOKEN_ESTIMATE = 1600;
 /** Per-message role/framing overhead every transport adds around the content. */
 const PER_MESSAGE_FRAMING_TOKENS = 4;
+/**
+ * Chars-per-token for the system prompt — prose, so the ordinary ratio applies.
+ */
+const PREAMBLE_PROSE_CHARS_PER_TOKEN = 4;
+/**
+ * Chars-per-token for the tool definitions — JSON, which tokenizes WORSE than
+ * prose. Punctuation-dense, short quoted keys, deep nesting: `{`, `"`, `:`, `[`
+ * mostly cost a token each where four characters of prose share one.
+ *
+ * **This ratio is REASONED, not measured** — see {@link estimatePreambleTokens}
+ * for exactly what was measured and what was not. It is deliberately the
+ * pessimistic side of the plausible 3–3.5 range: this figure feeds the guard that
+ * refuses an oversized request, and over-stating the preamble costs a little
+ * unused headroom where under-stating lets a turn overflow.
+ */
+const PREAMBLE_JSON_CHARS_PER_TOKEN = 3;
+/**
+ * Per-tool framing allowance, the tool-surface equivalent of
+ * {@link PER_MESSAGE_FRAMING_TOKENS}.
+ *
+ * What reaches the wire is not the JSON we serialize: every transport reshapes a
+ * `ChatToolDefinition` into its own vendor form (`input_schema` for Anthropic,
+ * `functionDeclarations` for Gemini) and wraps each one. Counting only the
+ * serialized bytes therefore misses a fixed cost per tool, which on an agent
+ * advertising a large surface is not negligible.
+ */
+const PER_TOOL_FRAMING_TOKENS = 8;
+/**
+ * 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 function estimatePreambleTokens(input) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const prose = ((_b = (_a = input.systemPrompt) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) + ((_d = (_c = input.tailContext) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0);
+    let json = 0;
+    for (const def of (_e = input.toolDefinitions) !== null && _e !== void 0 ? _e : []) {
+        try {
+            json += JSON.stringify(def).length;
+        }
+        catch (_k) {
+            // Circular or otherwise unserializable: the framing allowance below still
+            // charges for the tool itself rather than dropping it silently.
+            json += (_g = (_f = def.name) === null || _f === void 0 ? void 0 : _f.length) !== null && _g !== void 0 ? _g : 0;
+        }
+    }
+    return (Math.ceil(prose / PREAMBLE_PROSE_CHARS_PER_TOKEN) +
+        Math.ceil(json / PREAMBLE_JSON_CHARS_PER_TOKEN) +
+        ((_j = (_h = input.toolDefinitions) === null || _h === void 0 ? void 0 : _h.length) !== null && _j !== void 0 ? _j : 0) * PER_TOOL_FRAMING_TOKENS);
+}
 /**
  * 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
@@ -174,6 +258,190 @@ function usableAnchor(m, compactedAt) {
 function firstAnchor(history, compactedAt) {
     return history.findIndex((m) => usableAnchor(m, compactedAt));
 }
+/** Index of the LAST message carrying a usable measurement, or `-1`. */
+function lastAnchor(history, compactedAt) {
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        if (usableAnchor(history[i], compactedAt))
+            return i;
+    }
+    return -1;
+}
+/**
+ * The one calibration every estimate in this module is derived from (GENC-1582).
+ *
+ * **What `inputTokens` actually measures, and what it does not.** It is the size
+ * of the prompt a call really SENT — that is, the prompt after `condenseWhen` has
+ * stubbed spent tool payloads and per-agent masking has blanked another agent's.
+ * It is therefore an authoritative measurement of the wire, and no measurement of
+ * stored history exists at all. The first implementation of this module had that
+ * backwards (see the note left on {@link estimateRequestTokens}) and treated the
+ * anchors as describing untransformed history, which is where every figure here
+ * went wrong.
+ *
+ * **Why the old segment chain could not be repaired in place.** It charged each
+ * pair of consecutive anchors the DIFFERENCE between their measurements and kept
+ * the result, skipping the pair when the difference was negative. Growth was
+ * banked permanently; shrinkage was discarded. The total was consequently an
+ * integral of everything the conversation had ever grown by and rose
+ * monotonically, so no condensation, masking or compaction could ever bring it
+ * down. On a measured Create session it read 868,761 tokens — 87% of a 1M window
+ * — against a real last prompt of 107,928, having accumulated 857,712 of growth
+ * while throwing away 755,033 of shrinkage. Since the same figure gates the
+ * composer and, through `estimateRequestTokens`, the running-turn guard, it was
+ * on course to refuse work on a conversation using 11% of its window.
+ *
+ * **The model that replaced it.** Three facts, in the order they can be known:
+ *
+ * 1. The FIRST measurement is the only place the preamble is separable: it covers
+ *    the preamble plus a handful of messages, so subtracting the char estimate of
+ *    those messages leaves the preamble (see {@link estimateSystemOverhead}).
+ * 2. The LAST measurement is authoritative for everything before it — it is the
+ *    most recent true statement about the size of this conversation — so the total
+ *    is that figure plus the char estimate of whatever has been appended since.
+ *    Nothing is chained, so nothing accumulates, and a condensation shows up as a
+ *    smaller total on the very next call.
+ * 3. Per-message estimates are then shares of that total, in proportion to each
+ *    message's CURRENT size. Proportional-to-baseline is what makes a stub cost
+ *    what a stub costs: the old scheme pinned a segment to its historical measured
+ *    cost, so shrinking a message inside it merely moved tokens to its neighbours.
+ *
+ * The accuracy this buys is worth stating, because the old code's docblocks argued
+ * the opposite trade-off. Replayed call-by-call over the session above, the total's
+ * median absolute error against the prompt actually sent next falls from 76% to
+ * 0.3%. It is least accurate in two situations, both bounded by one call's change
+ * rather than accumulating: it over-states while a condensation is pending (the
+ * last measurement still describes the fat prompt), and it under-states a call
+ * that loads a large block of context in one step (nothing in stored history
+ * predicts it). The second is what a headroom reserve is for, not an estimator.
+ *
+ * `scale` is deliberately not used to compute the total — only to distribute it.
+ * It is noisy exactly where stored history is a poor proxy for the wire, and
+ * keeping the total anchored on a measurement rather than on `scale * baseline`
+ * is what stops that noise reaching the gate.
+ */
+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);
+    // Nothing has ever reported usage, or a compaction invalidated every
+    // measurement. The char estimate is all there is for the MESSAGES — but a
+    // measured preamble is still authoritative, because it describes what was just
+    // built rather than being derived from an anchor. Only the derivation needs an
+    // anchor; a handed-in measurement does not, and discarding it here reported a
+    // preamble of zero on the two paths that reach this branch: a conversation
+    // before its first response, and the moment after a compaction (every retained
+    // message predates `compactedAt`, so no anchor survives). The second is the one
+    // that bit — `estimateRequestTokens` is the mid-turn overflow guard, and on a
+    // large tool surface it saw ~15 tokens instead of ~30,000.
+    //
+    // The preamble is added to `total` as well as reported as `overhead`, and both
+    // halves matter. In the anchored path below, `overhead` is carved OUT of a
+    // wire-measured total that already contains it; here there is no such total, so
+    // it has to be added or `messages` absorbs the difference. Reporting it in only
+    // one of the two places is worse than not reporting it at all: `projectCompaction`
+    // prices the preamble into `tokensAfter` and reads `total` for `tokensBefore`, so
+    // an overhead missing from the total makes every projection look like a net LOSS,
+    // `reclaimed` floors at zero, and `planCompaction` rejects the plan
+    // (`reclaimed >= minReclaimTokens`) — telling the user compaction cannot help on
+    // a transcript where it would reclaim plenty. Measured on the fixture in
+    // `context-tokens.test.ts`: reclaimed 8,814 → 0 with the total left alone.
+    //
+    // Nothing is invented: with no measurement passed this is exactly the old
+    // zero-overhead result, and `reclaimed` is unchanged either way, since the
+    // preamble then appears on both sides of `tokensBefore - tokensAfter`.
+    if (first < 0 || last < 0) {
+        const measured = Math.max(0, preambleTokens !== null && preambleTokens !== void 0 ? preambleTokens : 0);
+        return {
+            overhead: measured,
+            total: baselineTotal + measured,
+            estimates: baselines,
+            scale: 1,
+        };
+    }
+    // The last measurement covers `history[0 … last-1]`; the messages from `last`
+    // onwards rode no measured prompt yet, so they are added at their char estimate.
+    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];
+    // A MEASURED preamble wins outright (GENC-1582). Only the total bounds it: the
+    // preamble cannot exceed a prompt that contains it.
+    //
+    // It is deliberately NOT capped against `baselineTotal`, which is what the
+    // previous cap did and why it had to go. `baselineTotal` counts stored
+    // CHARACTERS — full-fat, every tool payload intact, because `condenseWhen` works
+    // on a copy — while `total` is anchored on a wire-measured TOKEN count of an
+    // already-condensed prompt. Mid-run the former dwarfs the latter, so
+    // `total - baselineTotal` went negative and clamped the preamble to zero on
+    // exactly the condensed sessions this module exists to serve. Measured: 0 against
+    // full-fat stored history, 5,000 against the same session's post-condensation
+    // export — which is why the export-based check missed it. Comparing stored
+    // characters with wire tokens is the category error the whole file is about.
+    //
+    // Without a measurement we still fall back to the residual derivation, which is
+    // accurate when taken and goes stale on handover — see
+    // {@link estimatePreambleTokens} for why the fix was to stop deriving it.
+    const derived = Math.max(0, history[first].inputTokens - beforeFirst);
+    // A MEASURED preamble is trusted (GENC-1582) — but only up to the point where it
+    // starts contradicting a measurement, which is where an earlier version of this
+    // got it wrong.
+    //
+    // `total` is anchored on a WIRE measurement, and that measurement contains the
+    // preamble AND the messages that rode with it. So a preamble at or above `total`,
+    // on a history that HAS messages, is arithmetically impossible: it is proof the
+    // ESTIMATE is too high, not a fact about the conversation. `estimatePreambleTokens`
+    // converts characters to tokens with reasoned divisors rather than a tokenizer, and
+    // measured live on a large tool surface it reads about 12% high — 34,325 against a
+    // whole prompt the provider measured at 30,608.
+    //
+    // Letting it win there zeroed `messages`, which zeroes every share, which nulls the
+    // compaction plan — so the gate tells the user compaction cannot help on a transcript
+    // where it would in fact reclaim plenty. That is reachable on ANY window: it needs
+    // only a condensation to shrink the prompt below the preamble, which is routine after
+    // a long tool loop.
+    //
+    // The comment this replaces claimed the zero-shares state "is precisely the `'model'`
+    // block cause". It is not, and the two are not even related: `contextBlockCause` keys
+    // off `contextBudget.blockAt === 0`, i.e. the reserve against the WINDOW, and never
+    // consults this figure. Conflating "preamble exceeds the window" (rare, and genuinely
+    // means the model cannot host the agent) with "preamble exceeds the current transcript"
+    // (routine) is what put a dead end on the common path.
+    //
+    // So when the estimate is contradicted, fall back to the residual derivation, which is
+    // itself computed from a measured prompt. Zero shares remain possible only when there
+    // is genuinely nothing to price.
+    const claimed = preambleTokens !== null && preambleTokens !== void 0 ? 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));
+    // Land the rounding residual on the heaviest message so the shares sum to
+    // EXACTLY `messages`. Heaviest rather than last: its share is at least the mean,
+    // which is comfortably more than the residual can ever be (half a token per
+    // message), so the correction cannot drive an estimate negative. Without this
+    // the per-message rounding drifts and every projection inherits the drift.
+    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 };
+}
 /**
  * Whether anything about this transcript's size is knowable.
  *
@@ -199,100 +467,55 @@ export function isContextMeasurable(history) {
     return history.some((m) => m.inputTokens != null || m.role === 'compacted-summary');
 }
 /**
- * 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 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) {
-            // Nothing to scale against (an all-display-only segment): put the measured
-            // cost on the first message rather than losing it.
-            estimates[from] = measured;
-            continue;
-        }
-        // Rescale, then put the rounding residual on the last message of the segment
-        // so the segment sums to EXACTLY what was measured. Without it the per-message
-        // rounding drifts, and every projection inherits the drift of every segment
-        // before it.
-        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;
-    }
-    return estimates;
+export function estimateMessageTokens(history, preambleTokens) {
+    return calibrate(history, preambleTokens).estimates;
 }
 /**
  * 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 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);
+export function estimateSystemOverhead(history, preambleTokens) {
+    return calibrate(history, preambleTokens).overhead;
 }
 /**
- * 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 function estimateContextTokens(history) {
-    const estimates = estimateMessageTokens(history);
-    let total = estimateSystemOverhead(history);
-    for (const t of estimates)
-        total += t;
-    return total;
+    return calibrate(history).total;
 }
 /**
  * Estimated size of the request that will actually be SENT, given the stored
@@ -304,31 +527,34 @@ export function estimateContextTokens(history) {
  * 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 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.
  *
- * 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.
+ * 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 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);
+export function estimateRequestTokens(storedHistory, requestHistory, preambleTokens) {
+    const { overhead } = calibrate(storedHistory, preambleTokens);
     let requestBaseline = 0;
     for (const m of requestHistory)
         requestBaseline += baselineTokens(m);
-    // No stored baseline to scale against (an all-display-only history): the
-    // request's own baseline is the best available answer.
-    if (storedBaseline <= 0)
-        return overhead + requestBaseline;
-    return Math.round(overhead + calibratedMessages * (requestBaseline / storedBaseline));
+    return Math.round(overhead + requestBaseline);
 }
 /**
  * Project the effect of compacting at `cut`, WITHOUT running the summarizer.
@@ -342,16 +568,15 @@ export function estimateRequestTokens(storedHistory, requestHistory) {
  * The system preamble is carried across unchanged: compaction removes messages,
  * never the system prompt or the tool definitions.
  */
-export function projectCompaction(history, cut, summaryTokens = COMPACTION_SUMMARY_TOKEN_ESTIMATE) {
-    const estimates = estimateMessageTokens(history);
-    const overhead = estimateSystemOverhead(history);
+export function projectCompaction(history, cut, summaryTokens = COMPACTION_SUMMARY_TOKEN_ESTIMATE, preambleTokens) {
+    // One calibration for both figures, so `tokensBefore` is the same number the
+    // gauge and the gate read. Deriving it independently is how an affordance ends
+    // up promising a reclaim measured against a total nothing else agrees with.
+    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,

package/dist/esm/utils/history-transform.js

@@ -1,5 +1,5 @@
 import { __rest } from "tslib";
-import { estimateMessageTokens, projectCompaction, reachesProvider, } from './context-tokens';
+import { COMPACTION_SUMMARY_TOKEN_ESTIMATE, estimateMessageTokens, projectCompaction, reachesProvider, } from './context-tokens';
 /**
  * Masks the tool-specific payload of a single message — clears tool call args
  * and replaces tool result content with a placeholder. Used when passing history
@@ -152,8 +152,8 @@ export function isSafeCompactionCut(history, i) {
  * enormous, indivisible tool group, which no cut can shrink because a cut cannot
  * split a message.
  */
-export function findCompactionCut(history, tailTokenBudget = DEFAULT_TAIL_TOKEN_BUDGET) {
-    const estimates = estimateMessageTokens(history);
+export function findCompactionCut(history, tailTokenBudget = DEFAULT_TAIL_TOKEN_BUDGET, preambleTokens) {
+    const estimates = estimateMessageTokens(history, preambleTokens);
     let messagesTotal = 0;
     for (const t of estimates)
         messagesTotal += t;
@@ -191,10 +191,10 @@ export function findCompactionCut(history, tailTokenBudget = DEFAULT_TAIL_TOKEN_
  */
 export function planCompaction(history, options = {}) {
     const { 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;
 }
 /** One-line rendering of a message for the summarizer transcript. */

package/dist/esm/utils/resolve-context-budget.js

@@ -1,4 +1,3 @@
-import { COMPACTION_SUMMARY_TOKEN_ESTIMATE } from './context-tokens';
 // Re-exported, not redeclared: this module and `planCompaction` must apply the
 // SAME worth-it floor, or a host passing explicit options and a caller relying
 // on the module default would silently disagree about whether a compaction is
@@ -41,7 +40,7 @@ export const CONTEXT_ABORT_MARGIN_TOKENS = 4096;
  */
 export function resolveContextBudget(input) {
     var _a, _b, _c;
-    const { chatConfig, contextLimit, agentReserveTokens, systemOverhead = 0 } = input;
+    const { chatConfig, contextLimit, agentReserveTokens, agentWarnAheadTokens } = input;
     const cfg = chatConfig.context;
     const reserveTokens = Math.max(0, (_a = agentReserveTokens !== null && agentReserveTokens !== void 0 ? agentReserveTokens : cfg === null || cfg === void 0 ? void 0 : cfg.reserveTokens) !== null && _a !== void 0 ? _a : DEFAULT_RESERVE_TOKENS);
     const warnMultiplier = Math.max(1, (_b = cfg === null || cfg === void 0 ? void 0 : cfg.warnMultiplier) !== null && _b !== void 0 ? _b : DEFAULT_WARN_MULTIPLIER);
@@ -60,11 +59,42 @@ export function resolveContextBudget(input) {
     }
     const enabled = (cfg === null || cfg === void 0 ? void 0 : cfg.enabled) !== false;
     const blockAt = Math.max(0, limit - reserveTokens);
-    const warnAt = Math.max(0, limit - warnMultiplier * reserveTokens);
-    // Aim compaction at the warning line, and leave room for the summary itself.
-    // Floored at one reserve so a pathological config (a reserve wider than the
-    // window) still asks for a tail rather than an impossible zero.
-    const tailTokenBudget = Math.max(reserveTokens, warnAt - systemOverhead - COMPACTION_SUMMARY_TOKEN_ESTIMATE);
+    // An agent-declared warn-ahead is an ABSOLUTE distance above the block, so the
+    // warning sits a fixed, meaningful step ahead of it — one more of that agent's
+    // turns — instead of a multiple of a reserve it has no relation to. Only
+    // honoured alongside that agent's own reserve; on its own it would be measuring
+    // a step ahead of somebody else's line.
+    const warnAt = agentReserveTokens != null && agentWarnAheadTokens != null
+        ? Math.max(0, limit - (reserveTokens + agentWarnAheadTokens))
+        : Math.max(0, limit - warnMultiplier * reserveTokens);
+    // Compaction's own target, deliberately NOT derived from `warnAt` (GENC-1582).
+    //
+    // `limit - 2 * reserve` is "leave room for about two of this agent's turns" of
+    // FREE headroom, so the retained tail shrinks as an agent's appetite grows: a
+    // 400k-reserve agent on a 1M window keeps 200,000 and compacts hard, while an
+    // agent on the ambient 25k keeps 950,000 and `findCompactionCut` correctly
+    // declines to do anything. That is the right way round — the expensive agent is
+    // the one that cannot afford history sitting alongside its turns.
+    //
+    // **This was coupled to `warnAt`, and the coupling was a real behaviour bug.**
+    // GENC-1567 (08f6504c44) introduced both this budget and the token-based cut, and
+    // aimed the budget at the warning line — coherent while `warnAt` meant "a whole
+    // reserve of room left". The GENC-1582 warn-ahead redefined `warnAt` as "one
+    // turn's residue left", which is what the warning wants and the opposite of what
+    // compaction wants, and this line inherited the new meaning silently: `warnAt`
+    // 200,000 -> 560,000 took the budget 400,000 -> 553,800 and cut the reclaim from
+    // ~195,000 to ~40,000. Since the budget drives `findCompactionCut`, which drives
+    // `compact()`, that is how much less gets summarized — not a display figure.
+    // Two unrelated questions ("when do we tell the user?" and "how much do we throw
+    // away?") were sharing one number; they no longer are.
+    //
+    // The `reserveTokens` floor went with it. It is what made the budget 400,000 in
+    // the first place, and on a tight window it produced a tail wider than the window
+    // had room for — a compaction that did nothing. A window that cannot host the
+    // agent is now reported as the `'model'` block cause instead of being papered
+    // over here. `systemOverhead` is gone for the same reason it stopped being
+    // derivable: see `estimatePreambleTokens`.
+    const tailTokenBudget = Math.max(0, limit - 2 * reserveTokens);
     return {
         enabled,
         limit,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.23.0",
+  "version": "15.23.1-FUI-0.4",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -74,26 +74,26 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.23.0",
-    "@genesislcap/genx": "15.23.0",
-    "@genesislcap/rollup-builder": "15.23.0",
-    "@genesislcap/ts-builder": "15.23.0",
-    "@genesislcap/uvu-playwright-builder": "15.23.0",
-    "@genesislcap/vite-builder": "15.23.0",
-    "@genesislcap/webpack-builder": "15.23.0",
+    "@genesislcap/foundation-testing": "15.23.1-FUI-0.4",
+    "@genesislcap/genx": "15.23.1-FUI-0.4",
+    "@genesislcap/rollup-builder": "15.23.1-FUI-0.4",
+    "@genesislcap/ts-builder": "15.23.1-FUI-0.4",
+    "@genesislcap/uvu-playwright-builder": "15.23.1-FUI-0.4",
+    "@genesislcap/vite-builder": "15.23.1-FUI-0.4",
+    "@genesislcap/webpack-builder": "15.23.1-FUI-0.4",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.23.0",
-    "@genesislcap/foundation-logger": "15.23.0",
-    "@genesislcap/foundation-notifications": "15.23.0",
-    "@genesislcap/foundation-redux": "15.23.0",
-    "@genesislcap/foundation-ui": "15.23.0",
-    "@genesislcap/foundation-utils": "15.23.0",
-    "@genesislcap/rapid-design-system": "15.23.0",
-    "@genesislcap/web-core": "15.23.0",
+    "@genesislcap/foundation-ai": "15.23.1-FUI-0.4",
+    "@genesislcap/foundation-logger": "15.23.1-FUI-0.4",
+    "@genesislcap/foundation-notifications": "15.23.1-FUI-0.4",
+    "@genesislcap/foundation-redux": "15.23.1-FUI-0.4",
+    "@genesislcap/foundation-ui": "15.23.1-FUI-0.4",
+    "@genesislcap/foundation-utils": "15.23.1-FUI-0.4",
+    "@genesislcap/rapid-design-system": "15.23.1-FUI-0.4",
+    "@genesislcap/web-core": "15.23.1-FUI-0.4",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },