@animalabs/context-manager 0.5.3 → 0.5.4

package/dist/src/strategies/autobiographical.js

@@ -6,6 +6,7 @@ import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Picker, OverBudgetError } from '../adaptive/picker.js';
 import { FlatProfileStrategy } from '../adaptive/strategies/flat-profile.js';
+import { KvStableStrategy } from '../adaptive/strategies/kv-stable.js';
 import { OldestFirstStrategy } from '../adaptive/strategies/oldest-first.js';
 import { chunkMessage, DEFAULT_CHUNKER_OPTIONS } from '../adaptive/chunker.js';
 /**
@@ -923,9 +924,7 @@ export class AutobiographicalStrategy {
             const chunk = this.chunks[chunkIndex];
             if (!chunk || chunk.compressed)
                 return;
-            this.pendingCompression = this.config.hierarchical
-                ? this.compressChunkHierarchical(chunk, ctx)
-                : this.compressChunkLegacy(chunk, ctx);
+            this.pendingCompression = this.compressChunkHierarchical(chunk, ctx);
             try {
                 await this.pendingCompression;
             }
@@ -992,12 +991,13 @@ export class AutobiographicalStrategy {
     }
     select(store, log, budget) {
         this.rebuildChunks(store);
+        // Image stripping runs inside each select path (before stats commit / cache
+        // markers), so the returned entries are already bounded — see
+        // applyImageStripping.
         if (this.config.adaptiveResolution) {
             return this.selectAdaptive(store, budget);
         }
-        return this.config.hierarchical
-            ? this.selectHierarchical(store, budget)
-            : this.selectLegacy(store, log, budget);
+        return this.selectHierarchical(store, budget);
     }
     /**
      * Get summary statistics for observability.
@@ -1022,7 +1022,85 @@ export class AutobiographicalStrategy {
      * Useful for TUI / dashboards. The token sums use the strategy's own
      * token estimates (which match what `select()` uses for budget math).
      */
+    // ===========================================================================
+    // Render-stats instrumentation — inspect, don't reconstruct.
+    //
+    // selectAdaptive/selectHierarchical tally each entry into `_rs` AS THEY EMIT
+    // it (raw head/tail, raw middle the picker kept verbatim, and recall pairs
+    // bucketed by the ancestor summary's level), using the same token numbers the
+    // renderer uses for budget math. `getRenderStats()` returns that committed
+    // snapshot, so it reflects what the last compile actually rendered rather than
+    // re-deriving the full pyramid (which, under adaptive resolution, bears little
+    // resemblance to the folded output).
+    // ===========================================================================
+    _rs = null;
+    _lastRenderStats = null;
+    /** Begin a render-stats accumulation for one select() pass. */
+    rsBegin() {
+        this._rs = {
+            head: { messages: 0, tokens: 0 },
+            tail: { messages: 0, tokens: 0 },
+            middleRaw: { messages: 0, tokens: 0 },
+            summaries: {
+                l1: { count: 0, tokens: 0 },
+                l2: { count: 0, tokens: 0 },
+                l3: { count: 0, tokens: 0 },
+            },
+            pending: { chunks: 0, merges: 0 },
+            total: { messages: 0, tokens: 0 },
+        };
+    }
+    /** Tally one (or `count`) raw message(s) into a raw bucket. */
+    rsRaw(bucket, tokens, count = 1) {
+        const r = this._rs;
+        if (!r)
+            return;
+        r[bucket].messages += count;
+        r[bucket].tokens += tokens;
+    }
+    /** Tally one emitted recall pair under its ancestor's level (>=3 folds into l3). */
+    rsSummary(level, tokens) {
+        const r = this._rs;
+        if (!r)
+            return;
+        const k = level <= 1 ? 'l1' : level === 2 ? 'l2' : 'l3';
+        r.summaries[k].count += 1;
+        r.summaries[k].tokens += tokens;
+    }
+    /** Commit the accumulated stats as the last-render snapshot. */
+    rsEnd() {
+        const r = this._rs;
+        if (!r)
+            return;
+        r.pending = {
+            chunks: this.chunks.filter(c => !c.compressed).length,
+            merges: this.mergeQueue.length,
+        };
+        const s = r.summaries;
+        const summaryMsgs = (s.l1.count + s.l2.count + s.l3.count) * 2; // Q/A pair each
+        r.total = {
+            messages: r.head.messages + r.tail.messages + r.middleRaw.messages + summaryMsgs,
+            tokens: r.head.tokens + r.tail.tokens + r.middleRaw.tokens +
+                s.l1.tokens + s.l2.tokens + s.l3.tokens,
+        };
+        this._lastRenderStats = r;
+        this._rs = null;
+    }
+    /**
+     * Stats describing the LAST rendered context. Returns the inspected snapshot
+     * captured during the most recent `select()`. Before any compile has run (no
+     * snapshot yet), falls back to a reconstructed pyramid view so callers still
+     * get a non-null shape.
+     */
     getRenderStats(store) {
+        return this._lastRenderStats ?? this.reconstructRenderStats(store);
+    }
+    /**
+     * Pre-render fallback: re-derive head/tail windows + the full live pyramid.
+     * NOTE: this is the old "reconstruct" behavior and does NOT reflect adaptive
+     * folding — used only until the first compile populates the inspected stats.
+     */
+    reconstructRenderStats(store) {
         const messages = store.getAll();
         const headStart = this.getHeadWindowStartIndex(store);
         const headEnd = this.getHeadWindowEnd(store);
@@ -1032,131 +1110,30 @@ export class AutobiographicalStrategy {
         const tailMsgs = messages.slice(recentStart);
         const live = (level) => this.summaries.filter(s => s.level === level && !s.mergedInto);
         const sumLevelTokens = (level) => live(level).reduce((acc, s) => acc + s.tokens, 0);
+        const head = { messages: headMsgs.length, tokens: sumTokens(headMsgs) };
+        const tail = { messages: tailMsgs.length, tokens: sumTokens(tailMsgs) };
+        const summaries = {
+            l1: { count: live(1).length, tokens: sumLevelTokens(1) },
+            l2: { count: live(2).length, tokens: sumLevelTokens(2) },
+            l3: { count: live(3).length, tokens: sumLevelTokens(3) },
+        };
         return {
-            head: { messages: headMsgs.length, tokens: sumTokens(headMsgs) },
-            tail: { messages: tailMsgs.length, tokens: sumTokens(tailMsgs) },
-            summaries: {
-                l1: { count: live(1).length, tokens: sumLevelTokens(1) },
-                l2: { count: live(2).length, tokens: sumLevelTokens(2) },
-                l3: { count: live(3).length, tokens: sumLevelTokens(3) },
-            },
+            head,
+            tail,
+            middleRaw: { messages: 0, tokens: 0 },
+            summaries,
             pending: {
                 chunks: this.chunks.filter(c => !c.compressed).length,
                 merges: this.mergeQueue.length,
             },
+            total: {
+                messages: head.messages + tail.messages
+                    + (summaries.l1.count + summaries.l2.count + summaries.l3.count) * 2,
+                tokens: head.tokens + tail.tokens
+                    + summaries.l1.tokens + summaries.l2.tokens + summaries.l3.tokens,
+            },
         };
     }
-    // ============================================================================
-    // Legacy (single-level) path
-    // ============================================================================
-    selectLegacy(store, _log, budget) {
-        const entries = [];
-        const maxTokens = budget.maxTokens - budget.reserveForResponse;
-        let totalTokens = 0;
-        const messages = store.getAll();
-        const msgCap = this.config.maxMessageTokens;
-        // 1. Head window: preserved verbatim as raw copies
-        const headStart = this.getHeadWindowStartIndex(store);
-        const headEnd = this.getHeadWindowEnd(store);
-        for (let i = headStart; i < headEnd && i < messages.length; i++) {
-            const msg = messages[i];
-            const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
-            const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
-            if (this.isOverBudget(totalTokens + tokens, maxTokens))
-                break;
-            entries.push({
-                index: entries.length,
-                sourceMessageId: msg.id,
-                sourceRelation: 'copy',
-                participant: msg.participant,
-                content,
-            });
-            totalTokens += tokens;
-        }
-        // Mark the last head entry as a cache boundary (even if budget truncated the window)
-        if (entries.length > 0) {
-            entries[entries.length - 1].cacheMarker = true;
-        }
-        // 2. Middle zone: compressed chunks as diary pairs, uncompressed as raw messages.
-        const rawRecentStart = this.getRecentWindowStart(store);
-        // Track which message IDs are covered by chunks
-        const coveredByChunks = new Set();
-        for (const chunk of this.chunks) {
-            for (const m of chunk.messages)
-                coveredByChunks.add(m.id);
-            if (chunk.compressed && chunk.diary) {
-                const contextLabel = this.config.summaryContextLabel ?? 'Here is a summary of earlier conversation context:';
-                const summaryParticipant = this.config.summaryParticipant ?? 'Summary';
-                const questionEntry = {
-                    index: entries.length,
-                    participant: 'Context Manager',
-                    content: [{ type: 'text', text: contextLabel }],
-                    sourceRelation: 'derived',
-                };
-                // Synthesised summary turns must respect maxMessageTokens just like raw
-                // copies do — otherwise a runaway diary can starve recent messages.
-                const answerContent = [{ type: 'text', text: chunk.diary }];
-                const answerEntry = {
-                    index: entries.length + 1,
-                    participant: summaryParticipant,
-                    content: msgCap > 0 ? this.truncateContent(answerContent, msgCap) : answerContent,
-                    sourceRelation: 'derived',
-                };
-                const pairTokens = this.estimateTokens(questionEntry.content) +
-                    this.estimateTokens(answerEntry.content);
-                if (this.isOverBudget(totalTokens + pairTokens, maxTokens))
-                    break;
-                entries.push(questionEntry);
-                entries.push(answerEntry);
-                totalTokens += pairTokens;
-            }
-            else {
-                // Uncompressed: emit raw messages so they aren't lost
-                for (const msg of chunk.messages) {
-                    const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
-                    const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
-                    if (this.isOverBudget(totalTokens + tokens, maxTokens))
-                        break;
-                    entries.push({
-                        index: entries.length,
-                        sourceMessageId: msg.id,
-                        sourceRelation: 'copy',
-                        participant: msg.participant,
-                        content,
-                    });
-                    totalTokens += tokens;
-                }
-            }
-        }
-        // Emit gap messages in the compressible zone not covered by any chunk.
-        // Compressible zone: [0, headStart) ∪ [headEnd, rawRecentStart)
-        for (let i = 0; i < rawRecentStart && i < messages.length; i++) {
-            // Skip head window messages (already emitted verbatim above)
-            if (i >= headStart && i < headEnd)
-                continue;
-            if (coveredByChunks.has(messages[i].id))
-                continue;
-            const msg = messages[i];
-            const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
-            const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
-            if (this.isOverBudget(totalTokens + tokens, maxTokens))
-                break;
-            entries.push({
-                index: entries.length,
-                sourceMessageId: msg.id,
-                sourceRelation: 'copy',
-                participant: msg.participant,
-                content,
-            });
-            totalTokens += tokens;
-        }
-        // 3. Recent uncompressed messages (skip those already in head window)
-        const recentStart = Math.max(this.getRecentWindowStart(store), headEnd);
-        this.emitRecentNewestFirst(entries, store, messages, recentStart, msgCap, maxTokens, totalTokens);
-        this.trimOrphanedToolUse(entries);
-        this.pruneToolEntries(entries);
-        return entries;
-    }
     /**
      * Emit recent-window messages, evicting OLDEST-first when the budget is tight.
      *
@@ -1170,7 +1147,7 @@ export class AutobiographicalStrategy {
      */
     emitRecentNewestFirst(entries, store, messages, recentStart, msgCap, maxTokens, totalTokensBefore) {
         if (recentStart >= messages.length)
-            return;
+            return { messages: 0, tokens: 0 };
         const accepted = [];
         let acceptedTokens = 0;
         for (let i = messages.length - 1; i >= recentStart; i--) {
@@ -1190,9 +1167,13 @@ export class AutobiographicalStrategy {
             !this.hasToolUse(messages[accepted[0]])) {
             accepted.shift();
         }
+        let emittedTokens = 0;
         for (const i of accepted) {
             const msg = messages[i];
             const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
+            const tokens = msgCap > 0
+                ? Math.min(store.estimateTokens(msg), msgCap + 50)
+                : store.estimateTokens(msg);
             entries.push({
                 index: entries.length,
                 sourceMessageId: msg.id,
@@ -1200,86 +1181,9 @@ export class AutobiographicalStrategy {
                 participant: msg.participant,
                 content,
             });
+            emittedTokens += tokens;
         }
-    }
-    async compressChunkLegacy(chunk, ctx) {
-        if (!ctx.membrane) {
-            throw new Error('No membrane instance for compression');
-        }
-        const priorContext = this.buildPriorContextLegacy(chunk, ctx);
-        const chunkContent = this.formatChunkForCompression(chunk);
-        const prompt = this.config.diaryUserPrompt ?? this.config.summaryUserPrompt;
-        const systemPrompt = this.config.diarySystemPrompt ?? this.config.summarySystemPrompt;
-        const messages = [
-            ...priorContext,
-            {
-                participant: 'Context Manager',
-                content: [{ type: 'text', text: prompt.replace('{content}', chunkContent) }],
-            },
-        ];
-        const request = {
-            messages: messages.map((m) => ({
-                participant: m.participant,
-                content: m.content,
-            })),
-            system: systemPrompt,
-            config: {
-                model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
-                maxTokens: 2000,
-            },
-        };
-        try {
-            const response = await ctx.membrane.complete(request);
-            const diaryText = response.content
-                .filter((b) => b.type === 'text')
-                .map((b) => b.text)
-                .join('\n');
-            chunk.compressed = true;
-            chunk.diary = diaryText;
-            this._compressionCount++;
-        }
-        catch (error) {
-            console.error('Failed to compress chunk:', error);
-            throw error;
-        }
-    }
-    buildPriorContextLegacy(chunk, ctx) {
-        const context = [];
-        for (const prevChunk of this.chunks) {
-            if (prevChunk.index >= chunk.index)
-                break;
-            if (!prevChunk.compressed || !prevChunk.diary)
-                continue;
-            context.push({
-                participant: 'Context Manager',
-                content: [{ type: 'text', text: this.config.summaryContextLabel ?? 'Summary of earlier context:' }],
-            });
-            context.push({
-                participant: this.config.summaryParticipant ?? 'Summary',
-                content: [{ type: 'text', text: prevChunk.diary }],
-            });
-        }
-        // Find the actual position of this chunk's first message in the full array
-        const messages = ctx.messageStore.getAll();
-        const firstMsgId = chunk.messages[0]?.id;
-        const chunkAbsStart = firstMsgId
-            ? messages.findIndex(m => m.id === firstMsgId)
-            : -1;
-        if (chunkAbsStart > 0) {
-            const precedingStart = Math.max(0, chunkAbsStart - 50);
-            let tokens = 0;
-            for (let i = chunkAbsStart - 1; i >= precedingStart && tokens < 15000; i--) {
-                const msg = messages[i];
-                if (!msg)
-                    break;
-                tokens += ctx.messageStore.estimateTokens(msg);
-                context.unshift({
-                    participant: msg.participant,
-                    content: msg.content,
-                });
-            }
-        }
-        return context;
+        return { messages: accepted.length, tokens: emittedTokens };
     }
     // ============================================================================
     // Hierarchical (L1/L2/L3) path
@@ -1493,6 +1397,10 @@ export class AutobiographicalStrategy {
         let logSummaryId;
         try {
             const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
+            // Text-only on purpose: this is the SUMMARIZER's one-shot response —
+            // its thinking/redacted_thinking blocks are scratch work, not part of
+            // the agent's history, and signed thinking is never valid inside a
+            // rewritten summary anyway.
             const summaryText = response.content
                 .filter((b) => b.type === 'text')
                 .map(b => b.text)
@@ -1913,6 +1821,7 @@ export class AutobiographicalStrategy {
         let logNewSummaryId;
         try {
             const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
+            // Text-only on purpose: summarizer scratch thinking is not agent history
             const mergedText = response.content
                 .filter((b) => b.type === 'text')
                 .map(b => b.text)
@@ -1992,6 +1901,7 @@ export class AutobiographicalStrategy {
      * See `docs/adaptive-resolution-design.md` §3, §5.
      */
     selectAdaptive(store, budget) {
+        this.rsBegin();
         const entries = [];
         const maxTokens = budget.maxTokens - budget.reserveForResponse;
         const messages = store.getAll();
@@ -2022,10 +1932,11 @@ export class AutobiographicalStrategy {
             totalTokens += tokens;
             headMessageIds.add(msg.id);
             headTokens += tokens;
+            this.rsRaw('head', tokens);
         }
-        if (entries.length > 0) {
-            entries[entries.length - 1].cacheMarker = true;
-        }
+        // (Cache breakpoints are placed in one pass over the FINAL ordered entries
+        // below — see placeCacheMarkers — capturing the stable folded prefix, not
+        // just the head boundary.)
         // Compute tail message IDs (will be emitted at end)
         const effectiveRecentStart = Math.max(recentStart, headEnd);
         for (let i = effectiveRecentStart; i < messages.length; i++) {
@@ -2120,8 +2031,7 @@ export class AutobiographicalStrategy {
         };
         const headSetForPicker = new Set(headMessageIds);
         const tailSetForPicker = new Set(tailMessageIds);
-        const picker = this.getAdaptivePicker();
-        const result = picker.run({
+        const pickerInputs = {
             chunks: pickerChunks,
             summaries: summariesMap,
             recallPairTokens,
@@ -2129,7 +2039,9 @@ export class AutobiographicalStrategy {
             tailChunkIds: tailSetForPicker,
             headTokens,
             tailTokens,
-        }, foldingBudget);
+        };
+        const picker = this.buildPicker(pickerInputs);
+        const result = picker.run(pickerInputs, foldingBudget);
         // Commit the new resolutions back to strategy state for next compile.
         // Persist to chronicle only if anything actually changed — avoids
         // unnecessary state-slot writes on no-op compiles (which is the common
@@ -2236,6 +2148,7 @@ export class AutobiographicalStrategy {
                             content,
                         });
                         totalTokens += tokens;
+                        this.rsRaw('middleRaw', tokens);
                     }
                     else {
                         // summary run — emit Q+A pair, dedup at the strategy level
@@ -2263,6 +2176,7 @@ export class AutobiographicalStrategy {
                             entries.push(questionEntry);
                             entries.push(answerEntry);
                             totalTokens += pairTokens;
+                            this.rsSummary(ancestor.level, pairTokens);
                         }
                     }
                     currentRun = null;
@@ -2336,6 +2250,7 @@ export class AutobiographicalStrategy {
                     content,
                 });
                 totalTokens += tokens;
+                this.rsRaw('middleRaw', tokens);
                 i++;
             }
             else {
@@ -2353,6 +2268,7 @@ export class AutobiographicalStrategy {
                         content,
                     });
                     totalTokens += tokens;
+                    this.rsRaw('middleRaw', tokens);
                     i++;
                     continue;
                 }
@@ -2380,11 +2296,13 @@ export class AutobiographicalStrategy {
                 entries.push(questionEntry);
                 entries.push(answerEntry);
                 totalTokens += pairTokens;
+                this.rsSummary(ancestor.level, pairTokens);
                 i++;
             }
         }
         // ----- 6. Emit tail entries newest-first eviction (matches existing behavior) -----
-        this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+        const tailStats = this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+        this.rsRaw('tail', tailStats.tokens, tailStats.messages);
         // ----- 7. Post-process: merge consecutive raw entries from the same bodyGroup -----
         // Both head and tail emission paths emit shards as separate ContextEntries.
         // The middle path already merges consecutive same-bodyGroup raw shards into
@@ -2392,9 +2310,62 @@ export class AutobiographicalStrategy {
         // a sharded message renders as ONE API message regardless of which region
         // it falls into (preserves KV cache through region transitions).
         const merged = this.mergeAdjacentBodyGroupRaw(entries, store);
+        this.pruneToolEntries(merged);
         this.trimOrphanedToolUse(merged);
+        // Strip stale images BEFORE placing markers and committing stats, so both
+        // describe the post-strip context the agent actually receives.
+        this.applyImageStripping(merged, store);
+        // Place ≤4 cache breakpoints across the FINAL ordered entries so the
+        // provider can reuse the stable folded prefix — not just the head. With a
+        // single head marker the cache hit is ~2%; well-placed breakpoints take the
+        // real strategy to ~50% (docs/kv-stable-context-control.md — marker
+        // placement is the dominant KV lever).
+        this.placeCacheMarkers(merged, headMessageIds, tailMessageIds);
+        this.rsEnd();
         return merged;
     }
+    /**
+     * Place up to four `cache_control` breakpoints across the final ordered
+     * entries: the head/system boundary, the end of the folded history (the
+     * stable prefix that persists turn-to-turn — the most valuable), a mid-history
+     * seam, and the very end (for pure-append reuse). Mirrors `placeMarkers` in
+     * the adaptive layer but operates on emitted entries. Idempotent; clears any
+     * pre-existing markers first.
+     */
+    placeCacheMarkers(entries, headMessageIds, tailMessageIds) {
+        for (const e of entries)
+            if (e.cacheMarker)
+                e.cacheMarker = false;
+        const n = entries.length;
+        if (n === 0)
+            return;
+        let lastHead = -1;
+        let firstTail = n;
+        for (let i = 0; i < n; i++) {
+            const sid = entries[i].sourceMessageId;
+            if (sid && headMessageIds.has(sid))
+                lastHead = i;
+        }
+        for (let i = 0; i < n; i++) {
+            const sid = entries[i].sourceMessageId;
+            if (sid && tailMessageIds.has(sid)) {
+                firstTail = i;
+                break;
+            }
+        }
+        const historyEnd = firstTail - 1; // last middle (folded-history) entry
+        const marks = new Set();
+        if (lastHead >= 0)
+            marks.add(lastHead); // system / head block
+        if (historyEnd > lastHead)
+            marks.add(historyEnd); // stable folded prefix (the big one)
+        if (historyEnd - lastHead > 2)
+            marks.add(lastHead + Math.floor((historyEnd - lastHead) / 2)); // mid-history
+        marks.add(n - 1); // end → pure-append reuse
+        for (const idx of marks)
+            if (idx >= 0 && idx < n)
+                entries[idx].cacheMarker = true;
+    }
     /**
      * Walk an entries array; for every run of consecutive entries that
      *  (a) have sourceRelation: 'copy' (raw, not a synthesized recall pair)
@@ -2483,6 +2454,20 @@ export class AutobiographicalStrategy {
         this._adaptivePicker = new Picker(strategy);
         return this._adaptivePicker;
     }
+    /**
+     * Build the picker for this compile. Instance folding strategies (kv-stable)
+     * need the per-compile `PickerInputs` at construction, so they're built fresh
+     * here; stateless ones (flat-profile / oldest-first) reuse the memoized picker.
+     */
+    buildPicker(inputs) {
+        if (this.config.foldingStrategy === 'kv-stable') {
+            return new Picker(new KvStableStrategy(inputs, {
+                reachTokens: this.config.kvStableReachTokens,
+                mergeThreshold: this.config.mergeThreshold,
+            }));
+        }
+        return this.getAdaptivePicker();
+    }
     /**
      * Walk the summary tree to find the L_k ancestor of a message.
      * Returns null if no ancestor exists at that level (e.g., L_k not yet produced).
@@ -2556,6 +2541,7 @@ export class AutobiographicalStrategy {
      * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
      */
     selectHierarchical(store, budget) {
+        this.rsBegin();
         const entries = [];
         const maxTokens = budget.maxTokens - budget.reserveForResponse;
         const messages = store.getAll();
@@ -2578,6 +2564,7 @@ export class AutobiographicalStrategy {
                 content,
             });
             totalTokens += tokens;
+            this.rsRaw('head', tokens);
         }
         // Mark the last head entry as a cache boundary (even if budget truncated the window)
         if (entries.length > 0) {
@@ -2727,6 +2714,7 @@ export class AutobiographicalStrategy {
                         entries.push(questionEntry);
                         entries.push(answerEntry);
                         totalTokens += pairTokens;
+                        this.rsSummary(summary.level, pairTokens);
                     }
                     else {
                         const msg = item.msg;
@@ -2744,6 +2732,7 @@ export class AutobiographicalStrategy {
                             content,
                         });
                         totalTokens += tokens;
+                        this.rsRaw('middleRaw', tokens);
                     }
                 }
             }
@@ -2775,6 +2764,8 @@ export class AutobiographicalStrategy {
                     entries.push(questionEntry);
                     entries.push(answerEntry);
                     totalTokens += pairTokens;
+                    for (const s of selectedSummaries)
+                        this.rsSummary(s.level, s.tokens);
                 }
                 // Sort by position so uncompressed-middle messages and pins both
                 // appear in their chronological place after the combined recall pair.
@@ -2794,6 +2785,7 @@ export class AutobiographicalStrategy {
                         content,
                     });
                     totalTokens += tokens;
+                    this.rsRaw('middleRaw', tokens);
                 }
             }
         }
@@ -2802,9 +2794,14 @@ export class AutobiographicalStrategy {
         // budget, the latest messages (the ones the agent actually needs to act
         // on) are preserved and the oldest recent-window messages are dropped.
         const effectiveRecentStart = Math.max(recentStart, headEnd);
-        this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+        const tailStats = this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+        this.rsRaw('tail', tailStats.tokens, tailStats.messages);
         this.trimOrphanedToolUse(entries);
         this.pruneToolEntries(entries);
+        // Strip stale images before committing stats so RenderStats.total reflects
+        // the post-strip context (this path places no cache markers).
+        this.applyImageStripping(entries, store);
+        this.rsEnd();
         return entries;
     }
     // ============================================================================
@@ -3025,6 +3022,7 @@ export class AutobiographicalStrategy {
             },
         };
         const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
+        // Text-only on purpose: summarizer scratch thinking is not agent history
         return response.content
             .filter((b) => b.type === 'text')
             .map(b => b.text)
@@ -3156,7 +3154,6 @@ export class AutobiographicalStrategy {
         const existing = existingCompressed.get(key);
         if (existing) {
             chunk.compressed = true;
-            chunk.diary = existing.diary;
             chunk.summaryId = existing.summaryId;
         }
         // In hierarchical mode, also check if a summary exists for this chunk
@@ -3172,6 +3169,97 @@ export class AutobiographicalStrategy {
     chunkKey(chunk) {
         return chunk.messages.map((m) => m.id).join(':');
     }
+    /** True if any content block is a live image. */
+    hasImageBlock(content) {
+        return content.some((b) => b.type === 'image');
+    }
+    /** Message index marking the image-strip depth boundary: walks newest→oldest
+     *  summing the same per-message estimate as getRecentWindowStart, and returns
+     *  the index of the first message still within `depthTokens`. Messages before
+     *  this index have their images stripped to placeholders. */
+    getImageStripStart(store, depthTokens) {
+        const messages = store.getAll();
+        let tokens = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            tokens += store.estimateTokens(messages[i]);
+            if (tokens > depthTokens)
+                return i + 1;
+        }
+        return 0;
+    }
+    /** Text substituted for an image block once it leaves the live-image window. */
+    static IMAGE_PLACEHOLDER = '[image dropped from live context]';
+    /** Post-pass over compiled entries: replace image blocks with a text
+     *  placeholder once they fall outside the live-image window — either deeper
+     *  than `imageStripDepthTokens` from the newest message, or beyond the
+     *  `maxLiveImages` most-recent images (counted newest-first). Summaries are
+     *  already text, so they're naturally unaffected. The adjacent
+     *  "[image attachment: <name>]" text added at ingest preserves the filename,
+     *  so the placeholder itself stays terse. Reduces tokens, so it never pushes
+     *  a compiled context back over budget.
+     *
+     *  Runs INSIDE each select path, *before* `rsEnd()` and `placeCacheMarkers`,
+     *  so the committed render stats (and the cache breakpoints) describe the
+     *  post-strip context. As it strips, it decrements the matching raw bucket of
+     *  the in-progress render stats by the reclaimed tokens, keeping
+     *  `RenderStats.total` equal to the real rendered size. */
+    applyImageStripping(entries, store) {
+        const maxLive = this.config.maxLiveImages ?? 0; // 0 = unlimited count
+        const depthTokens = this.config.imageStripDepthTokens ?? 0; // 0 = no depth strip
+        if (maxLive === 0 && depthTokens === 0)
+            return; // policy disabled
+        const messages = store.getAll();
+        const posById = new Map();
+        for (let i = 0; i < messages.length; i++)
+            posById.set(messages[i].id, i);
+        const stripStart = depthTokens > 0 ? this.getImageStripStart(store, depthTokens) : 0;
+        // Same region windows select() bucketed by, so a stripped image's reclaimed
+        // tokens come back out of the bucket it was originally tallied into.
+        const headStart = this.getHeadWindowStartIndex(store);
+        const headEnd = this.getHeadWindowEnd(store);
+        const recentStart = Math.max(this.getRecentWindowStart(store), headEnd);
+        const bucketAt = (pos) => {
+            if (pos < 0)
+                return 'middleRaw'; // no resolvable region — keep total == Σbuckets
+            if (pos >= headStart && pos < headEnd)
+                return 'head';
+            if (pos >= recentStart)
+                return 'tail';
+            return 'middleRaw';
+        };
+        const placeholderTokens = Math.ceil(AutobiographicalStrategy.IMAGE_PLACEHOLDER.length / 4);
+        // Image-bearing entries, newest-first by source position. Entries with no
+        // resolvable source position sort last (pos -1) and never count as "live".
+        const ordered = entries
+            .map((entry, idx) => ({
+            idx,
+            pos: entry.sourceMessageId !== undefined ? posById.get(entry.sourceMessageId) ?? -1 : -1,
+        }))
+            .filter(({ idx }) => this.hasImageBlock(entries[idx].content))
+            .sort((a, b) => b.pos - a.pos);
+        let keptImages = 0;
+        for (const { idx, pos } of ordered) {
+            const entry = entries[idx];
+            const tooDeep = depthTokens > 0 && (pos < 0 || pos < stripStart);
+            const bucket = bucketAt(pos);
+            entry.content = entry.content.map((block) => {
+                if (block.type !== 'image')
+                    return block;
+                const overCount = maxLive > 0 && keptImages >= maxLive;
+                if (tooDeep || overCount) {
+                    // The renderer estimates an image at `tokenEstimate ?? 1600` (see
+                    // message-store/context-log). Hand that back to the bucket, less the
+                    // placeholder text that replaces it, so the stats match the output.
+                    const reclaimed = (block.tokenEstimate ?? 1600) - placeholderTokens;
+                    if (this._rs && reclaimed > 0)
+                        this._rs[bucket].tokens -= reclaimed;
+                    return { type: 'text', text: AutobiographicalStrategy.IMAGE_PLACEHOLDER };
+                }
+                keptImages++;
+                return block;
+            });
+        }
+    }
     getRecentWindowStart(store) {
         const messages = store.getAll();
         let tokens = 0;