@corenel/harness 0.7.4 → 0.8.0

package/dist/conversation.d.ts

@@ -14,5 +14,20 @@ export interface ConversationTurn {
     messages: ChatCompletionMessageParam[];
     /** Token/cost/latency for the assistant response, once the turn settles. */
     stats?: TurnStats;
+    /** Set on a COMPACTION SEAM: the checkpoint body the summarizer produced for
+     * the stretch this seam replaced. Carried on the turn rather than left to a
+     * file because the question a seam raises ("what did it keep?") is a question
+     * about the conversation in front of you, and because the file only exists
+     * for a run that had a session to write beside. Absent on every other turn. */
+    checkpoint?: string;
 }
+/** Is this turn a COMPACTION SEAM rather than something said?
+ *
+ * Recognized by the marker the harness writes into the window, so a surface
+ * cannot look for one string while the loop writes another. Lives here, beside
+ * the type, because three consumers need it now -- the transcript draws the
+ * seam, the context panel counts seams and must keep them OUT of the window it
+ * reports (a seam is an unsent note; counting it would inflate the very number
+ * the panel exists to give), and the runtime writes them. */
+export declare function isCheckpointTurn(t: ConversationTurn): boolean;
 //# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;+EAC+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB"}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAGpF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;+EAC+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;mFAI+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;6DAO6D;AAC7D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAG7D"}

package/dist/conversation.js

@@ -1,2 +1,14 @@
-export {};
+import { CHECKPOINT_MARKER } from './core/compactHistory.js';
+/** Is this turn a COMPACTION SEAM rather than something said?
+ *
+ * Recognized by the marker the harness writes into the window, so a surface
+ * cannot look for one string while the loop writes another. Lives here, beside
+ * the type, because three consumers need it now -- the transcript draws the
+ * seam, the context panel counts seams and must keep them OUT of the window it
+ * reports (a seam is an unsent note; counting it would inflate the very number
+ * the panel exists to give), and the runtime writes them. */
+export function isCheckpointTurn(t) {
+    const first = t.messages[0];
+    return typeof first?.content === 'string' && first.content.startsWith(CHECKPOINT_MARKER);
+}
 //# sourceMappingURL=conversation.js.map

package/dist/conversation.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":""}
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AA0B1D;;;;;;;6DAO6D;AAC7D,MAAM,UAAU,gBAAgB,CAAC,CAAmB;IAClD,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,OAAO,OAAO,KAAK,EAAE,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AAC3F,CAAC"}

package/dist/core/compactHistory.d.ts

@@ -0,0 +1,84 @@
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+export interface CompactHistoryOptions {
+    /** Summarizes the collapsed stretch. Injected so the partitioning is testable
+     * without a model call. */
+    summarize: (collapsed: ChatCompletionMessageParam[]) => Promise<string>;
+    /** Produces the one-line referent for a preserved user message: what it was
+     * answering. `answered` is the nearest preceding assistant turn, or null when
+     * the user opened the conversation. Omit to preserve user messages bare. */
+    anchor?: (user: ChatCompletionMessageParam, answered: ChatCompletionMessageParam | null) => Promise<string>;
+    /** Byte size past which a user message's own content is offloaded rather than
+     * kept inline. Requires `offload`. */
+    offloadOverBytes?: number;
+    /** Records oversized user content and returns the pointer to leave in its
+     * place — the same treatment rung 1 gives an oversized tool result. */
+    offload?: (content: string) => Promise<string>;
+}
+export interface CompactHistoryResult {
+    /** The rebuilt message array to send from here on. */
+    messages: ChatCompletionMessageParam[];
+    /** The durable checkpoint body, destined for a file in the project. */
+    checkpoint: string;
+}
+/** The marker every checkpoint message starts with, so a later pass can
+ * recognize one it already wrote instead of collapsing it again. */
+export declare const CHECKPOINT_MARKER = "[checkpoint] ";
+/** The marker every anchor message starts with. An anchor is context ABOUT the
+ * user message that follows it, not something the assistant said. */
+export declare const ANCHOR_MARKER = "[anchor] ";
+/** Window fill ratio at which history compaction becomes worth its cost.
+ * High on purpose: see the one-shot reasoning at the top of this file. */
+export declare const COMPACT_AT_FILL = 0.86;
+/** Whether compacting now is worth rewriting the cached prefix. Two gates: the
+ * window is genuinely close to full, AND there is bulk to remove. A compaction
+ * that reduces nothing still invalidates the whole prefix, so "nothing to
+ * collapse" is a refusal, not a no-op. */
+export declare function shouldCompact(fill: number, messages: ChatCompletionMessageParam[]): boolean;
+/** Fill must fall back below this before compaction re-arms. */
+export declare const REARM_BELOW_FILL = 0.6;
+/** How much the window must refill, ABOVE where the last compaction left it,
+ * for another compaction to be worth its cost. */
+export declare const REARM_ON_REGROWTH = 0.1;
+/** The latch's state between turns.
+ *
+ * `floor` is the fill measured just after the last compaction -- how far down
+ * it actually got. Null means either nothing has compacted yet or the next
+ * usage reading has not arrived, and the gate falls back to the absolute rule
+ * until it has. It is deliberately taken from a REAL reading rather than
+ * estimateFill: it is compared against real readings, and mixing an estimate
+ * into one side of that comparison would bias every re-arm after it. */
+export interface CompactGate {
+    armed: boolean;
+    floor: number | null;
+}
+/** The gate's state the moment a compaction has run: shut, and waiting for the
+ * next usage reading to tell it how far down that compaction got. */
+export declare function afterCompaction(): CompactGate;
+/** Window fill ratio read from the messages themselves.
+ *
+ * For the one turn where no usage reading exists: `fill` comes from the
+ * PREVIOUS response, so it is 0 on turn 1 and the gate could never fire before
+ * the first request. A run resuming an already-oversized conversation
+ * therefore put it on the wire uncompacted and took the fatal 400 immediately
+ * -- the case that needs rung 2 most was the case it could not run in.
+ *
+ * Reads low: the request also carries tool schemas, which are not visible
+ * here. That is the right direction to be wrong in, since the cost of reading
+ * high is a compaction nobody needed. */
+export declare function estimateFill(messages: ChatCompletionMessageParam[], contextWindow: number | undefined): number;
+export declare function compactionDecision(fill: number, messages: ChatCompletionMessageParam[], gate: CompactGate): {
+    compact: boolean;
+    next: CompactGate;
+};
+export declare function compactHistory(messages: ChatCompletionMessageParam[], opts: CompactHistoryOptions): Promise<CompactHistoryResult>;
+/** An anchor or checkpoint a compaction wrote — bookkeeping ABOUT the
+ * conversation rather than part of it. Exported because a caller that has to
+ * tell "what this run added" from "what a rewrite inserted" cannot do it by
+ * position: a rewrite puts fresh objects into the array at arbitrary places. */
+export declare const isCompactionMarker: typeof isOwnMarker;
+/** An anchor or checkpoint this module wrote on an earlier pass. Dropped and
+ * rewritten each time rather than accumulated: the newest checkpoint already
+ * subsumes what the older ones recorded. */
+declare function isOwnMarker(m: ChatCompletionMessageParam): boolean;
+export {};
+//# sourceMappingURL=compactHistory.d.ts.map

package/dist/core/compactHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactHistory.d.ts","sourceRoot":"","sources":["../../core/compactHistory.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,MAAM,WAAW,qBAAqB;IACpC;+BAC2B;IAC3B,SAAS,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxE;;gFAE4E;IAC5E,MAAM,CAAC,EAAE,CACP,IAAI,EAAE,0BAA0B,EAChC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,KACxC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB;0CACsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;2EACuE;IACvE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;oEACoE;AACpE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;qEACqE;AACrE,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;0EAC0E;AAC1E,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;0CAG0C;AAC1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,0BAA0B,EAAE,GAAG,OAAO,CAG3F;AAED,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;kDACkD;AAClD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;wEAOwE;AACxE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;qEACqE;AACrE,wBAAgB,eAAe,IAAI,WAAW,CAE7C;AAyBD;;;;;;;;;;yCAUyC;AACzC,wBAAgB,YAAY,CAAC,QAAQ,EAAE,0BAA0B,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9G;AA+BD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,0BAA0B,EAAE,EACtC,IAAI,EAAE,WAAW,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAQzC;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,0BAA0B,EAAE,EACtC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAyC/B;AAeD;;;gFAGgF;AAChF,eAAO,MAAM,kBAAkB,oBAAc,CAAC;AAE9C;;4CAE4C;AAC5C,iBAAS,WAAW,CAAC,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAG3D"}

package/dist/core/compactHistory.js

@@ -0,0 +1,191 @@
+/* Rung 2 of the context ladder: one-shot history compaction.
+ *
+ * Rung 1 (compression.ts) offloads ONE oversized tool result at a time and is
+ * lossless. This is the other half: when the window is genuinely close to full,
+ * collapse the conversation's bulk in a single structural step.
+ *
+ * It is deliberately NOT incremental. Every form of history compression
+ * invalidates the provider's cached prefix — the cache is a prefix, so touching
+ * any byte of it recomputes everything after it at full price. A compactor that
+ * trims a little each turn therefore pays full reprocessing every turn and saves
+ * almost nothing. One shot, high threshold, large payoff. */
+/** The marker every checkpoint message starts with, so a later pass can
+ * recognize one it already wrote instead of collapsing it again. */
+export const CHECKPOINT_MARKER = '[checkpoint] ';
+/** The marker every anchor message starts with. An anchor is context ABOUT the
+ * user message that follows it, not something the assistant said. */
+export const ANCHOR_MARKER = '[anchor] ';
+/** Window fill ratio at which history compaction becomes worth its cost.
+ * High on purpose: see the one-shot reasoning at the top of this file. */
+export const COMPACT_AT_FILL = 0.86;
+/** Whether compacting now is worth rewriting the cached prefix. Two gates: the
+ * window is genuinely close to full, AND there is bulk to remove. A compaction
+ * that reduces nothing still invalidates the whole prefix, so "nothing to
+ * collapse" is a refusal, not a no-op. */
+export function shouldCompact(fill, messages) {
+    if (fill < COMPACT_AT_FILL)
+        return false;
+    return messages.some((m) => m.role !== 'system' && m.role !== 'user');
+}
+/** Fill must fall back below this before compaction re-arms. */
+export const REARM_BELOW_FILL = 0.6;
+/** How much the window must refill, ABOVE where the last compaction left it,
+ * for another compaction to be worth its cost. */
+export const REARM_ON_REGROWTH = 0.1;
+/** The gate's state the moment a compaction has run: shut, and waiting for the
+ * next usage reading to tell it how far down that compaction got. */
+export function afterCompaction() {
+    return { armed: false, floor: null };
+}
+/* ~4 characters per token, matching estimateFactTokens in memory/tier.ts and
+ * the chars/4 fallback in @corenel/ui-kit. A BPE count is not worth a
+ * dependency for a number whose whole job is to be approximately right. */
+function messageChars(m) {
+    let n = 0;
+    const content = m.content;
+    if (typeof content === 'string')
+        n += content.length;
+    else if (Array.isArray(content)) {
+        for (const part of content) {
+            const text = part.text;
+            if (typeof text === 'string')
+                n += text.length;
+        }
+    }
+    /* Tool-call arguments ARE the bulk of an agent conversation and live beside
+     * `content`, not in it. Leaving them out would make this read near zero on
+     * exactly the histories it exists to catch. */
+    const calls = m.tool_calls;
+    if (Array.isArray(calls)) {
+        for (const c of calls)
+            n += (c.function?.name?.length ?? 0) + (c.function?.arguments?.length ?? 0);
+    }
+    return n;
+}
+/** Window fill ratio read from the messages themselves.
+ *
+ * For the one turn where no usage reading exists: `fill` comes from the
+ * PREVIOUS response, so it is 0 on turn 1 and the gate could never fire before
+ * the first request. A run resuming an already-oversized conversation
+ * therefore put it on the wire uncompacted and took the fatal 400 immediately
+ * -- the case that needs rung 2 most was the case it could not run in.
+ *
+ * Reads low: the request also carries tool schemas, which are not visible
+ * here. That is the right direction to be wrong in, since the cost of reading
+ * high is a compaction nobody needed. */
+export function estimateFill(messages, contextWindow) {
+    if (!contextWindow || contextWindow <= 0)
+        return 0;
+    let chars = 0;
+    for (const m of messages)
+        chars += messageChars(m);
+    return Math.min(1, chars / 4 / contextWindow);
+}
+/* The gate, with hysteresis.
+ *
+ * `shouldCompact` alone says "the window is full and there is bulk" — which
+ * stays TRUE on the turn after a compaction, and the one after that. A real
+ * run against a live model compacted over and over for exactly that reason,
+ * paying a full cached-prefix rewrite each time: the trickle failure this
+ * module's own header argues against, reintroduced by the missing edge.
+ *
+ * So the gate is a latch, not a predicate. It fires once at COMPACT_AT_FILL,
+ * disarms, and re-arms only once another compaction would be worth its cost.
+ *
+ * RE-ARMING ON PROGRESS, NOT ON A MARK. The first version re-armed only below
+ * REARM_BELOW_FILL, which assumed a compaction always drains past that mark.
+ * Nothing guarantees it: this codebase keeps EVERY user message verbatim, so a
+ * compaction's floor is system + all user turns + the checkpoint, and in a long
+ * conversation with large pastes that clears 0.6 easily. Landing anywhere in
+ * [0.6, 0.86) left the latch stuck SHUT FOREVER -- fill only grows from there,
+ * so it could never fall back under the mark, and the run compacted exactly
+ * once before marching into the wall it was supposed to prevent. Silently: a
+ * gate that never fires looks identical to a conversation that never got big.
+ *
+ * So the question is not "how full is the window" but "has it grown enough
+ * since the last compaction to have something new to collapse". Growth of
+ * REARM_ON_REGROWTH past that floor means yes, whatever the absolute level.
+ * The drained-window rule is kept alongside it: it is the cheapest possible
+ * signal and stays correct. Between the marks, with nothing new accumulated,
+ * the gate still does nothing -- which remains the right answer, because a
+ * second compaction so soon has almost nothing left to remove and would charge
+ * a full prefix rewrite to discover that. */
+export function compactionDecision(fill, messages, gate) {
+    if (!gate.armed) {
+        const drained = fill < REARM_BELOW_FILL;
+        const regrown = gate.floor !== null && fill >= gate.floor + REARM_ON_REGROWTH;
+        return { compact: false, next: { ...gate, armed: drained || regrown } };
+    }
+    if (!shouldCompact(fill, messages))
+        return { compact: false, next: gate };
+    return { compact: true, next: afterCompaction() };
+}
+export async function compactHistory(messages, opts) {
+    // A trailing assistant message that has asked for tools but not yet been
+    // answered is held back from the collapse: the loop appends its `tool`
+    // results next, and those results need this parent to exist or the provider
+    // rejects the request with a fatal 400.
+    const tail = messages.length ? messages[messages.length - 1] : undefined;
+    const pending = tail && isUnansweredToolCall(tail) ? tail : null;
+    const body = pending ? messages.slice(0, -1) : messages;
+    const system = body.filter((m) => m.role === 'system');
+    const collapsed = body.filter((m) => m.role !== 'system' && m.role !== 'user');
+    const kept = [];
+    let answered = null;
+    for (const m of body) {
+        /* Skip THIS MODULE'S OWN messages, both as anchor candidates and as
+         * things to re-anchor. An anchor is an assistant message with string
+         * content, so a naive walk picks up the previous compaction's anchors and
+         * anchors those — a real run produced
+         * "[anchor] answering: [anchor] answering: [anchor] answering: ...".
+         * These are bookkeeping about the conversation, not part of it. */
+        if (isOwnMarker(m))
+            continue;
+        if (m.role === 'assistant' && typeof m.content === 'string')
+            answered = m;
+        if (m.role !== 'user')
+            continue;
+        if (opts.anchor) {
+            kept.push({ role: 'assistant', content: `${ANCHOR_MARKER}${await opts.anchor(m, answered)}` });
+        }
+        kept.push(await offloadIfOversized(m, opts));
+    }
+    const summary = await opts.summarize(collapsed);
+    return {
+        messages: [
+            ...system,
+            { role: 'assistant', content: `${CHECKPOINT_MARKER}${summary}` },
+            ...kept,
+            ...(pending ? [pending] : []),
+        ],
+        checkpoint: summary,
+    };
+}
+/** A user turn's DECISION text is small and stays verbatim; a pasted log is
+ * bulk and gets rung 1's treatment. Anything that is not oversized plain text
+ * is returned untouched. */
+async function offloadIfOversized(m, opts) {
+    const limit = opts.offloadOverBytes;
+    if (!opts.offload || limit === undefined)
+        return m;
+    if (typeof m.content !== 'string' || m.content.length <= limit)
+        return m;
+    return { ...m, content: await opts.offload(m.content) };
+}
+/** An anchor or checkpoint a compaction wrote — bookkeeping ABOUT the
+ * conversation rather than part of it. Exported because a caller that has to
+ * tell "what this run added" from "what a rewrite inserted" cannot do it by
+ * position: a rewrite puts fresh objects into the array at arbitrary places. */
+export const isCompactionMarker = isOwnMarker;
+/** An anchor or checkpoint this module wrote on an earlier pass. Dropped and
+ * rewritten each time rather than accumulated: the newest checkpoint already
+ * subsumes what the older ones recorded. */
+function isOwnMarker(m) {
+    if (m.role !== 'assistant' || typeof m.content !== 'string')
+        return false;
+    return m.content.startsWith(ANCHOR_MARKER) || m.content.startsWith(CHECKPOINT_MARKER);
+}
+function isUnansweredToolCall(m) {
+    return m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length > 0;
+}
+//# sourceMappingURL=compactHistory.js.map

package/dist/core/compactHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactHistory.js","sourceRoot":"","sources":["../../core/compactHistory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;6DAU6D;AA8B7D;oEACoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD;qEACqE;AACrE,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;0EAC0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;0CAG0C;AAC1C,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,QAAsC;IAChF,IAAI,IAAI,GAAG,eAAe;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;AACxE,CAAC;AAED,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC;kDACkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAerC;qEACqE;AACrE,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAED;;2EAE2E;AAC3E,SAAS,YAAY,CAAC,CAA6B;IACjD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,MAAM,OAAO,GAAI,CAA2B,CAAC,OAAO,CAAC;IACrD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC;SAChD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI,CAAC;YAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC;QACjD,CAAC;IACH,CAAC;IACD;;mDAE+C;IAC/C,MAAM,KAAK,GAAI,CAA6E,CAAC,UAAU,CAAC;IACxG,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;yCAUyC;AACzC,MAAM,UAAU,YAAY,CAAC,QAAsC,EAAE,aAAiC;IACpG,IAAI,CAAC,aAAa,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACnD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CA4B6C;AAC7C,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,QAAsC,EACtC,IAAiB;IAEjB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,IAAI,GAAG,gBAAgB,CAAC;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,iBAAiB,CAAC;QAC9E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,IAAI,OAAO,EAAE,EAAE,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC1E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAsC,EACtC,IAA2B;IAE3B,yEAAyE;IACzE,uEAAuE;IACvE,4EAA4E;IAC5E,wCAAwC;IACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAExD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IAE/E,MAAM,IAAI,GAAiC,EAAE,CAAC;IAC9C,IAAI,QAAQ,GAAsC,IAAI,CAAC;IACvD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB;;;;;2EAKmE;QACnE,IAAI,WAAW,CAAC,CAAC,CAAC;YAAE,SAAS;QAC7B,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;YAAE,QAAQ,GAAG,CAAC,CAAC;QAC1E,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAChC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,aAAa,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,kBAAkB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAEhD,OAAO;QACL,QAAQ,EAAE;YACR,GAAG,MAAM;YACT,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,iBAAiB,GAAG,OAAO,EAAE,EAAE;YAChE,GAAG,IAAI;YACP,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B;QACD,UAAU,EAAE,OAAO;KACpB,CAAC;AACJ,CAAC;AAED;;4BAE4B;AAC5B,KAAK,UAAU,kBAAkB,CAC/B,CAA6B,EAC7B,IAA2B;IAE3B,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC;IACpC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,CAAC,CAAC;IACzE,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED;;;gFAGgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC;AAE9C;;4CAE4C;AAC5C,SAAS,WAAW,CAAC,CAA6B;IAChD,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1E,OAAO,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,oBAAoB,CAAC,CAA6B;IACzD,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;AAC1F,CAAC"}

package/dist/core/loop.d.ts

@@ -40,6 +40,17 @@ export interface RunAgentArgs {
     describePermissionDenial?: (toolName: string) => string;
     /** Context-compression config (rung-1 offload). Omit to disable. */
     compression?: CompressionConfig;
+    /** Rung-2 history compaction. Omit and history is never compacted — the run
+     * then behaves exactly as it did before this existed, which is to say it
+     * runs until the provider rejects an oversized request with a fatal 400.
+     * `summarize` is a host concern because it costs a model call; the host also
+     * decides where `onCheckpoint` persists the body (a file the user can edit,
+     * not an invisible blob). */
+    compaction?: {
+        summarize: (collapsed: ChatCompletionMessageParam[]) => Promise<string>;
+        anchor?: (user: ChatCompletionMessageParam, answered: ChatCompletionMessageParam | null) => Promise<string>;
+        onCheckpoint?: (checkpoint: string) => void | Promise<void>;
+    };
     /** Intra-run self-healing budget (stream-retry + tool-steer). Omit for defaults. */
     recovery?: Partial<RecoveryConfig>;
     /** Optional output-token ceiling forwarded to the model on every turn (reasoning
@@ -73,6 +84,20 @@ export interface RunAgentResult {
     text: string;
     usage: Usage;
     stopReason: string;
+    /** How many messages at the TAIL of `messages` this run added.
+     *
+     * A caller stitching the new messages onto its own transcript cannot compute
+     * this from what it sent: rung-2 compaction rewrites `messages` in place and
+     * the rewrite is SHORTER than the input -- that is the point of it -- so an
+     * absolute offset into the result runs off the end and the caller silently
+     * keeps nothing. The browser runtime did exactly that, and dropped the reply
+     * of every run that compacted.
+     *
+     * Counted from the tail by object identity, so no future `messages.push` can
+     * forget to maintain it. A run whose earlier messages were collapsed into a
+     * checkpoint reports only what survives: those messages are genuinely gone
+     * from the array, and the seam in the transcript is what stands in for them. */
+    appended: number;
 }
 /** The most tools one request may carry.
  *

package/dist/core/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../core/loop.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,mCAAmC,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAA4B,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EACY,KAAK,cAAc,EAErC,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAA0D,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIhH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;kFAG8E;IAC9E,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B;oFACgF;IAChF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;6EAQyE;IACzE,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;0FACsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;yEAOqE;IACrE,aAAa,CAAC,EAAE,MAAM,0BAA0B,EAAE,CAAC;IACnD;;4DAEwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC;IACpC;;;0EAGsE;IACtE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;gEAWgE;AAChE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAwa1E"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../core/loop.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,mCAAmC,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAA4B,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EACY,KAAK,cAAc,EAErC,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAA0D,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKhH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;kFAG8E;IAC9E,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B;oFACgF;IAChF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;6EAQyE;IACzE,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC;;;;;iCAK6B;IAC7B,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;QACxE,MAAM,CAAC,EAAE,CACP,IAAI,EAAE,0BAA0B,EAChC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,KACxC,OAAO,CAAC,MAAM,CAAC,CAAC;QACrB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC7D,CAAC;IACF,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;0FACsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;yEAOqE;IACrE,aAAa,CAAC,EAAE,MAAM,0BAA0B,EAAE,CAAC;IACnD;;4DAEwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC;IACpC;;;0EAGsE;IACtE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;oFAYgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;gEAWgE;AAChE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAugB1E"}

package/dist/core/loop.js

@@ -6,6 +6,7 @@ import { checkFeature } from '../guards.js';
 import { STANDARD_POLICY } from '../guardrail/builtins.js';
 import { toolAddress } from '../tools/namespaces.js';
 import { effectiveThreshold, formatOffloadRef, isOffloadPointer } from '../compression.js';
+import { compactHistory, compactionDecision, estimateFill, isCompactionMarker } from './compactHistory.js';
 import { fillToolsMarker } from '../prompts/toolsMarker.js';
 import { createToolLoader, serverIndex } from '../tools/toolSearch.js';
 /** The most tools one request may carry.
@@ -29,6 +30,10 @@ export async function runAgent(args) {
     const ctxWindow = compression?.contextWindow;
     const compressionStrategy = compression?.strategy ?? 'eager';
     let fill = 0; // window fill ratio; drives the adaptive offload threshold
+    /* Compaction is a LATCH, not a per-turn predicate -- see compactionDecision.
+     * Armed at the start of a run; disarmed by a compaction; re-armed once the
+     * window has drained, or has refilled past where that compaction left it. */
+    let compactGate = { armed: true, floor: null };
     // 'deferred' strategy only: results offloaded THIS turn, awaiting the ONE
     // streamCompletion call that sends them in full (the turn right after
     // they're produced — the model that asked for the result reads it). As soon
@@ -54,6 +59,24 @@ export async function runAgent(args) {
     signal.addEventListener('abort', () => { turnAc?.abort(); });
     args.registerInterrupt?.(() => { interrupted = true; turnAc?.abort(); });
     const messages = [...args.messages];
+    /* The messages that came IN, by identity. Everything this run appends is a
+     * fresh object, and everything that survives a compaction from the input is
+     * the same object, so walking back from the tail until an input message
+     * appears is an exact count of what this run added -- maintained by nothing,
+     * and therefore impossible for a later `push` site to get wrong. */
+    const incoming = new Set(args.messages);
+    const appendedFromTail = () => {
+        let n = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const m = messages[i];
+            // A compaction's own checkpoint/anchor, and the system prompt unshifted
+            // below, are fresh objects too -- and neither is something this run said.
+            if (incoming.has(m) || m.role === 'system' || isCompactionMarker(m))
+                break;
+            n++;
+        }
+        return n;
+    };
     /* DEFERRED TOOLS: sent only once found. The loader owns the loaded set;
      * `activeTools` is what one request may carry right now -- the eager tools,
      * `tool_search`, then the loaded ones, capped. Eager first so a full loaded
@@ -138,6 +161,75 @@ export async function runAgent(args) {
                 emit({ type: 'injected', content: typeof m.content === 'string' ? m.content : '' });
             }
         }
+        /* Rung-2 history compaction, BEFORE the request is built so the compacted
+         * array is what goes on the wire. `fill` is last turn's prompt/window
+         * ratio; shouldCompact refuses below the threshold and refuses again when
+         * there is nothing collapsible, because a compaction that removes nothing
+         * still rewrites the cached prefix and re-bills everything after it.
+         * Rebuilt in place: callers (and `res.messages`) hold this array. */
+        /* On turn 1 there is no usage reading yet, so `fill` is 0 and the gate
+         * could not fire before the first request -- which is precisely how a run
+         * resuming an already-oversized conversation put it on the wire and took
+         * the fatal 400. Fall back to reading the window off the messages. Only as
+         * a fallback: a real reading is always better than an estimate that cannot
+         * see the tool schemas. */
+        const gateFill = fill || estimateFill(messages, ctxWindow);
+        const gate = compactionDecision(gateFill, messages, compactGate);
+        compactGate = gate.next;
+        if (args.compaction && gate.compact) {
+            const before = messages.length;
+            /* A summarizer failure is the same shape as a persist failure: the window
+             * is full, the model call meant to compress it did not come back, and the
+             * honest response is to carry on UNCOMPACTED rather than end the run on
+             * the recovery path. The turn then proceeds with the history it had,
+             * which is exactly what would have happened without compaction at all. */
+            try {
+                const out = await compactHistory(messages, {
+                    summarize: args.compaction.summarize,
+                    anchor: args.compaction.anchor,
+                    offloadOverBytes: compression && compression.mode !== 'off'
+                        ? effectiveThreshold(compression.mode, gateFill)
+                        : undefined,
+                    offload: toolCtx.recall
+                        // Recorded under 'user' rather than a tool name: the RecallStore is
+                        // indifferent to who authored the bulk, but the transcript should not
+                        // claim a tool produced what a person pasted.
+                        ? async (content) => formatOffloadRef(await toolCtx.recall.record('user', content))
+                        : undefined,
+                });
+                messages.splice(0, messages.length, ...out.messages);
+                /* The 'deferred' strategy holds ABSOLUTE indices into `messages`, to
+                 * rewrite those entries once the model has seen them in full. The splice
+                 * above just invalidated every one of them, and the rewrite pass read
+                 * `.role` off the resulting undefined -- a crash in the interactive
+                 * CLI's shipping configuration ('deferred' + compaction). Nothing is
+                 * lost by dropping them: the tool results they point at were collapsed
+                 * into the checkpoint and are not in `messages` any more. */
+                deferredOffloads.length = 0;
+                /* The compaction has ALREADY happened by this point. Failing to RECORD it
+                 * must not take the run with it -- checkpointStore.append deliberately
+                 * rejects rather than risk clobbering an existing CHECKPOINT.md, and a
+                 * read-only workspace rejects too. Dying here would lose the whole
+                 * conversation in order to save nothing. */
+                try {
+                    await args.compaction.onCheckpoint?.(out.checkpoint);
+                }
+                catch (e) {
+                    alog('checkpoint persist failed', e instanceof Error ? e.message : String(e));
+                }
+                emit({ type: 'checkpoint', collapsed: before - messages.length, checkpoint: out.checkpoint });
+            }
+            catch (e) {
+                /* Compaction failed (most likely the summarizer's own model call). The
+                 * turn proceeds with the history it had -- exactly what would have
+                 * happened had compaction never been configured. Re-arm so a later turn
+                 * may try again rather than giving up on the run for good. */
+                /* The floor is left as it was: it describes where the last SUCCESSFUL
+                 * compaction landed, and a failed attempt moved nothing. */
+                compactGate = { ...compactGate, armed: true };
+                alog('compaction failed', e instanceof Error ? e.message : String(e));
+            }
+        }
         // Turn-budget guardrail (gstate.turn = completed turns).
         gstate.turn = turn - 1;
         const turnGate = evaluateTurnStart(policy, gstate);
@@ -263,6 +355,12 @@ export async function runAgent(args) {
         usage.completionTokens += streamed.usage.completionTokens;
         if (ctxWindow && ctxWindow > 0 && streamed.usage.promptTokens) {
             fill = Math.min(1, streamed.usage.promptTokens / ctxWindow);
+            /* The first real reading after a compaction is how far down that
+             * compaction actually got, and re-arming is judged against it from here
+             * on. Measured, never estimated: it is compared with later readings of
+             * the same kind. */
+            if (!compactGate.armed && compactGate.floor === null)
+                compactGate = { armed: false, floor: fill };
         }
         emit({ type: 'usage', usage: streamed.usage });
         // Commit the assistant message to history (with tool_calls if any).
@@ -454,7 +552,7 @@ export async function runAgent(args) {
     }
     alog('done', stopReason, 'tokens', usage);
     emit({ type: 'done', reason: stopReason });
-    return { messages, text, usage, stopReason };
+    return { messages, text, usage, stopReason, appended: appendedFromTail() };
 }
 /** 'deferred' strategy: compact any ALREADY-oversized tool result already
  * sitting in the incoming history — i.e. produced by an earlier `runAgent()`