@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/context/compact.js

@@ -0,0 +1,635 @@
+import { isInternalBlockContent, sanitizeInternalReminderBlocks } from "../agent/internal-reminder-sanitizer.js";
+import { appendFileBlocks, extractFileOps, mergeFileOps, parseFileBlocks, stripFileBlocks, } from "./compaction-files.js";
+/**
+ * Compaction must never summarize away what the user actually asked for:
+ * requirements that appear late in a long instruction ("commit when done",
+ * "write the report in French") would otherwise vanish once the heuristic
+ * summary truncates the goal line. Messages larger than this cap are pinned
+ * in truncated form (e.g. a pasted megabyte of logs as the opening message).
+ */
+export const PINNED_INSTRUCTION_MAX_CHARS = 8192;
+export const COMPACTION_SUMMARY_PREFIX = "Previous conversation summary:";
+export const SUBTURN_SUMMARY_PREFIX = "Earlier in this turn (compacted to free context):";
+// llm-compactor.ts's LLM_SUMMARY_PREFIX must start with this literal — a unit
+// test locks the two together (importing it here would create a module cycle).
+const LLM_ENVELOPE_PREFIX = "Another language model previously worked on this task";
+// Projected forms: the projector wraps meta messages into user-role internal
+// blocks, and the resident-history path writes that projected form back, so a
+// summary emitted as meta can come back around as one of these.
+const PROJECTED_SUMMARY_PREFIXES = [
+    `<bubble_internal_context kind="compaction-summary">`,
+    `<bubble_internal_context kind="subturn-compaction-summary">`,
+    // Legacy: summaries emitted as raw system messages by ≤0.0.42 got projected
+    // into runtime-system blocks.
+    `<bubble_internal_context kind="runtime-system">\n${COMPACTION_SUMMARY_PREFIX}`,
+    `<bubble_internal_context kind="runtime-system">\n${SUBTURN_SUMMARY_PREFIX}`,
+];
+export function messageText(message) {
+    if (typeof message.content === "string")
+        return message.content;
+    if (Array.isArray(message.content)) {
+        return message.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join(" ");
+    }
+    return "";
+}
+/**
+ * Identity check for compaction summaries across every form they can take:
+ * the first-class meta form, the legacy raw-system form, and the projected
+ * user-role internal-block forms (the resident path rewrites projections back
+ * into history, so role/position are not conserved).
+ */
+export function isCompactionSummaryMessage(message) {
+    if (message.role === "meta") {
+        return message.kind === "compaction-summary" || message.kind === "subturn-compaction-summary";
+    }
+    const text = messageText(message);
+    if (message.role === "system") {
+        return text.startsWith(COMPACTION_SUMMARY_PREFIX) || text.startsWith(SUBTURN_SUMMARY_PREFIX);
+    }
+    if (message.role === "user") {
+        const trimmed = text.trimStart();
+        if (trimmed.startsWith(LLM_ENVELOPE_PREFIX))
+            return true;
+        return PROJECTED_SUMMARY_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+    }
+    return false;
+}
+/** A message the user actually typed (not a projected reminder, not a summary). */
+export function isRealUserMessage(message) {
+    // Tool screenshots ride in a user-role message for the provider, but they
+    // belong to the tool turn: never a turn boundary.
+    if (message.role !== "user" || message.toolObservation)
+        return false;
+    const text = messageText(message);
+    if (!text.trim() || isInternalBlockContent(text))
+        return false;
+    if (text.trimStart().startsWith(LLM_ENVELOPE_PREFIX))
+        return false;
+    return true;
+}
+/**
+ * Split history into the leading system/meta context prefix (system prompt,
+ * startup reminders) and the conversational body. Positional, mirroring the
+ * projector's leading-prefix semantics: mid-history system/meta messages
+ * belong to the body and are foldable — preserving them by role forever is
+ * how stale reminders and relocated summaries used to pile up at the head.
+ */
+export function splitLeadingContext(messages) {
+    let split = 0;
+    while (split < messages.length) {
+        const message = messages[split];
+        if ((message.role === "system" || message.role === "meta") && !isCompactionSummaryMessage(message)) {
+            split += 1;
+            continue;
+        }
+        break;
+    }
+    return { leading: messages.slice(0, split), body: messages.slice(split) };
+}
+/** Index of the first message the user actually wrote. */
+export function findFirstRealUserIndex(messages) {
+    for (let index = 0; index < messages.length; index++) {
+        if (isRealUserMessage(messages[index]))
+            return index;
+    }
+    return -1;
+}
+/**
+ * Clone a message for pinning; oversized content is truncated rather than
+ * losing the pin entirely (P0.5: a truncated original beats a 140-char
+ * summary line).
+ */
+export function clonePinnedUserMessage(message) {
+    const text = messageText(message);
+    if (text.length <= PINNED_INSTRUCTION_MAX_CHARS)
+        return cloneMessage(message);
+    return {
+        role: "user",
+        content: `${text.slice(0, PINNED_INSTRUCTION_MAX_CHARS)}\n[...original message truncated for context management...]`,
+    };
+}
+export function buildCompactionSummaryMessage(summary) {
+    return {
+        role: "meta",
+        kind: "compaction-summary",
+        content: `${COMPACTION_SUMMARY_PREFIX}\n${summary}`,
+    };
+}
+export function planSessionCompaction(entries, options = {}) {
+    const keepRecentTurns = options.keepRecentTurns ?? 2;
+    // Provider errors are diagnostics, not model context. Keep the latest audit
+    // records across compaction without allowing repeated failures to grow the
+    // compacted session forever.
+    const metadataEntries = [
+        ...entries.filter((entry) => entry.type === "metadata"),
+        ...entries.filter((entry) => entry.type === "provider_error").slice(-20),
+    ];
+    const nonMetadataEntries = entries.filter((entry) => entry.type !== "metadata" && entry.type !== "provider_error");
+    const latestSummaryIndex = findLatestSummaryIndex(nonMetadataEntries);
+    const baseIndex = latestSummaryIndex >= 0 ? latestSummaryIndex + 1 : 0;
+    const activeEntries = nonMetadataEntries.slice(baseIndex);
+    const turnStartIndexes = activeEntries
+        .map((entry, index) => (entry.type === "user_message" ? index : -1))
+        .filter((index) => index >= 0);
+    if (turnStartIndexes.length <= keepRecentTurns) {
+        return { compactable: false };
+    }
+    const keepStartIndex = turnStartIndexes[Math.max(0, turnStartIndexes.length - keepRecentTurns)];
+    if (keepStartIndex <= 0) {
+        return { compactable: false };
+    }
+    return {
+        compactable: true,
+        metadataEntries,
+        oldEntries: activeEntries.slice(0, keepStartIndex),
+        keptEntries: activeEntries.slice(keepStartIndex),
+    };
+}
+/**
+ * Cumulative file ops for a compaction: the blocks prior summaries carried,
+ * unioned with the ops found in the messages being evicted now. Every
+ * compaction path — LLM, heuristic, sub-turn, session-entry — must thread
+ * this through, or the "cumulative" record resets on that path.
+ */
+export function collectCompactionFileOps(evicted, priorSummaries) {
+    return mergeFileOps(...priorSummaries.map((message) => parseFileBlocks(messageText(message))), extractFileOps(evicted));
+}
+/**
+ * Assemble the post-compaction entry list from a plan and a (possibly
+ * LLM-generated) summary string. The summary entry is keyed off the full
+ * original `entries` so its id never collides with a prior summary.
+ */
+export function buildCompactedEntries(entries, plan, summary) {
+    const summaryEntry = {
+        id: nextSummaryId(entries),
+        type: "summary",
+        // Sink-level backstop: whatever producer built this string (LLM or
+        // heuristic), internal markup never lands in the session file.
+        summary: sanitizeInternalReminderBlocks(summary),
+        timestamp: Date.now(),
+    };
+    return [...plan.metadataEntries, summaryEntry, ...plan.keptEntries];
+}
+/** Flatten a plan's old entries into messages for an external summarizer. */
+export function planOldMessages(plan) {
+    return entriesToMessages(plan.oldEntries);
+}
+export function compactSessionEntries(entries, options = {}) {
+    const maxSummaryItems = options.maxSummaryItems ?? 4;
+    const plan = planSessionCompaction(entries, options);
+    if (!plan.compactable) {
+        return { compacted: false };
+    }
+    const summary = buildCompactionSummary(plan.oldEntries, maxSummaryItems);
+    if (!summary) {
+        return { compacted: false };
+    }
+    const oldMessages = entriesToMessages(plan.oldEntries);
+    const summaryWithFiles = appendFileBlocks(summary, collectCompactionFileOps(oldMessages.filter((message) => !isCompactionSummaryMessage(message)), oldMessages.filter(isCompactionSummaryMessage)));
+    return {
+        compacted: true,
+        summary: summaryWithFiles,
+        entries: buildCompactedEntries(entries, plan, summaryWithFiles),
+        droppedEntries: plan.oldEntries.length,
+    };
+}
+export function compactMessages(messages, options = {}) {
+    const keepRecentTurns = options.keepRecentTurns ?? 2;
+    const maxSummaryItems = options.maxSummaryItems ?? 4;
+    // Replace envelopes, not their contents: prior LLM summaries can be the only
+    // surviving record of decisions and constraints. Merge their prose below.
+    const { leading, body } = splitLeadingContext(messages);
+    const priorSummaries = body.filter(isCompactionSummaryMessage);
+    const bodyMessages = body.filter((message) => !isCompactionSummaryMessage(message));
+    // Turn boundaries anchor on REAL user messages only. Projected reminders
+    // and summary envelopes used to inflate the turn count, shrinking the keep
+    // window to nothing and firing compaction almost every turn.
+    const turnStartIndexes = bodyMessages
+        .map((message, index) => (isRealUserMessage(message) ? index : -1))
+        .filter((index) => index >= 0);
+    if (turnStartIndexes.length <= keepRecentTurns) {
+        return { compacted: false };
+    }
+    const keepStartIndex = turnStartIndexes[Math.max(0, turnStartIndexes.length - keepRecentTurns)];
+    if (keepStartIndex <= 0) {
+        return { compacted: false };
+    }
+    const oldMessages = bodyMessages.slice(0, keepStartIndex);
+    const keptMessages = bodyMessages.slice(keepStartIndex);
+    // Pin the original instruction: it stays verbatim above the summary instead
+    // of being crushed into the summary's 140-char goal line.
+    const pinnedIndex = findFirstRealUserIndex(oldMessages);
+    const pinnedMessage = pinnedIndex >= 0 ? oldMessages[pinnedIndex] : undefined;
+    // Summary fodder: real conversational content only — no pinned original,
+    // no projected reminder blocks (they used to pollute Goal/Progress lines).
+    const summaryInput = oldMessages.filter((message, index) => index !== pinnedIndex
+        && message.role !== "meta"
+        && !(message.role === "user" && !isRealUserMessage(message)));
+    const summary = buildMessageSummary(summaryInput, maxSummaryItems);
+    if (!summary) {
+        return { compacted: false };
+    }
+    // Flatten prior envelopes and dedupe lines instead of nesting summaries on
+    // every pass. Keep an explicitly bounded prose record (head + recent tail),
+    // with a durable warning when the heuristic cannot retain everything.
+    const pinOverflow = pinnedMessage
+        ? messageText(pinnedMessage).slice(PINNED_INSTRUCTION_MAX_CHARS)
+        : "";
+    const summaryLines = [
+        ...priorSummaries.map((message) => stripFileBlocks(messageText(message))),
+        ...(pinOverflow ? [`Original instruction beyond retained pin:\n${pinOverflow}`] : []),
+        summary,
+    ].join("\n")
+        .replace(/<\/?bubble_internal_(?:context|reminder)\b[^>]*>/g, "")
+        .split("\n")
+        .map((line) => line.trim()
+        .replace(/^Another language model previously worked on this task[^\n]*?Summary:\s*/, "")
+        .replace(/^Previous conversation summary:\s*/, "")
+        .replace(/^Earlier in this turn \(compacted to free context\):\s*/, ""))
+        .filter(Boolean);
+    const mergedSummary = [...new Set(summaryLines)].join("\n");
+    const proseLimit = 8192;
+    const overflowNotice = "\n[Heuristic compaction degraded: accumulated summary exceeded 8192 characters; middle omitted.]\n";
+    const boundedSummary = mergedSummary.length <= proseLimit ? mergedSummary
+        : mergedSummary.slice(0, 4096) + overflowNotice
+            + mergedSummary.slice(-(proseLimit - 4096 - overflowNotice.length));
+    const summaryWithFiles = appendFileBlocks(boundedSummary, collectCompactionFileOps(oldMessages, priorSummaries));
+    const compactedMessages = [
+        ...leading.map((message) => cloneMessage(message)),
+        ...(pinnedMessage ? [clonePinnedUserMessage(pinnedMessage)] : []),
+        buildCompactionSummaryMessage(summaryWithFiles),
+        ...keptMessages.map((message) => cloneMessage(message)),
+    ];
+    return {
+        compacted: true,
+        summary: summaryWithFiles,
+        messages: compactedMessages,
+        // The pin survives verbatim only up to its cap; the tail beyond it exists
+        // nowhere else, so an external summarizer must see it in the pin's place.
+        evictedMessages: [...priorSummaries, ...oldMessages.flatMap((message, index) => index !== pinnedIndex ? [message]
+                : pinOverflow ? [{ role: "user", content: `Original instruction beyond retained pin:\n${pinOverflow}` }] : [])],
+        summaryIndex: leading.length + (pinnedMessage ? 1 : 0),
+        droppedEntries: summaryInput.length,
+    };
+}
+export function compactCurrentTurnToolGroups(messages, options = {}) {
+    const keepRecentGroups = options.keepRecentGroups ?? 2;
+    const maxSummaryItems = options.maxSummaryItems ?? 8;
+    const { leading, body } = splitLeadingContext(messages);
+    // Anchor the "current turn" on the last REAL user message — a projected
+    // reminder must not shrink the turn to a sliver.
+    let lastUserIndex = -1;
+    for (let i = body.length - 1; i >= 0; i--) {
+        if (isRealUserMessage(body[i])) {
+            lastUserIndex = i;
+            break;
+        }
+    }
+    if (lastUserIndex < 0)
+        return { compacted: false };
+    const preTurn = body.slice(0, lastUserIndex + 1);
+    const rawTurnBody = body.slice(lastUserIndex + 1);
+    // Replace semantics within the turn: fold prior sub-turn summaries' lines
+    // into the new one instead of stacking marker messages.
+    const priorSubturnSummaries = rawTurnBody.filter((m) => m.role === "meta" ? m.kind === "subturn-compaction-summary" : isCompactionSummaryMessage(m) && messageText(m).includes(SUBTURN_SUMMARY_PREFIX.slice(0, 20)));
+    const turnBody = rawTurnBody.filter((m) => !priorSubturnSummaries.includes(m));
+    const groups = [];
+    let current = null;
+    for (const msg of turnBody) {
+        if (msg.role === "assistant") {
+            if (current)
+                groups.push(current);
+            current = { assistant: msg, toolResults: [] };
+        }
+        else if ((msg.role === "tool" || (msg.role === "user" && msg.toolObservation)) && current) {
+            // A screenshot observation follows its tool result: it lives and dies
+            // with that group instead of vanishing from kept groups.
+            current.toolResults.push(msg);
+        }
+    }
+    if (current)
+        groups.push(current);
+    if (groups.length <= keepRecentGroups)
+        return { compacted: false };
+    // Only drop groups that have tool_calls — text-only assistant messages don't
+    // free much context, and dropping them confuses the conversation flow.
+    const evictable = groups.slice(0, groups.length - keepRecentGroups)
+        .filter((g) => g.assistant.role === "assistant" && (g.assistant.toolCalls?.length ?? 0) > 0);
+    if (evictable.length === 0)
+        return { compacted: false };
+    const freshSummary = buildToolGroupsSummary(evictable, maxSummaryItems);
+    if (!freshSummary)
+        return { compacted: false };
+    const summary = mergeSubturnSummaryLines(priorSubturnSummaries, freshSummary, maxSummaryItems);
+    // Evicted groups' file ops would otherwise vanish before any multi-turn
+    // compactor runs; blocks on the sub-turn summary get merged upward later.
+    const summaryWithFiles = appendFileBlocks(summary, collectCompactionFileOps(evictable.flatMap((g) => [g.assistant, ...g.toolResults]), priorSubturnSummaries));
+    const survivingGroups = groups.filter((g) => !evictable.includes(g));
+    const flatSurvivors = [];
+    for (const g of survivingGroups) {
+        flatSurvivors.push(cloneMessage(g.assistant));
+        for (const t of g.toolResults)
+            flatSurvivors.push(cloneMessage(t));
+    }
+    const compactedMessages = [
+        ...leading.map(cloneMessage),
+        ...preTurn.map(cloneMessage),
+        {
+            role: "meta",
+            kind: "subturn-compaction-summary",
+            content: `${SUBTURN_SUMMARY_PREFIX}\n${summaryWithFiles}`,
+        },
+        ...flatSurvivors,
+    ];
+    return {
+        compacted: true,
+        summary,
+        messages: compactedMessages,
+        evictedMessages: [...priorSubturnSummaries, ...evictable.flatMap((g) => [g.assistant, ...g.toolResults])],
+        summaryIndex: leading.length + preTurn.length,
+        droppedEntries: evictable.length,
+    };
+}
+/**
+ * Merge prior sub-turn summary lines with the fresh one: line-level dedupe,
+ * prior lines first (chronological), capped. Structured merge of tool-name /
+ * file lists — not freetext concatenation.
+ */
+function mergeSubturnSummaryLines(priorSummaries, freshSummary, maxItems) {
+    if (priorSummaries.length === 0)
+        return freshSummary;
+    const seen = new Set();
+    const merged = [];
+    const push = (line) => {
+        const normalized = line.trim();
+        if (!normalized || seen.has(normalized))
+            return;
+        seen.add(normalized);
+        merged.push(line);
+    };
+    for (const prior of priorSummaries) {
+        // File blocks are merged structurally by collectCompactionFileOps, not as
+        // prose lines — strip them so paths don't leak into the line dedupe.
+        for (const line of stripFileBlocks(messageText(prior)).split("\n")) {
+            if (line.startsWith(SUBTURN_SUMMARY_PREFIX) || line.startsWith("<bubble_internal_"))
+                continue;
+            push(line);
+        }
+    }
+    for (const line of freshSummary.split("\n"))
+        push(line);
+    const cap = Math.max(maxItems * 4, 24);
+    return merged.slice(-cap).join("\n");
+}
+function buildToolGroupsSummary(groups, maxItems) {
+    const toolCounts = new Map();
+    const fileSet = new Set();
+    let totalResultChars = 0;
+    const findings = [];
+    for (const group of groups) {
+        if (group.assistant.role !== "assistant" || !group.assistant.toolCalls)
+            continue;
+        const toolNameByCallId = new Map();
+        for (const tc of group.assistant.toolCalls) {
+            toolCounts.set(tc.name, (toolCounts.get(tc.name) ?? 0) + 1);
+            toolNameByCallId.set(tc.id, tc.name);
+            try {
+                const parsed = JSON.parse(tc.arguments || "{}");
+                for (const key of ["file_path", "path", "paths", "file"]) {
+                    const v = parsed[key];
+                    if (typeof v === "string" && v)
+                        fileSet.add(v);
+                    else if (Array.isArray(v)) {
+                        for (const item of v)
+                            if (typeof item === "string" && item)
+                                fileSet.add(item);
+                    }
+                }
+            }
+            catch {
+                // ignore unparseable args
+            }
+        }
+        for (const r of group.toolResults) {
+            if (r.role !== "tool")
+                continue;
+            const content = typeof r.content === "string" ? r.content : "";
+            totalResultChars += content.length;
+            if (findings.length < maxItems) {
+                const toolName = toolNameByCallId.get(r.toolCallId) ?? "tool";
+                findings.push(`${toolName}: ${summarizeText(content)}`);
+            }
+        }
+    }
+    const lines = [];
+    const toolList = [...toolCounts.entries()]
+        .map(([name, n]) => (n > 1 ? `${name}×${n}` : name))
+        .join(", ");
+    lines.push(`Tools used: ${toolList || "none"}`);
+    if (fileSet.size > 0) {
+        const fileList = [...fileSet].slice(0, 12);
+        lines.push(`Files touched: ${fileList.join(", ")}${fileSet.size > 12 ? ` (+${fileSet.size - 12} more)` : ""}`);
+    }
+    lines.push(`Discarded ~${formatChars(totalResultChars)} of earlier tool output. Re-run the relevant tool if you need specifics.`);
+    if (findings.length > 0) {
+        lines.push("");
+        lines.push("Earlier findings:");
+        for (const f of findings)
+            lines.push(`- ${f}`);
+    }
+    return lines.join("\n");
+}
+function formatChars(count) {
+    if (count < 1000)
+        return `${count} chars`;
+    if (count < 1_000_000)
+        return `${(count / 1000).toFixed(1)}K chars`;
+    return `${(count / 1_000_000).toFixed(2)}M chars`;
+}
+function buildCompactionSummary(entries, maxSummaryItems) {
+    const messages = entriesToMessages(entries);
+    return buildMessageSummary(messages, maxSummaryItems);
+}
+function buildMessageSummary(messages, maxSummaryItems) {
+    if (messages.length === 0) {
+        return "";
+    }
+    // Internal blocks (goal kicks, task wakes, projected reminders) must not
+    // become the Goal/Progress lines: 140-char truncation would turn them into
+    // markup FRAGMENTS, which defeat the anchored display filters downstream.
+    const userMessages = messages.filter((message) => message.role === "user"
+        && typeof message.content === "string"
+        && !isInternalBlockContent(message.content));
+    const assistantMessages = messages.filter((message) => message.role === "assistant");
+    const toolCalls = collectToolCalls(messages);
+    const relevantFiles = collectRelevantFiles(toolCalls);
+    const toolFindings = collectToolFindings(messages, maxSummaryItems);
+    const goal = userMessages[0] ? summarizeContent(userMessages[0].content) : "Unknown";
+    const progress = userMessages.slice(0, maxSummaryItems).map((message) => `- ${summarizeContent(message.content)}`);
+    const decisions = assistantMessages
+        .map((message) => message.content.trim())
+        .filter(Boolean)
+        .slice(0, maxSummaryItems)
+        .map((content) => `- ${summarizeText(content)}`);
+    const lines = [
+        "Goal:",
+        `- ${goal}`,
+        "",
+        "Progress:",
+        ...(progress.length > 0 ? progress : ["- No user progress recorded"]),
+        "",
+        "Key Decisions:",
+        ...(decisions.length > 0 ? decisions : ["- No assistant decisions recorded"]),
+        "",
+        "Next Steps:",
+        ["- Continue from the most recent preserved turn"],
+        "",
+        "Relevant Files:",
+        ...(relevantFiles.length > 0 ? relevantFiles.map((file) => `- ${file}`) : ["- None captured"]),
+        "",
+        "Tool Findings:",
+        ...(toolFindings.length > 0 ? toolFindings.map((item) => `- ${item}`) : ["- None captured"]),
+    ];
+    return lines.flat().join("\n");
+}
+function entriesToMessages(entries) {
+    const messages = [];
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "user_message":
+                messages.push({ ...entry.message });
+                break;
+            case "assistant_message":
+                messages.push({
+                    ...entry.message,
+                    role: "assistant",
+                });
+                break;
+            case "tool_call": {
+                const last = messages[messages.length - 1];
+                if (last?.role === "assistant") {
+                    last.toolCalls = [...(last.toolCalls ?? []), { ...entry.toolCall }];
+                }
+                else {
+                    messages.push({
+                        role: "assistant",
+                        content: "",
+                        toolCalls: [{ ...entry.toolCall }],
+                    });
+                }
+                break;
+            }
+            case "tool_result":
+                messages.push({ ...entry.message });
+                break;
+            default:
+                break;
+        }
+    }
+    return messages;
+}
+function collectToolCalls(messages) {
+    return messages.flatMap((message) => message.role === "assistant" ? (message.toolCalls ?? []) : []);
+}
+function collectRelevantFiles(toolCalls) {
+    const files = new Set();
+    for (const toolCall of toolCalls) {
+        let parsed = {};
+        try {
+            parsed = JSON.parse(toolCall.arguments || "{}");
+        }
+        catch {
+            parsed = {};
+        }
+        for (const key of ["file", "path", "paths"]) {
+            const value = parsed[key];
+            if (typeof value === "string" && value) {
+                files.add(value);
+            }
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (typeof item === "string" && item) {
+                        files.add(item);
+                    }
+                }
+            }
+        }
+    }
+    return [...files].slice(0, 12);
+}
+function collectToolFindings(messages, maxItems) {
+    const findings = [];
+    const toolNameByCallId = new Map();
+    for (const message of messages) {
+        if (message.role === "assistant" && message.toolCalls) {
+            for (const toolCall of message.toolCalls) {
+                toolNameByCallId.set(toolCall.id, toolCall.name);
+            }
+            continue;
+        }
+        if (message.role !== "tool") {
+            continue;
+        }
+        const toolName = toolNameByCallId.get(message.toolCallId) ?? "tool";
+        findings.push(`${toolName}: ${summarizeText(message.content)}`);
+        if (findings.length >= maxItems) {
+            break;
+        }
+    }
+    return findings;
+}
+function summarizeContent(content) {
+    if (typeof content === "string") {
+        return summarizeText(content);
+    }
+    const textParts = content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text);
+    return summarizeText(textParts.join(" "));
+}
+function summarizeText(value) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= 140) {
+        return normalized || "(empty)";
+    }
+    return `${normalized.slice(0, 137)}...`;
+}
+function findLatestSummaryIndex(entries) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        if (entries[index].type === "summary") {
+            return index;
+        }
+    }
+    return -1;
+}
+function nextSummaryId(entries) {
+    let max = 0;
+    for (const entry of entries) {
+        const match = /^(\d+)/.exec(entry.id);
+        if (!match)
+            continue;
+        max = Math.max(max, Number(match[1]));
+    }
+    return `${max + 1}`;
+}
+function cloneMessage(message) {
+    if (message.role === "assistant") {
+        return {
+            ...message,
+            toolCalls: message.toolCalls?.map((toolCall) => ({ ...toolCall })),
+        };
+    }
+    if (message.role === "user" && Array.isArray(message.content)) {
+        return {
+            ...message,
+            content: message.content.map((part) => ({
+                ...part,
+                ...(part.type === "image_url" ? { image_url: { ...part.image_url } } : {}),
+            })),
+        };
+    }
+    return { ...message };
+}

package/dist/context/compaction-files.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Cumulative file-operation tracking across compactions.
+ *
+ * The LLM summary handles semantics (progress, decisions, next steps); which
+ * files were touched is an enumerable fact the model reliably drops after a
+ * couple of rolling summaries. So it never goes through the model: at each
+ * compaction, deterministic code extracts file ops from the evicted messages,
+ * unions them with the lists the previous summary carried, and appends the
+ * result as structured blocks after the summary text.
+ *
+ * Robustness rules (each earned by a review finding):
+ * - appendFileBlocks sanitizes its input first, so a summary can never carry
+ *   two generations of blocks — or model-echoed tags — at once.
+ * - Only tool calls with a successful result count: a rejected or failed edit
+ *   must not report the file as modified.
+ * - Lists are capped; modified entries are the ones worth keeping complete.
+ * - Serialization is sorted and deduped so identical sets are identical bytes.
+ */
+import type { Message } from "../types.js";
+export interface CompactionFileOps {
+    read: string[];
+    modified: string[];
+}
+/**
+ * File ops mentioned by tool calls in the given (about-to-be-evicted)
+ * messages. A call only counts when its tool result is present and not an
+ * error — a rejected edit or failed read must not enter the record.
+ */
+export declare function extractFileOps(messages: Message[]): CompactionFileOps;
+/** Parse every block a previous compaction summary carried (empty when absent). */
+export declare function parseFileBlocks(text: string): CompactionFileOps;
+/**
+ * Remove all blocks AND stray tags, e.g. before feeding a prior summary back
+ * to the model. Whitespace is only reflowed when something was removed.
+ */
+export declare function stripFileBlocks(text: string): string;
+/** Union, deduped and sorted; a file that was ever modified never lists as read-only. */
+export declare function mergeFileOps(...ops: CompactionFileOps[]): CompactionFileOps;
+/**
+ * Append the blocks to a summary text. Sanitizes the summary first so the
+ * output always contains exactly one generation of blocks, even when the
+ * model echoed tags into its own prose. No-op when both lists are empty.
+ */
+export declare function appendFileBlocks(summary: string, ops: CompactionFileOps): string;