@genesislcap/ai-assistant 15.19.6 → 15.20.0-alpha.3

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

@@ -1,4 +1,5 @@
 import { __rest } from "tslib";
+import { APPROX_CHARS_PER_TOKEN } from './context-tokens';
 /**
  * Tool-context condensation: collapse stale tool payloads out of the history
  * sent to the model, while leaving stored history untouched.
@@ -21,11 +22,6 @@ import { __rest } from "tslib";
 export const CONDENSE_MIN_CHARS = 1000;
 /** Key the collapsed args are stored under — a tool-call's args must stay a Record. */
 export const CONDENSED_ARGS_KEY = 'condensed';
-/**
- * Rough chars-per-token divisor for the `tokensSaved` estimate. No tokenizer is
- * available in this stack; ~4 chars/token is the usual English approximation.
- */
-const APPROX_CHARS_PER_TOKEN = 4;
 /** Short human-readable reason for the stub text, per fired trigger. */
 function triggerReason(trigger) {
     switch (trigger.kind) {
@@ -65,6 +61,38 @@ imageCount = 0) {
     const images = imageCount > 0 ? ` + ${imageCount} image${imageCount === 1 ? '' : 's'}` : '';
     return `[${tool}${key} — ${what} elided, ~${origLen} chars${images} (${triggerReason(trigger)})${restore}]`;
 }
+/**
+ * The replacement for a call's ARGS, in the shape args must keep. Shared by the request-time
+ * transform and {@link condenseForPersistence} so both render byte-identical stubs.
+ *
+ * Args must stay a Record, so every mode stashes its stub under a single key.
+ *
+ * GENC-1494: `drop` used to collapse args to a bare `{}`. That is indistinguishable from a call
+ * the model made with NO arguments, and the model reads its own history as fact: a ui-builder run
+ * saw its elided `vfs_write` calls as `vfs_write {}` beside a live
+ * `{"status":"buffered","path":"…"}` result, concluded it was calling the tool without content,
+ * and burned two hours re-writing files that were already correct. A bare marker is not enough
+ * either — it still fails to say WHICH file the call wrote, since `path` went with the args. So
+ * `drop` renders the same identifying stub as `pointer`, minus only the restore promise it cannot
+ * honour.
+ */
+function renderCondensedArgs(policy, tool, fired, origLen) {
+    return {
+        [CONDENSED_ARGS_KEY]: policy === 'drop' || policy === 'pointer'
+            ? condenseStub('args', tool, fired, origLen, policy === 'pointer')
+            : policy.replaceWith,
+    };
+}
+/**
+ * The replacement for a call's RESULT. Kept non-empty — Anthropic rejects empty `tool_result`
+ * content. Shared with {@link condenseForPersistence} for the same reason as
+ * {@link renderCondensedArgs}.
+ */
+function renderCondensedResult(policy, tool, fired, textLen, imageCount) {
+    return policy === 'drop' || policy === 'pointer'
+        ? condenseStub('response', tool, fired, textLen, policy === 'pointer', imageCount)
+        : policy.replaceWith;
+}
 /** Stable label for the `context.condensed` meta-event's `trigger` field. */
 function triggerLabel(trigger) {
     switch (trigger.kind) {
@@ -224,24 +252,9 @@ export function applyCondensation(history, policies, ctx, onCondensed) {
                 if (origLen < CONDENSE_MIN_CHARS)
                     return tc;
                 changed = true;
-                const result = entry.policy.args;
-                // Args must stay a Record, so every mode stashes its stub under a single key.
                 // Spread `tc` so providerMetadata (e.g. the Gemini reasoning signature that must
                 // round-trip) and UI fields survive.
-                //
-                // GENC-1494: `drop` used to collapse args to a bare `{}`. That is indistinguishable
-                // from a call the model made with NO arguments, and the model reads its own history
-                // as fact: a ui-builder run saw its elided `vfs_write` calls as `vfs_write {}` beside
-                // a live `{"status":"buffered","path":"…"}` result, concluded it was calling the tool
-                // without content, and burned two hours re-writing files that were already correct.
-                // A bare marker is not enough either — it still fails to say WHICH file the call
-                // wrote, since `path` went with the args. So `drop` renders the same identifying stub
-                // as `pointer`, minus only the restore promise it cannot honour.
-                const args = {
-                    [CONDENSED_ARGS_KEY]: result === 'drop' || result === 'pointer'
-                        ? condenseStub('args', tc.name, fired, origLen, result === 'pointer')
-                        : result.replaceWith,
-                };
+                const args = renderCondensedArgs(entry.policy.args, tc.name, fired, origLen);
                 if (!entry.reportedArgs) {
                     entry.reportedArgs = true;
                     const stubLen = JSON.stringify(args).length;
@@ -281,11 +294,8 @@ export function applyCondensation(history, policies, ctx, onCondensed) {
                 : undefined;
             if (entry && fired && origLen >= CONDENSE_MIN_CHARS) {
                 const tool = (_e = nameById.get(msg.toolResult.toolCallId)) !== null && _e !== void 0 ? _e : msg.toolResult.toolCallId;
-                const result = entry.policy.response; // `fired` is only set when response is declared
-                // Kept non-empty — Anthropic rejects empty tool_result content.
-                const content = result === 'drop' || result === 'pointer'
-                    ? condenseStub('response', tool, fired, textLen, result === 'pointer', images.length)
-                    : result.replaceWith;
+                // `fired` is only set when a response policy is declared, so the `!` holds.
+                const content = renderCondensedResult(entry.policy.response, tool, fired, textLen, images.length);
                 if (!entry.reportedResponse) {
                     entry.reportedResponse = true;
                     onCondensed({
@@ -308,3 +318,92 @@ export function applyCondensation(history, policies, ctx, onCondensed) {
         return msg;
     });
 }
+/**
+ * Project history for PERSISTENCE: collapse the payloads the model has **already** stopped
+ * seeing, using the same stubs it was sent (GENC-1566).
+ *
+ * `applyCondensation` leaves stored history whole on purpose, and that is right for the live
+ * transcript — but a host that WRITES the transcript to durable storage is then writing payloads
+ * the driver has already decided are spent, on every autosave, for the life of the project.
+ * Measured on one small Create session: 58,187 chars, 7.4% of a 790 KB session object, across
+ * five payloads the driver had condensed out of context to save 14,434 tokens. That session
+ * autosaved 86 times, so the bytes were written 86 times.
+ *
+ * **Deliberately dumber than {@link applyCondensation}, and that is the safety argument.** No
+ * clocks, no trigger evaluation, no events, no writes to the registry's latches. It reads only
+ * `reportedArgs` / `reportedResponse` — set when a payload was actually replaced by a stub — and
+ * `firedTrigger`, which is latched, so the stub it renders is byte-identical to the one the model
+ * received. It therefore cannot condense something the model can still see, and calling it is
+ * free of side effects: safe on a save path, and safe to call twice.
+ *
+ * What survives: `diag/`-style diagnostic streams keep the full payloads (they are a separate,
+ * chunked keyspace), and stored history in memory is untouched — this returns a copy. So the
+ * transcript a host RENDERS and the transcript a host STORES can differ, which is the point.
+ *
+ * **That divergence lasts only until the next reload, and the difference is user-visible** (PR
+ * #2495 review). Restore feeds the STORED transcript back into both the driver and the UI, so a
+ * resumed session renders the stubs: someone reopening a project sees
+ * `[read_context — result elided, ~26907 chars (agent finished)]` where the payload used to be,
+ * and the only route back to it is the debug-log download. That is the trade this function makes —
+ * 7.4% of a measured session object against a spent payload no longer being visible in a resumed
+ * transcript — and it is deliberate, but it is not invisible. Anyone handling a "where did my tool
+ * output go?" report should find the answer here.
+ *
+ * Returns `history` itself when there is nothing to collapse, so a caller that saves on every
+ * keystroke pays one walk and no allocation.
+ */
+export function condenseForPersistence(history, policies) {
+    var _a;
+    if (policies.size === 0)
+        return history;
+    // A tool message carries only an id, so the tool NAME for its stub comes from the call.
+    const nameById = new Map();
+    for (const msg of history) {
+        for (const tc of (_a = msg.toolCalls) !== null && _a !== void 0 ? _a : [])
+            nameById.set(tc.id, tc.name);
+    }
+    let changed = false;
+    const projected = history.map((msg) => {
+        var _a, _b, _c, _d, _e;
+        if ((_a = msg.toolCalls) === null || _a === void 0 ? void 0 : _a.length) {
+            let callsChanged = false;
+            const toolCalls = msg.toolCalls.map((tc) => {
+                var _a;
+                const entry = policies.get(tc.id);
+                if (!(entry === null || entry === void 0 ? void 0 : entry.reportedArgs) || !entry.firedTrigger || !entry.policy.args)
+                    return tc;
+                callsChanged = true;
+                const origLen = JSON.stringify((_a = tc.args) !== null && _a !== void 0 ? _a : {}).length;
+                return Object.assign(Object.assign({}, tc), { args: renderCondensedArgs(entry.policy.args, tc.name, entry.firedTrigger, origLen) });
+            });
+            // Returns unconditionally, matching `applyCondensation`'s equivalent branch
+            // (`return changed ? { ...msg, toolCalls } : msg`). A message can carry BOTH `toolCalls` and
+            // a `toolResult`, so falling through here would walk a result the request-time transform
+            // never reaches — safe today only because `reportedResponse` can be set by nothing except
+            // `applyCondensation`, which cannot reach it either. The whole safety argument for this
+            // function is that it renders the stub the model was already sent, so the control flow is
+            // held identical rather than resting on that coincidence (PR #2495 review).
+            if (callsChanged) {
+                changed = true;
+                return Object.assign(Object.assign({}, msg), { toolCalls });
+            }
+            return msg;
+        }
+        if (msg.toolResult) {
+            const entry = policies.get(msg.toolResult.toolCallId);
+            if ((entry === null || entry === void 0 ? void 0 : entry.reportedResponse) && entry.firedTrigger && entry.policy.response) {
+                changed = true;
+                const tool = (_b = nameById.get(msg.toolResult.toolCallId)) !== null && _b !== void 0 ? _b : msg.toolResult.toolCallId;
+                const images = (_c = msg.toolResult.attachments) !== null && _c !== void 0 ? _c : [];
+                const content = renderCondensedResult(entry.policy.response, tool, entry.firedTrigger, (_e = (_d = msg.toolResult.content) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0, images.length);
+                // `attachments` is dropped rather than spread through, exactly as the request-time
+                // transform drops it: the stub says the payload was elided, and keeping the base64
+                // would both make that a lie and shed none of the bytes this exists to shed.
+                const _f = msg.toolResult, { attachments: _elided } = _f, restOfResult = __rest(_f, ["attachments"]);
+                return Object.assign(Object.assign({}, msg), { toolResult: Object.assign(Object.assign({}, restOfResult), { content }) });
+            }
+        }
+        return msg;
+    });
+    return changed ? projected : history;
+}

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

@@ -0,0 +1,339 @@
+/**
+ * Context-window accounting (GENC-1567) — estimating how much of the model's
+ * context each message occupies, so compaction can be sized in the unit that
+ * actually matters and a gate can promise a reclaim before spending a
+ * summarizer call.
+ *
+ * The estimates here are deliberately **conservative** (biased to over-count).
+ * They feed a gate that blocks sending: over-counting costs a little unused
+ * headroom, under-counting lets a turn overflow, which is the failure this
+ * whole feature exists to prevent.
+ */
+/**
+ * Fallback ratio for messages with no measured anchor nearby. Shared with
+ * `condense-history.ts`, which uses it for the same purpose (reporting bytes
+ * shed as tokens) — one definition so the two never drift.
+ */
+export const APPROX_CHARS_PER_TOKEN = 4;
+/**
+ * Flat per-image allowance. Both vendors price an image by its pixel area
+ * (Anthropic ≈ `w × h / 750`), and a `ChatImageAttachment` carries only base64
+ * bytes — no dimensions — so there is nothing to compute from. This stands in
+ * for a mid-size screenshot and is intentionally on the high side: an image is
+ * the one payload compaction cannot shrink (it is dropped, never summarized),
+ * so under-counting images is exactly how a projected reclaim comes up short.
+ */
+const IMAGE_TOKEN_ESTIMATE = 1600;
+/** Per-message role/framing overhead every transport adds around the content. */
+const PER_MESSAGE_FRAMING_TOKENS = 4;
+/**
+ * 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
+ * concise prose, but the length is the model's choice, so this is a ceiling
+ * rather than an average — a projection that under-estimates the summary is a
+ * gate that promises a reclaim it cannot deliver.
+ */
+export const COMPACTION_SUMMARY_TOKEN_ESTIMATE = 1200;
+/**
+ * Whether a message contributes to the provider request at all.
+ *
+ * Exported because the cut logic needs the same answer: a boundary is judged by
+ * what the provider will actually see, so a display-only row sitting between an
+ * `assistant(toolCalls)` and its results must not be mistaken for a safe split.
+ *
+ * Mirrors what the request-build chokepoint and the transports actually send:
+ * `system-event` / `synthetic-user` are display-only rows, and the
+ * reasoning/narration splits (GENC-1410, plus the legacy `thinking` flag they
+ * superseded) are skipped when building the request. Counting any of them would
+ * inflate every estimate against a prompt that never carries them.
+ */
+export function reachesProvider(m) {
+    if (m.role === 'system-event' || m.role === 'synthetic-user')
+        return false;
+    if (m.category === 'reasoning' || m.category === 'narration')
+        return false;
+    return !m.thinking;
+}
+/** Images on a message — both the user-attached kind and the kind a tool handed back. */
+function imageCount(m) {
+    var _a, _b, _c, _d, _e;
+    const onMessage = (_b = (_a = m.attachments) === null || _a === void 0 ? void 0 : _a.filter((a) => a.kind === 'image').length) !== null && _b !== void 0 ? _b : 0;
+    const onResult = (_e = (_d = (_c = m.toolResult) === null || _c === void 0 ? void 0 : _c.attachments) === null || _d === void 0 ? void 0 : _d.filter((a) => a.kind === 'image').length) !== null && _e !== void 0 ? _e : 0;
+    return onMessage + onResult;
+}
+/** Framing a text attachment adds on the wire: `[File: ` + `]\n`. */
+const TEXT_ATTACHMENT_FRAMING_CHARS = 9;
+/**
+ * Characters this message puts on the wire: prose, text-attachment contents,
+ * tool-call names and serialized arguments, and tool-result content.
+ *
+ * **Text attachments are counted here, not by `imageCount`.** A `kind: 'text'`
+ * attachment is sent verbatim as `[File: <name>]\n<content>` — it is ordinary
+ * prompt text, and a picked file can be megabytes of it. Charging only for
+ * images made the single largest sanctioned input invisible to every estimate,
+ * so both the composer gate and the mid-loop guard waved it straight through:
+ * the exact overrun they exist to catch. Note `kind` is OPTIONAL on the text arm
+ * (attachments authored before images existed carry none), so anything that is
+ * not explicitly an image is text.
+ *
+ * `toolResult.attachments` is deliberately not walked for text: that field is
+ * typed image-only, because a text attachment there would be indistinguishable
+ * from `toolResult.content` and the transports drop it rather than double-send.
+ *
+ * `toolCall.subAgentTrace` is deliberately not counted either — it hangs off the
+ * tool call for the UI's benefit and is never sent, so counting it would
+ * attribute a whole sub-agent transcript to the parent's context.
+ */
+function wireChars(m) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    let chars = (_b = (_a = m.content) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0;
+    for (const attachment of (_c = m.attachments) !== null && _c !== void 0 ? _c : []) {
+        if (attachment.kind === 'image')
+            continue;
+        chars +=
+            TEXT_ATTACHMENT_FRAMING_CHARS + attachment.name.length + ((_e = (_d = attachment.content) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0);
+    }
+    for (const tc of (_f = m.toolCalls) !== null && _f !== void 0 ? _f : []) {
+        chars += tc.name.length;
+        try {
+            chars += JSON.stringify((_g = tc.args) !== null && _g !== void 0 ? _g : {}).length;
+        }
+        catch (_l) {
+            // Circular or otherwise unserializable args: skip rather than throw. The
+            // framing allowance below still counts the call itself.
+        }
+    }
+    chars += (_k = (_j = (_h = m.toolResult) === null || _h === void 0 ? void 0 : _h.content) === null || _j === void 0 ? void 0 : _j.length) !== null && _k !== void 0 ? _k : 0;
+    return chars;
+}
+/** Char-derived token estimate for one message, before any measured calibration. */
+function baselineTokens(m) {
+    if (!reachesProvider(m))
+        return 0;
+    return (Math.ceil(wireChars(m) / APPROX_CHARS_PER_TOKEN) +
+        imageCount(m) * IMAGE_TOKEN_ESTIMATE +
+        PER_MESSAGE_FRAMING_TOKENS);
+}
+/**
+ * True creation time of the compaction that produced this history, if any.
+ *
+ * Read from `compaction.createdAt` rather than the summary's `timestamp`, which
+ * is deliberately backdated to the covered region's start so the summary sorts to
+ * the head of chronological views.
+ */
+function compactedAtOf(history) {
+    var _a, _b;
+    return (_b = (_a = history.find((m) => m.role === 'compacted-summary')) === null || _a === void 0 ? void 0 : _a.compaction) === null || _b === void 0 ? void 0 : _b.createdAt;
+}
+/**
+ * Whether a message's `inputTokens` still describes the history being sent.
+ *
+ * A measurement is only meaningful against the history that produced it, and
+ * compaction rewrites that history underneath the tail it keeps. Every retained
+ * message was appended before the compaction ran, so an older measurement is
+ * describing a transcript that no longer exists — and it is describing a much
+ * BIGGER one, which is what made trusting it a dead end rather than a rounding
+ * error (GENC-1567).
+ *
+ * A measurement with no timestamp is rejected once a compaction is present: its
+ * age is unknowable, and falling back to the character estimate is the safer of
+ * the two wrong answers.
+ */
+function usableAnchor(m, compactedAt) {
+    if (m.inputTokens == null)
+        return false;
+    if (!compactedAt)
+        return true;
+    return !!m.timestamp && m.timestamp >= compactedAt;
+}
+/** Index of the first message carrying a usable measurement, or `-1`. */
+function firstAnchor(history, compactedAt) {
+    return history.findIndex((m) => usableAnchor(m, compactedAt));
+}
+/**
+ * Whether anything about this transcript's size is knowable.
+ *
+ * The gate's "should I have an opinion at all?" question. Deliberately broader
+ * than "is there a USABLE anchor": a compaction invalidates every retained
+ * measurement, which is the normal state immediately after one runs, and gating
+ * the recompute on a usable anchor there meant no assignment at all — leaving a
+ * blocked figure latched on a conversation that had just shrunk. That is the very
+ * dead end this machinery exists to prevent, so the question has to be whether the
+ * transcript was EVER measured, not whether the measurement is still good.
+ *
+ * When it is true, {@link estimateContextTokens} is the figure to use — it drops
+ * the invalidated anchors itself and falls back to characters, which is still the
+ * truth about the current history and, crucially, is not the stale number.
+ *
+ * A `compacted-summary` counts on its own: a conversation only reaches one by
+ * being large, and a compaction can summarise away every measured turn.
+ *
+ * When it is false nothing has ever reported usage, and the honest answer is to
+ * leave the gate inert rather than let a character estimate invent a percentage.
+ */
+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}.
+ */
+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;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+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);
+}
+/**
+ * Total estimated context for a transcript — the preamble plus every message.
+ *
+ * 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.
+ */
+export function estimateContextTokens(history) {
+    const estimates = estimateMessageTokens(history);
+    let total = estimateSystemOverhead(history);
+    for (const t of estimates)
+        total += t;
+    return total;
+}
+/**
+ * Estimated size of the request that will actually be SENT, given the stored
+ * history it was derived from.
+ *
+ * The two differ by design and can differ by a lot. `condenseWhen` replaces spent
+ * tool payloads with short stubs, and multi-agent masking blanks another agent's
+ * payloads — both on a copy, leaving stored history full-fat for the UI and the
+ * 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.
+ */
+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);
+    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));
+}
+/**
+ * Project the effect of compacting at `cut`, WITHOUT running the summarizer.
+ *
+ * This is what lets a gate tell the difference between "compaction will unblock
+ * you" and "compaction will spend a call and leave you exactly where you are" —
+ * a distinction the old boolean `canCompact()` could not express, because it
+ * answered only whether a legal cut existed. A legal cut that covers four short
+ * messages while a large tool loop sits in the tail is legal and useless.
+ *
+ * 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);
+    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 tokensAfter = overhead + summaryTokens + tail;
+    return {
+        cut,
+        compactedCount: cut,
+        tokensBefore,
+        tokensAfter,
+        reclaimed: Math.max(0, tokensBefore - tokensAfter),
+    };
+}

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

@@ -1,4 +1,5 @@
 import { __rest } from "tslib";
+import { 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
@@ -40,32 +41,113 @@ export function applyHistoryCap(history, cap) {
     const cutoff = history.length - cap;
     return history.map((msg, i) => (i < cutoff ? maskToolPayload(msg) : msg));
 }
-// ───────────────────────────── Compaction (GENC-1351 §5.7) ─────────────────────────────
-/** Recent messages kept verbatim when compacting; everything earlier is summarized. */
-export const COMPACT_KEEP_RECENT_MESSAGES = 4;
-/** Don't bother compacting unless at least this many messages would be summarized. */
-export const COMPACT_MIN_MESSAGES_TO_COMPACT = 4;
+// ───────────────────────────── Compaction (GENC-1351 §5.7, GENC-1567) ─────────────────────────────
 /**
- * Index at which the verbatim tail begins — everything before it gets summarized.
- * The tail starts on a clean turn boundary (a `user` message): a user message
- * never appears between a `tool_use` and its `tool_result`, so cutting there
- * guarantees the summarized region is tool-pair-balanced (compaction only runs
- * when idle, so history is turn-complete). Returns `null` when there is nothing
- * worth compacting (too short, or no earlier user boundary) — e.g. a freshly
- * restored session whose only user turn is the current one.
+ * Default size of the verbatim tail a compaction leaves behind, in tokens —
+ * MESSAGES only, since the system preamble is not something compaction can
+ * remove. A caller with a resolved context limit should pass a budget derived
+ * from it rather than relying on this.
  */
-export function findCompactionCut(history) {
-    if (history.length < COMPACT_KEEP_RECENT_MESSAGES + COMPACT_MIN_MESSAGES_TO_COMPACT) {
+export const DEFAULT_TAIL_TOKEN_BUDGET = 30000;
+/**
+ * Default floor on what a compaction must reclaim to be worth running. Below
+ * this the summarizer call costs more than the space it buys — and, crucially,
+ * a gate that offered compaction as its escape would be promising a reclaim
+ * that does not clear the gate.
+ */
+export const DEFAULT_MIN_RECLAIM_TOKENS = 5000;
+/**
+ * Whether cutting at `i` — summarizing `[0, i)` and keeping `[i, end)` verbatim
+ * — leaves a request the provider will accept.
+ *
+ * The one hard constraint is tool pairing: a `tool_result` whose `tool_use` was
+ * summarized away is rejected outright by every provider. So the first message
+ * the tail actually SENDS must not be a tool result.
+ *
+ * This replaces the old "cut only on a `user` message" rule (GENC-1351), which
+ * was a proxy for the same invariant — a user message never appears between a
+ * tool call and its results, so it was guaranteed safe without any pairing
+ * check. The proxy was sound but far too narrow: an agentic tool loop contains
+ * no user messages at all, so the whole loop was one indivisible block and a
+ * runaway turn could not be compacted at any point. Checking the invariant
+ * directly opens up every gap between tool groups (GENC-1567).
+ *
+ * Display-only rows are skipped when looking for that first sent message: a
+ * `system-event` (e.g. "Stopped.") sitting between an `assistant(toolCalls)` and
+ * its results reaches no transport, so cutting in front of it would still orphan
+ * the results behind it.
+ */
+export function isSafeCompactionCut(history, i) {
+    if (i <= 0 || i >= history.length)
+        return false;
+    for (let j = i; j < history.length; j += 1) {
+        if (!reachesProvider(history[j]))
+            continue;
+        return history[j].role !== 'tool';
+    }
+    // A tail of nothing but display-only rows sends no tool result, so nothing can
+    // be orphaned.
+    return true;
+}
+/**
+ * Index at which the verbatim tail begins — everything before it gets summarized
+ * — chosen so the tail fits `tailTokenBudget` (GENC-1567).
+ *
+ * Walks back from the end accumulating estimated tokens until the next message
+ * would overrun the budget, then snaps FORWARD to the nearest safe boundary.
+ * Forward is the correct direction: it can only shrink the tail, so the budget
+ * still holds after the snap, whereas snapping backwards could blow it.
+ *
+ * Returns `null` when the whole transcript already fits (nothing worth doing) or
+ * when no safe boundary exists ahead of the walk — e.g. a tail that is one
+ * 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);
+    let messagesTotal = 0;
+    for (const t of estimates)
+        messagesTotal += t;
+    if (messagesTotal <= tailTokenBudget)
         return null;
+    let tail = 0;
+    let raw = history.length;
+    for (let i = history.length - 1; i > 0; i -= 1) {
+        if (tail + estimates[i] > tailTokenBudget)
+            break;
+        tail += estimates[i];
+        raw = i;
     }
-    const target = history.length - COMPACT_KEEP_RECENT_MESSAGES;
-    for (let i = target; i > 0; i -= 1) {
-        if (history[i].role === 'user') {
-            return i >= COMPACT_MIN_MESSAGES_TO_COMPACT ? i : null;
-        }
+    for (let i = raw; i < history.length; i += 1) {
+        if (isSafeCompactionCut(history, i))
+            return i;
     }
     return null;
 }
+/**
+ * The single answer to "what would compacting do right now, and is it worth it?"
+ *
+ * Every consumer reads this one function — the menu's enabled state, its
+ * tooltip, the gate's banner copy, and the action itself — so the affordance can
+ * never promise something the action does not deliver. That is the same
+ * one-source-of-truth argument that produced `canCompact()` (the GENC-1351
+ * follow-up which stopped the gate reading a different history from the action);
+ * this extends it from *legality* to *sufficiency*, which is what a blocking
+ * gate needs. A legal cut that covers four short messages while a large tool
+ * loop sits in the tail is legal and useless, and the old boolean could not say
+ * so.
+ *
+ * Returns `null` when there is no safe cut, or when the projected reclaim does
+ * not clear `minReclaimTokens`.
+ */
+export function planCompaction(history, options = {}) {
+    const { tailTokenBudget = DEFAULT_TAIL_TOKEN_BUDGET, minReclaimTokens = DEFAULT_MIN_RECLAIM_TOKENS, } = options;
+    const cut = findCompactionCut(history, tailTokenBudget);
+    if (cut == null)
+        return null;
+    const projection = projectCompaction(history, cut);
+    return projection.reclaimed >= minReclaimTokens ? projection : null;
+}
 /** One-line rendering of a message for the summarizer transcript. */
 function renderMessageForSummary(m) {
     var _a;