@ponythewhite/base-context 1.0.6 → 1.0.8

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

@@ -1 +1 @@
-{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/compaction.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Context compaction for long sessions.\n *\n * Pure functions for compaction logic. The session manager handles I/O,\n * and after compaction the session is reloaded.\n */\n\nimport type { AgentMessage, ThinkingLevel } from \"@ponythewhite/base-context-agent\";\nimport type { AssistantMessage, Model, Usage } from \"@ponythewhite/base-context-ai\";\nimport {\n\tcompleteInference,\n\tInferenceCoordinator,\n\ttype NativeCompactionOutputBinding,\n} from \"../inference-coordinator.js\";\nimport {\n\tconvertToLlm,\n\tcreateBranchSummaryMessage,\n\tcreateCompactionSummaryMessage,\n\tcreateCustomMessage,\n} from \"../messages.js\";\nimport type { NativeCompactionRequestOutputAssociation } from \"../request-events.js\";\nimport { MODEL_REQUEST_ID_HEADER } from \"../semantic-edges.js\";\nimport { buildSessionContext, type CompactionEntry, type SessionEntry } from \"../session-manager.js\";\nimport { addAssistantUsage, emptyUsage } from \"../usage.js\";\nimport {\n\tcomputeFileLists,\n\tcreateFileOps,\n\textractFileOpsFromMessage,\n\ttype FileOperations,\n\tformatFileOperations,\n\tSUMMARIZATION_SYSTEM_PROMPT,\n\tserializeConversation,\n} from \"./utils.js\";\n/** Details stored in CompactionEntry.details for file tracking */\nexport interface CompactionDetails {\n\treadFiles: string[];\n\tmodifiedFiles: string[];\n}\n\nexport interface SummarySlice {\n\tsummary: string;\n\tusage?: Usage;\n}\n\n// Identity follows the actual completion -> text slice -> built-in composition, never copied fields.\nconst nativeSummarySlices = new WeakMap<SummarySlice, { summary: string; binding: NativeCompactionOutputBinding }>();\nconst nativeCompactionResults = new WeakMap<object, { summary: string; bindings: NativeCompactionOutputBinding[] }>();\n\nfunction captureSummarySlice(\n\tslice: SummarySlice,\n\trequests: InferenceCoordinator | undefined,\n\tcompletion: Promise<AssistantMessage>,\n\tpart: NativeCompactionRequestOutputAssociation[\"part\"],\n): SummarySlice {\n\tconst binding =\n\t\trequests instanceof InferenceCoordinator\n\t\t\t? InferenceCoordinator.prototype.takeCompactionOutput.call(requests, completion)\n\t\t\t: undefined;\n\tif (binding?.output.part === part) nativeSummarySlices.set(slice, { summary: slice.summary, binding });\n\treturn slice;\n}\n\n/** Internal append input: only this exact built-in result and original sink can contribute links. */\nexport function takeCompactionRequestOutputs(\n\tresult: object | undefined,\n\tsink: object,\n\tsummary: string,\n): readonly NativeCompactionRequestOutputAssociation[] | undefined {\n\tconst captured = result ? nativeCompactionResults.get(result) : undefined;\n\tif (result) nativeCompactionResults.delete(result);\n\t// Equality only checks an already privately bound projection for mutation; it never discovers a link.\n\tif (!captured || captured.summary !== summary) return undefined;\n\tconst outputs = captured.bindings.filter((binding) => binding.sink === sink).map((binding) => binding.output);\n\treturn outputs.length ? outputs : undefined;\n}\n\n/**\n * Extract file operations from messages and previous compaction entries.\n */\n/** Preserve file operations recorded by prior compactions and current tool calls. */\nfunction extractFileOperations(\n\tmessages: AgentMessage[],\n\tentries: SessionEntry[],\n\tprevCompactionIndex: number,\n): FileOperations {\n\tconst fileOps = createFileOps();\n\tif (prevCompactionIndex >= 0) {\n\t\tconst prevCompaction = entries[prevCompactionIndex] as CompactionEntry;\n\t\tif (!prevCompaction.fromHook && prevCompaction.details) {\n\t\t\t// fromHook field kept for session file compatibility\n\t\t\tconst details = prevCompaction.details as CompactionDetails;\n\t\t\tif (Array.isArray(details.readFiles)) {\n\t\t\t\tfor (const f of details.readFiles) fileOps.read.add(f);\n\t\t\t}\n\t\t\tif (Array.isArray(details.modifiedFiles)) {\n\t\t\t\tfor (const f of details.modifiedFiles) fileOps.edited.add(f);\n\t\t\t}\n\t\t}\n\t}\n\tfor (const msg of messages) {\n\t\textractFileOpsFromMessage(msg, fileOps);\n\t}\n\n\treturn fileOps;\n}\n/**\n * Extract AgentMessage from an entry if it produces one.\n * Returns undefined for entries that don't contribute to LLM context.\n */\nfunction getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {\n\tif (entry.type === \"message\") {\n\t\treturn entry.message;\n\t}\n\tif (entry.type === \"custom_message\") {\n\t\treturn createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp);\n\t}\n\tif (entry.type === \"branch_summary\") {\n\t\treturn createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);\n\t}\n\tif (entry.type === \"compaction\") {\n\t\treturn createCompactionSummaryMessage(\n\t\t\tentry.summary,\n\t\t\tentry.tokensBefore,\n\t\t\tentry.timestamp,\n\t\t\tentry.customInstructions,\n\t\t);\n\t}\n\treturn undefined;\n}\n\nfunction getMessageFromEntryForCompaction(entry: SessionEntry): AgentMessage | undefined {\n\tif (entry.type === \"compaction\") {\n\t\treturn undefined;\n\t}\n\treturn getMessageFromEntry(entry);\n}\n\n/** Result from compact() - SessionManager adds uuid/parentUuid when saving */\nexport interface CompactionResult<T = unknown> {\n\tsummary: string;\n\tfirstKeptEntryId: string;\n\t/** Prior-context estimate; null when the original context is not measurable. */\n\ttokensBefore: number | null;\n\t/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */\n\tdetails?: T;\n\t/** What the summarization call(s) billed; persisted on the compaction entry. */\n\tusage?: Usage;\n}\nexport const COMPACT_SKILL_NAME = \"compact\";\n\nexport interface CompactionSettings {\n\tenabled: boolean;\n\treserveTokens: number;\n\tkeepRecentTokens: number;\n}\n\nexport const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {\n\tenabled: true,\n\treserveTokens: 16384,\n\tkeepRecentTokens: 20000,\n};\n/**\n * Calculate total context tokens from usage.\n * Uses the native totalTokens field when available, falls back to computing from components.\n *\n * Includes output: the assistant's response becomes part of the prompt on the next\n * request, so it counts toward the context the next turn will send.\n */\nexport function calculateContextTokens(usage: Usage): number {\n\treturn usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;\n}\n\n/**\n * Get usage from an assistant message if available.\n * Skips aborted and error messages as they don't have valid usage data.\n */\nfunction getAssistantUsage(msg: AgentMessage): Usage | undefined {\n\tif (msg.role === \"assistant\" && \"usage\" in msg) {\n\t\tconst assistantMsg = msg as AssistantMessage;\n\t\tif (assistantMsg.stopReason !== \"aborted\" && assistantMsg.stopReason !== \"error\" && assistantMsg.usage) {\n\t\t\treturn assistantMsg.usage;\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/**\n * Find the last non-aborted assistant message usage from session entries.\n */\nexport function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined {\n\tfor (let i = entries.length - 1; i >= 0; i--) {\n\t\tconst entry = entries[i];\n\t\tif (entry.type === \"message\") {\n\t\t\tconst usage = getAssistantUsage(entry.message);\n\t\t\tif (usage) return usage;\n\t\t}\n\t}\n\treturn undefined;\n}\n\nexport interface ContextUsageEstimate {\n\ttokens: number;\n\tusageTokens: number;\n\ttrailingTokens: number;\n\tlastUsageIndex: number | null;\n}\n\nfunction getLastAssistantUsageInfo(messages: readonly AgentMessage[]): { usage: Usage; index: number } | undefined {\n\tfor (let i = messages.length - 1; i >= 0; i--) {\n\t\tconst usage = getAssistantUsage(messages[i]);\n\t\tif (usage) return { usage, index: i };\n\t}\n\treturn undefined;\n}\n\n/**\n * Estimate context tokens from messages, using the last assistant usage when available.\n * If there are messages after the last usage, estimate their tokens with estimateTokens.\n */\nexport function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate {\n\tconst usageInfo = getLastAssistantUsageInfo(messages);\n\n\tif (!usageInfo) {\n\t\tlet estimated = 0;\n\t\tfor (const message of messages) {\n\t\t\testimated += estimateTokens(message);\n\t\t}\n\t\treturn {\n\t\t\ttokens: estimated,\n\t\t\tusageTokens: 0,\n\t\t\ttrailingTokens: estimated,\n\t\t\tlastUsageIndex: null,\n\t\t};\n\t}\n\n\tconst usageTokens = calculateContextTokens(usageInfo.usage);\n\tlet trailingTokens = 0;\n\tfor (let i = usageInfo.index + 1; i < messages.length; i++) {\n\t\ttrailingTokens += estimateTokens(messages[i]);\n\t}\n\n\treturn {\n\t\ttokens: usageTokens + trailingTokens,\n\t\tusageTokens,\n\t\ttrailingTokens,\n\t\tlastUsageIndex: usageInfo.index,\n\t};\n}\n\n/**\n * Check if compaction should trigger based on context usage.\n */\nexport function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {\n\tif (!settings.enabled) return false;\n\tif (contextWindow <= 0) return false;\n\treturn contextTokens > contextWindow - settings.reserveTokens;\n}\n/** Raise suffix estimates when observed usage exceeds chars/4 for the same prefix. */\nfunction compactionTokenScale(messages: readonly AgentMessage[]): number {\n\tconst usageInfo = getLastAssistantUsageInfo(messages);\n\tif (!usageInfo) return 1;\n\tlet estimatedTokens = 0;\n\tfor (let index = 0; index <= usageInfo.index; index++) {\n\t\testimatedTokens += estimateTokens(messages[index]);\n\t}\n\treturn estimatedTokens > 0 ? Math.max(1, calculateContextTokens(usageInfo.usage) / estimatedTokens) : 1;\n}\n\n/** Estimate message tokens with chars/4; dense content can exceed this heuristic. */\nexport function estimateTokens(message: AgentMessage): number {\n\tlet chars = 0;\n\n\tswitch (message.role) {\n\t\tcase \"user\": {\n\t\t\tconst content = (message as { content: string | Array<{ type: string; text?: string }> }).content;\n\t\t\tif (typeof content === \"string\") {\n\t\t\t\tchars = content.length;\n\t\t\t} else if (Array.isArray(content)) {\n\t\t\t\tfor (const block of content) {\n\t\t\t\t\tif (block.type === \"text\" && block.text) {\n\t\t\t\t\t\tchars += block.text.length;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"assistant\": {\n\t\t\tconst assistant = message as AssistantMessage;\n\t\t\tfor (const block of assistant.content) {\n\t\t\t\tif (block.type === \"text\") {\n\t\t\t\t\tchars += block.text.length;\n\t\t\t\t} else if (block.type === \"thinking\") {\n\t\t\t\t\tchars += block.thinking.length;\n\t\t\t\t} else if (block.type === \"toolCall\") {\n\t\t\t\t\tchars += block.name.length + JSON.stringify(block.arguments).length;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"custom\":\n\t\tcase \"toolResult\": {\n\t\t\tif (typeof message.content === \"string\") {\n\t\t\t\tchars = message.content.length;\n\t\t\t} else {\n\t\t\t\tfor (const block of message.content) {\n\t\t\t\t\tif (block.type === \"text\" && block.text) {\n\t\t\t\t\t\tchars += block.text.length;\n\t\t\t\t\t}\n\t\t\t\t\tif (block.type === \"image\") {\n\t\t\t\t\t\tchars += 4800; // Estimate images as 4000 chars, or 1200 tokens\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"bashExecution\": {\n\t\t\tchars = message.command.length + message.output.length;\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"branchSummary\":\n\t\tcase \"compactionSummary\": {\n\t\t\tchars = message.summary.length;\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t}\n\n\treturn 0;\n}\n\n/**\n * Find valid cut points: indices of user, assistant, custom, or bashExecution messages.\n * Never cut at tool results (they must follow their tool call).\n * When we cut at an assistant message with tool calls, its tool results follow it\n * and will be kept.\n * BashExecutionMessage is treated like a user message (user-initiated context).\n */\nfunction findValidCutPoints(entries: SessionEntry[], startIndex: number, endIndex: number): number[] {\n\tconst cutPoints: number[] = [];\n\tfor (let i = startIndex; i < endIndex; i++) {\n\t\tconst entry = entries[i];\n\t\tswitch (entry.type) {\n\t\t\tcase \"message\": {\n\t\t\t\tconst role = entry.message.role;\n\t\t\t\tswitch (role) {\n\t\t\t\t\tcase \"bashExecution\":\n\t\t\t\t\tcase \"custom\":\n\t\t\t\t\tcase \"branchSummary\":\n\t\t\t\t\tcase \"compactionSummary\":\n\t\t\t\t\tcase \"user\":\n\t\t\t\t\tcase \"assistant\":\n\t\t\t\t\t\tcutPoints.push(i);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"toolResult\":\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase \"thinking_level_change\":\n\t\t\tcase \"model_change\":\n\t\t\tcase \"compaction\":\n\t\t\tcase \"branch_summary\":\n\t\t\tcase \"custom\":\n\t\t\tcase \"custom_message\":\n\t\t\tcase \"label\":\n\t\t\tcase \"session_info\":\n\t\t\t\tbreak;\n\t\t}\n\t\t// Branch summaries and custom messages are user-role turn boundaries.\n\t\tif (entry.type === \"branch_summary\" || entry.type === \"custom_message\") {\n\t\t\tcutPoints.push(i);\n\t\t}\n\t}\n\treturn cutPoints;\n}\n\n/**\n * Find the user message (or bashExecution) that starts the turn containing the given entry index.\n * Returns -1 if no turn start found before the index.\n * BashExecutionMessage is treated like a user message for turn boundaries.\n */\nexport function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number {\n\tfor (let i = entryIndex; i >= startIndex; i--) {\n\t\tconst entry = entries[i];\n\t\tif (entry.type === \"branch_summary\" || entry.type === \"custom_message\") {\n\t\t\treturn i;\n\t\t}\n\t\tif (entry.type === \"message\") {\n\t\t\tconst role = entry.message.role;\n\t\t\tif (role === \"user\" || role === \"bashExecution\") {\n\t\t\t\treturn i;\n\t\t\t}\n\t\t}\n\t}\n\treturn -1;\n}\n\nexport interface CutPointResult {\n\t/** Index of first entry to keep */\n\tfirstKeptEntryIndex: number;\n\t/** Index of user message that starts the turn being split, or -1 if not splitting */\n\tturnStartIndex: number;\n\t/** Whether this cut splits a turn (cut point is not a user message) */\n\tisSplitTurn: boolean;\n}\n\n/**\n * Find the cut point in session entries that keeps approximately `keepRecentTokens`.\n *\n * Algorithm: Walk backwards from newest, accumulating estimated message sizes.\n * Stop when we've accumulated >= keepRecentTokens. Cut at that point.\n *\n * Can cut at user OR assistant messages (never tool results). When cutting at an\n * assistant message with tool calls, its tool results come after and will be kept.\n *\n * Returns CutPointResult with:\n * - firstKeptEntryIndex: the entry index to start keeping from\n * - turnStartIndex: if cutting mid-turn, the user message that started that turn\n * - isSplitTurn: whether we're cutting in the middle of a turn\n *\n * Only considers entries between `startIndex` and `endIndex` (exclusive).\n */\nexport function findCutPoint(\n\tentries: SessionEntry[],\n\tstartIndex: number,\n\tendIndex: number,\n\tkeepRecentTokens: number,\n\tallowShortSession = false,\n\ttokenScale = 1,\n): CutPointResult {\n\tconst cutPoints = findValidCutPoints(entries, startIndex, endIndex);\n\n\tif (cutPoints.length === 0) {\n\t\treturn { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false };\n\t}\n\tlet accumulatedTokens = 0;\n\tlet cutIndex = cutPoints[0]; // Default: keep from first message (not header)\n\n\tfor (let i = endIndex - 1; i >= startIndex; i--) {\n\t\tconst entry = entries[i];\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst messageTokens = estimateTokens(entry.message) * tokenScale;\n\t\taccumulatedTokens += messageTokens;\n\t\tif (accumulatedTokens >= keepRecentTokens) {\n\t\t\tcutIndex = cutPoints.filter((candidate) => candidate <= i).at(-1) ?? cutIndex;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (allowShortSession && cutIndex === cutPoints[0]) {\n\t\t// An explicit compact may summarize a short prefix, but must keep a real suffix.\n\t\tconst latest = cutPoints\n\t\t\t.filter((index) => {\n\t\t\t\tconst entry = entries[index];\n\t\t\t\treturn entry.type !== \"message\" || entry.message.role !== \"compactionSummary\";\n\t\t\t})\n\t\t\t.at(-1);\n\t\tif (latest !== undefined) cutIndex = latest;\n\t}\n\twhile (cutIndex > startIndex) {\n\t\tconst prevEntry = entries[cutIndex - 1];\n\t\tif (prevEntry.type === \"compaction\") {\n\t\t\tbreak;\n\t\t}\n\t\tif (prevEntry.type === \"message\") {\n\t\t\tbreak;\n\t\t}\n\t\tcutIndex--;\n\t}\n\tconst cutEntry = entries[cutIndex];\n\tconst isUserMessage = cutEntry.type === \"message\" && cutEntry.message.role === \"user\";\n\t// A cut in a non-user turn requires a prefix summary.\n\tconst turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);\n\n\treturn {\n\t\tfirstKeptEntryIndex: cutIndex,\n\t\tturnStartIndex,\n\t\tisSplitTurn: !isUserMessage && turnStartIndex !== -1,\n\t};\n}\nconst SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.\n\nUse this EXACT format:\n\n## Goal\n[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements mentioned by user]\n- [Or \"(none)\" if none were mentioned]\n\n## Progress\n### Done\n- [x] [Completed tasks/changes]\n\n### In Progress\n- [ ] [Current work]\n\n### Blocked\n- [Issues preventing progress, if any]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Ordered list of what should happen next]\n\n## Critical Context\n- [Any data, examples, or references needed to continue]\n- [Or \"(none)\" if not applicable]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.`;\n\nconst RUNTIME_STATE_SUMMARY_NOTE =\n\t\"Runtime note: this summary does not establish whether a Python kernel is live or whether its variables, imports, helpers, or jobs remain available. Preserve useful names and their last observed state, including uncertainty. Use current runtime reports before relying on them; do not infer either survival or loss from compaction.\";\n\nconst UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.\n\nUpdate the existing structured summary with new information. RULES:\n- PRESERVE all existing information from the previous summary\n- ADD new progress, decisions, and context from the new messages\n- UPDATE the Progress section: move items from \"In Progress\" to \"Done\" when completed\n- UPDATE \"Next Steps\" based on what was accomplished\n- PRESERVE exact file paths, function names, and error messages\n- If something is no longer relevant, you may remove it\n\nUse this EXACT format:\n\n## Goal\n[Preserve existing goals, add new ones if the task expanded]\n\n## Constraints & Preferences\n- [Preserve existing, add new ones discovered]\n\n## Progress\n### Done\n- [x] [Include previously done items AND newly completed items]\n\n### In Progress\n- [ ] [Current work - update based on progress]\n\n### Blocked\n- [Current blockers - remove if resolved]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale] (preserve all previous, add new)\n\n## Next Steps\n1. [Update based on current state]\n\n## Critical Context\n- [Preserve important context, add new if needed]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.`;\n\n/**\n * Build the instruction portion of the summarization prompt: the initial or\n * update template, optional user instructions, and the runtime-state qualification.\n */\nexport function buildSummarizationPrompt(customInstructions?: string, previousSummary?: string): string {\n\tlet basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;\n\tif (customInstructions) {\n\t\tbasePrompt += `\\n\\n<user-instructions>\\nThe user provided these instructions for this summary. Follow them with high priority while keeping the section format above: emphasize what they ask to focus on, and preserve verbatim anything they ask to remember.\\n${customInstructions}\\n</user-instructions>`;\n\t}\n\treturn `${basePrompt}\\n\\n${RUNTIME_STATE_SUMMARY_NOTE}`;\n}\n\n/**\n * Generate a summary of the conversation using the LLM.\n * If previousSummary is provided, uses the update prompt to merge.\n */\nexport async function generateSummary(\n\tcurrentMessages: AgentMessage[],\n\tmodel: Model<any>,\n\treserveTokens: number,\n\tapiKey: string,\n\theaders?: Record<string, string>,\n\tsignal?: AbortSignal,\n\tcustomInstructions?: string,\n\tpreviousSummary?: string,\n\tthinkingLevel?: ThinkingLevel,\n\trequests?: InferenceCoordinator,\n): Promise<SummarySlice> {\n\tconst maxTokens = Math.floor(0.8 * reserveTokens);\n\n\tconst basePrompt = buildSummarizationPrompt(customInstructions, previousSummary);\n\t// Serialize before the LLM call so it summarizes rather than continues this conversation.\n\tconst llmMessages = convertToLlm(currentMessages);\n\tconst conversationText = serializeConversation(llmMessages);\n\tlet promptText = `<conversation>\\n${conversationText}\\n</conversation>\\n\\n`;\n\tif (previousSummary) {\n\t\tpromptText += `<previous-summary>\\n${previousSummary}\\n</previous-summary>\\n\\n`;\n\t}\n\tpromptText += basePrompt;\n\n\tconst summarizationMessages = [\n\t\t{\n\t\t\trole: \"user\" as const,\n\t\t\tcontent: [{ type: \"text\" as const, text: promptText }],\n\t\t\ttimestamp: Date.now(),\n\t\t},\n\t];\n\n\tconst completionOptions =\n\t\tmodel.reasoning && thinkingLevel && thinkingLevel !== \"off\"\n\t\t\t? { maxTokens, signal, apiKey, headers, reasoning: thinkingLevel }\n\t\t\t: { maxTokens, signal, apiKey, headers };\n\n\tconst completion = completeInference(\n\t\trequests,\n\t\tmodel,\n\t\t{ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },\n\t\tcompletionOptions,\n\t\t{\n\t\t\tpurpose: \"summary\",\n\t\t\tpurposeDetail: \"compaction\",\n\t\t\toperationId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t\tsemanticEdgeId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t},\n\t);\n\n\tconst response = await completion;\n\tif (response.stopReason === \"error\") {\n\t\tthrow new Error(`Summarization failed: ${response.errorMessage || \"Unknown error\"}`);\n\t}\n\n\tconst textContent = response.content\n\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t.map((c) => c.text)\n\t\t.join(\"\\n\");\n\n\treturn captureSummarySlice({ summary: textContent, usage: response.usage }, requests, completion, \"history\");\n}\nexport interface CompactionPreparation {\n\t/** UUID of first entry to keep */\n\tfirstKeptEntryId: string;\n\t/** Messages that will be summarized and discarded */\n\tmessagesToSummarize: AgentMessage[];\n\t/** Messages that will be turned into turn prefix summary (if splitting) */\n\tturnPrefixMessages: AgentMessage[];\n\t/** Whether this is a split turn (cut point in middle of turn) */\n\tisSplitTurn: boolean;\n\ttokensBefore: number;\n\t/** Summary from previous compaction, for iterative update */\n\tpreviousSummary?: string;\n\t/** File operations extracted from messagesToSummarize */\n\tfileOps: FileOperations;\n\t/** Compaction settions from settings.jsonl\t*/\n\tsettings: CompactionSettings;\n}\n\n/** Prepare the actual selected epoch view. Entry IDs are only real cut anchors, never synthetic rows. */\nexport function prepareViewCompaction(\n\tmessages: readonly AgentMessage[],\n\tentryIds: readonly (string | undefined)[],\n\tpathEntries: SessionEntry[],\n\tsettings: CompactionSettings,\n\tmaxCutEntryId?: string,\n\tallowShortSession = false,\n\tbudgetPressure = false,\n): CompactionPreparation | undefined {\n\tif (messages.length !== entryIds.length) throw new Error(\"Compaction views do not match their source anchors\");\n\t// firstKeptEntryId restores a chronological source suffix, not a selected-view suffix.\n\t// Older pinned views cannot become cut anchors across omitted source messages.\n\tconst selectedIds = new Set(entryIds);\n\tconst suffixAnchors = new Set<string>();\n\tfor (let index = pathEntries.length - 1; index >= 0; index--) {\n\t\tconst entry = pathEntries[index];\n\t\tif (!getMessageFromEntryForCompaction(entry)) continue;\n\t\tif (!selectedIds.has(entry.id)) break;\n\t\tsuffixAnchors.add(entry.id);\n\t}\n\tlet cuts = messages.flatMap((message, index) =>\n\t\tentryIds[index] &&\n\t\tsuffixAnchors.has(entryIds[index]!) &&\n\t\tmessage.role !== \"toolResult\" &&\n\t\tmessage.role !== \"compactionSummary\"\n\t\t\t? [index]\n\t\t\t: [],\n\t);\n\tlet relaxRetention = false;\n\tif (budgetPressure) {\n\t\t// Only caller-confirmed public OVER may relax retention; source/tool groups remain whole.\n\t\tconst spans: [number, number][] = [];\n\t\tconst sourceStarts = new Map<string, number>();\n\t\tconst resultEnds = new Map<string, number>();\n\t\t// Public history renders original roles as custom text; use its captured source anchors.\n\t\tconst sourceMessages = new Map(pathEntries.map((entry) => [entry.id, getMessageFromEntry(entry)]));\n\t\tconst anchoredMessages = messages.map((message, index) => sourceMessages.get(entryIds[index] ?? \"\") ?? message);\n\t\tfor (const [index, message] of anchoredMessages.entries()) {\n\t\t\tconst entryId = entryIds[index];\n\t\t\tif (entryId) {\n\t\t\t\tconst start = sourceStarts.get(entryId);\n\t\t\t\tif (start === undefined) sourceStarts.set(entryId, index);\n\t\t\t\telse spans.push([start, index]);\n\t\t\t}\n\t\t\tif (message.role === \"toolResult\") resultEnds.set(message.toolCallId, index);\n\t\t}\n\t\tlet latestCompleteExchange = messages.length - 1;\n\t\tconst completedAssistants: number[] = [];\n\t\tfor (const [index, message] of anchoredMessages.entries()) {\n\t\t\tif (message.role !== \"assistant\") continue;\n\t\t\tconst calls = message.content.filter((block) => block.type === \"toolCall\");\n\t\t\tconst completeExchange = calls.length > 0 && calls.every((call) => (resultEnds.get(call.id) ?? -1) > index);\n\t\t\tif (completeExchange) latestCompleteExchange = index;\n\t\t\tif (completeExchange || (!calls.length && message.stopReason === \"stop\")) completedAssistants.push(index);\n\t\t\tfor (const call of calls) {\n\t\t\t\tconst end = resultEnds.get(call.id);\n\t\t\t\tif (end !== undefined && end > index) spans.push([index, end]);\n\t\t\t}\n\t\t}\n\t\t// A lone current instruction before its first exchange is not removable history.\n\t\trelaxRetention = completedAssistants.some((index) => index < latestCompleteExchange);\n\t\tif (relaxRetention) {\n\t\t\tcuts = cuts.filter(\n\t\t\t\t(candidate) =>\n\t\t\t\t\tcandidate <= latestCompleteExchange &&\n\t\t\t\t\tspans.every(([start, end]) => candidate <= start || candidate > end),\n\t\t\t);\n\t\t}\n\t}\n\tif (!cuts.length) return;\n\tconst tokenScale = compactionTokenScale(messages);\n\tlet cut = cuts[0];\n\tlet tokens = 0;\n\tfor (let index = messages.length - 1; index >= 0; index--) {\n\t\tif (!entryIds[index] || messages[index].role === \"compactionSummary\") continue;\n\t\ttokens += estimateTokens(messages[index]) * tokenScale;\n\t\tif (tokens >= settings.keepRecentTokens) {\n\t\t\t// Include the message that crossed the threshold and its preceding legal group boundary.\n\t\t\tcut = cuts.filter((candidate) => candidate <= index).at(-1) ?? cut;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (relaxRetention || (allowShortSession && cut === cuts[0])) cut = cuts.at(-1)!;\n\tif (maxCutEntryId !== undefined) {\n\t\tconst maximum = entryIds.indexOf(maxCutEntryId);\n\t\tconst lastAllowed = cuts.filter((candidate) => candidate <= maximum).at(-1);\n\t\tif (lastAllowed === undefined) throw new Error(\"Compaction recovery boundary is unavailable\");\n\t\tcut = Math.min(cut, lastAllowed);\n\t}\n\tlet turnStart = -1;\n\tif (messages[cut].role !== \"user\") {\n\t\tfor (let index = cut; index >= 0; index--) {\n\t\t\tif (entryIds[index] && [\"user\", \"custom\", \"branchSummary\", \"bashExecution\"].includes(messages[index].role)) {\n\t\t\t\tturnStart = index;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\tconst isSplitTurn = turnStart >= 0;\n\tconst historyEnd = isSplitTurn ? turnStart : cut;\n\tlet previousSummary: string | undefined;\n\tlet previousSummaryIndex = -1;\n\tfor (const [index, message] of messages.entries()) {\n\t\tif (message.role !== \"compactionSummary\") continue;\n\t\tpreviousSummary = message.summary;\n\t\tpreviousSummaryIndex = pathEntries.findIndex((entry) => entry.id === entryIds[index]);\n\t}\n\tconst historical = messages.filter(\n\t\t(message, index) => entryIds[index] && index < historyEnd && message.role !== \"compactionSummary\",\n\t);\n\tconst turnPrefixMessages = isSplitTurn\n\t\t? messages.filter(\n\t\t\t\t(message, index) =>\n\t\t\t\t\tentryIds[index] && index >= turnStart && index < cut && message.role !== \"compactionSummary\",\n\t\t\t)\n\t\t: [];\n\tif (!historical.length && !turnPrefixMessages.length && (budgetPressure || allowShortSession || !previousSummary))\n\t\treturn;\n\t// Virtual TaskFrame displays are continuity input, never a canonical suffix boundary.\n\tconst messagesToSummarize = messages.filter(\n\t\t(message, index) => message.role !== \"compactionSummary\" && (!entryIds[index] || index < historyEnd),\n\t);\n\tconst fileOps = extractFileOperations(messagesToSummarize, pathEntries, previousSummaryIndex);\n\tfor (const message of turnPrefixMessages) extractFileOpsFromMessage(message, fileOps);\n\treturn {\n\t\tfirstKeptEntryId: entryIds[cut]!,\n\t\tmessagesToSummarize: structuredClone(messagesToSummarize),\n\t\tturnPrefixMessages: structuredClone(turnPrefixMessages),\n\t\tisSplitTurn,\n\t\ttokensBefore: estimateContextTokens([...messages]).tokens,\n\t\tpreviousSummary,\n\t\tfileOps,\n\t\tsettings,\n\t};\n}\n\nexport function prepareCompaction(\n\tpathEntries: SessionEntry[],\n\tsettings: CompactionSettings,\n\tallowShortSession = false,\n): CompactionPreparation | undefined {\n\tif (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === \"compaction\") {\n\t\treturn undefined;\n\t}\n\n\tlet prevCompactionIndex = -1;\n\tfor (let i = pathEntries.length - 1; i >= 0; i--) {\n\t\tif (pathEntries[i].type === \"compaction\") {\n\t\t\tprevCompactionIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tlet previousSummary: string | undefined;\n\tlet boundaryStart = 0;\n\tif (prevCompactionIndex >= 0) {\n\t\tconst prevCompaction = pathEntries[prevCompactionIndex] as CompactionEntry;\n\t\tpreviousSummary = prevCompaction.summary;\n\t\tconst firstKeptEntryIndex = pathEntries.findIndex((entry) => entry.id === prevCompaction.firstKeptEntryId);\n\t\tboundaryStart = firstKeptEntryIndex >= 0 ? firstKeptEntryIndex : prevCompactionIndex + 1;\n\t}\n\tconst boundaryEnd = pathEntries.length;\n\n\tconst messages = buildSessionContext(pathEntries).messages;\n\tconst tokensBefore = estimateContextTokens(messages).tokens;\n\n\tconst cutPoint = findCutPoint(\n\t\tpathEntries,\n\t\tboundaryStart,\n\t\tboundaryEnd,\n\t\tsettings.keepRecentTokens,\n\t\tallowShortSession,\n\t\tcompactionTokenScale(messages),\n\t);\n\tconst firstKeptEntry = pathEntries[cutPoint.firstKeptEntryIndex];\n\tif (!firstKeptEntry?.id) {\n\t\treturn undefined; // Session needs migration\n\t}\n\tconst firstKeptEntryId = firstKeptEntry.id;\n\n\tconst historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptEntryIndex;\n\tconst messagesToSummarize: AgentMessage[] = [];\n\tfor (let i = boundaryStart; i < historyEnd; i++) {\n\t\tconst msg = getMessageFromEntryForCompaction(pathEntries[i]);\n\t\tif (msg) messagesToSummarize.push(msg);\n\t}\n\tconst turnPrefixMessages: AgentMessage[] = [];\n\tif (cutPoint.isSplitTurn) {\n\t\tfor (let i = cutPoint.turnStartIndex; i < cutPoint.firstKeptEntryIndex; i++) {\n\t\t\tconst msg = getMessageFromEntryForCompaction(pathEntries[i]);\n\t\t\tif (msg) turnPrefixMessages.push(msg);\n\t\t}\n\t}\n\n\t// Avoid a compaction that would summarize no history.\n\tif (messagesToSummarize.length === 0 && turnPrefixMessages.length === 0 && (allowShortSession || !previousSummary)) {\n\t\treturn undefined;\n\t}\n\tconst fileOps = extractFileOperations(messagesToSummarize, pathEntries, prevCompactionIndex);\n\t// Split turns retain their suffix, but their prefix file operations still belong in the summary.\n\tif (cutPoint.isSplitTurn) {\n\t\tfor (const msg of turnPrefixMessages) {\n\t\t\textractFileOpsFromMessage(msg, fileOps);\n\t\t}\n\t}\n\n\treturn {\n\t\tfirstKeptEntryId,\n\t\tmessagesToSummarize,\n\t\tturnPrefixMessages,\n\t\tisSplitTurn: cutPoint.isSplitTurn,\n\t\ttokensBefore,\n\t\tpreviousSummary,\n\t\tfileOps,\n\t\tsettings,\n\t};\n}\nconst TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.\n\nSummarize the prefix to provide context for the retained suffix:\n\n## Original Request\n[What did the user ask for in this turn?]\n\n## Early Progress\n- [Key decisions and work done in the prefix]\n\n## Context for Suffix\n- [Information needed to understand the retained recent work]\n\nBe concise. Focus on what's needed to understand the kept suffix.`;\n\n/**\n * Generate summaries for compaction using prepared data.\n * Returns CompactionResult - SessionManager adds uuid/parentUuid when saving.\n *\n * @param preparation - Pre-calculated preparation from prepareCompaction()\n * @param customInstructions - Optional custom focus for the summary\n */\n/** Runs one summary wire call; hosts decorate each call with its own request identity. */\nexport type SummaryCallRunner = <T>(\n\tcall: (callHeaders: Record<string, string> | undefined) => Promise<T>,\n) => Promise<T>;\n\nexport async function compact(\n\tpreparation: CompactionPreparation,\n\tmodel: Model<any>,\n\tapiKey: string,\n\theaders?: Record<string, string>,\n\tcustomInstructions?: string,\n\tsignal?: AbortSignal,\n\tthinkingLevel?: ThinkingLevel,\n\tsummaryCall: SummaryCallRunner = (call) => call(headers),\n\trequests?: InferenceCoordinator,\n): Promise<CompactionResult> {\n\tconst {\n\t\tfirstKeptEntryId,\n\t\tmessagesToSummarize,\n\t\tturnPrefixMessages,\n\t\tisSplitTurn,\n\t\ttokensBefore,\n\t\tpreviousSummary,\n\t\tfileOps,\n\t\tsettings,\n\t} = preparation;\n\tlet summary: string;\n\tconst slices: SummarySlice[] = [];\n\n\tif (isSplitTurn && turnPrefixMessages.length > 0) {\n\t\t// Split turns make two wire calls with different bodies; each needs its own identity.\n\t\tconst [historyResult, turnPrefixResult] = await Promise.all([\n\t\t\tmessagesToSummarize.length > 0\n\t\t\t\t? summaryCall((callHeaders) =>\n\t\t\t\t\t\tgenerateSummary(\n\t\t\t\t\t\t\tmessagesToSummarize,\n\t\t\t\t\t\t\tmodel,\n\t\t\t\t\t\t\tsettings.reserveTokens,\n\t\t\t\t\t\t\tapiKey,\n\t\t\t\t\t\t\tcallHeaders,\n\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t\tcustomInstructions,\n\t\t\t\t\t\t\tpreviousSummary,\n\t\t\t\t\t\t\tthinkingLevel,\n\t\t\t\t\t\t\trequests,\n\t\t\t\t\t\t),\n\t\t\t\t\t)\n\t\t\t\t: Promise.resolve<SummarySlice>({ summary: \"No prior history.\" }),\n\t\t\tsummaryCall((callHeaders) =>\n\t\t\t\tgenerateTurnPrefixSummary(\n\t\t\t\t\tturnPrefixMessages,\n\t\t\t\t\tmodel,\n\t\t\t\t\tsettings.reserveTokens,\n\t\t\t\t\tapiKey,\n\t\t\t\t\tcallHeaders,\n\t\t\t\t\tsignal,\n\t\t\t\t\tthinkingLevel,\n\t\t\t\t\trequests,\n\t\t\t\t),\n\t\t\t),\n\t\t]);\n\t\tslices.push(historyResult, turnPrefixResult);\n\t\tsummary = `${historyResult.summary}\\n\\n---\\n\\n**Turn Context (split turn):**\\n\\n${turnPrefixResult.summary}`;\n\t} else {\n\t\tconst result = await summaryCall((callHeaders) =>\n\t\t\tgenerateSummary(\n\t\t\t\tmessagesToSummarize,\n\t\t\t\tmodel,\n\t\t\t\tsettings.reserveTokens,\n\t\t\t\tapiKey,\n\t\t\t\tcallHeaders,\n\t\t\t\tsignal,\n\t\t\t\tcustomInstructions,\n\t\t\t\tpreviousSummary,\n\t\t\t\tthinkingLevel,\n\t\t\t\trequests,\n\t\t\t),\n\t\t);\n\t\tslices.push(result);\n\t\tsummary = result.summary;\n\t}\n\tconst { readFiles, modifiedFiles } = computeFileLists(fileOps);\n\tsummary += formatFileOperations(readFiles, modifiedFiles);\n\n\tif (!firstKeptEntryId) {\n\t\tthrow new Error(\"First kept entry has no UUID - session may need migration\");\n\t}\n\n\tlet usage: Usage | undefined;\n\tfor (const slice of slices) {\n\t\tif (!slice.usage) continue;\n\t\tusage ??= emptyUsage();\n\t\taddAssistantUsage(usage, slice.usage);\n\t}\n\tconst result: CompactionResult = {\n\t\tsummary,\n\t\tfirstKeptEntryId,\n\t\ttokensBefore,\n\t\tdetails: { readFiles, modifiedFiles } as CompactionDetails,\n\t\tusage,\n\t};\n\tconst bindings = slices.flatMap((slice) => {\n\t\tconst captured = nativeSummarySlices.get(slice);\n\t\tnativeSummarySlices.delete(slice);\n\t\treturn captured?.summary === slice.summary ? [captured.binding] : [];\n\t});\n\tif (bindings.length) nativeCompactionResults.set(result, { summary, bindings });\n\treturn result;\n}\n\n/**\n * Generate a summary for a turn prefix (when splitting a turn).\n */\nasync function generateTurnPrefixSummary(\n\tmessages: AgentMessage[],\n\tmodel: Model<any>,\n\treserveTokens: number,\n\tapiKey: string,\n\theaders?: Record<string, string>,\n\tsignal?: AbortSignal,\n\tthinkingLevel?: ThinkingLevel,\n\trequests?: InferenceCoordinator,\n): Promise<SummarySlice> {\n\tconst maxTokens = Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix\n\tconst llmMessages = convertToLlm(messages);\n\tconst conversationText = serializeConversation(llmMessages);\n\tconst promptText = `<conversation>\\n${conversationText}\\n</conversation>\\n\\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;\n\tconst summarizationMessages = [\n\t\t{\n\t\t\trole: \"user\" as const,\n\t\t\tcontent: [{ type: \"text\" as const, text: promptText }],\n\t\t\ttimestamp: Date.now(),\n\t\t},\n\t];\n\n\tconst completion = completeInference(\n\t\trequests,\n\t\tmodel,\n\t\t{ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },\n\t\tmodel.reasoning && thinkingLevel && thinkingLevel !== \"off\"\n\t\t\t? { maxTokens, signal, apiKey, headers, reasoning: thinkingLevel }\n\t\t\t: { maxTokens, signal, apiKey, headers },\n\t\t{\n\t\t\tpurpose: \"summary\",\n\t\t\tpurposeDetail: \"compaction-turn-prefix\",\n\t\t\toperationId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t\tsemanticEdgeId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t},\n\t);\n\n\tconst response = await completion;\n\tif (response.stopReason === \"error\") {\n\t\tthrow new Error(`Turn prefix summarization failed: ${response.errorMessage || \"Unknown error\"}`);\n\t}\n\n\tconst slice: SummarySlice = {\n\t\tsummary: response.content\n\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t.map((c) => c.text)\n\t\t\t.join(\"\\n\"),\n\t\tusage: response.usage,\n\t};\n\treturn captureSummarySlice(slice, requests, completion, \"turn-prefix\");\n}\n"]}
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/compaction.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Context compaction for long sessions.\n *\n * Pure functions for compaction logic. The session manager handles I/O,\n * and after compaction the session is reloaded.\n */\n\nimport type { AgentMessage, ThinkingLevel } from \"@ponythewhite/base-context-agent\";\nimport type { AssistantMessage, Model, Usage } from \"@ponythewhite/base-context-ai\";\nimport {\n\tcompleteInference,\n\tInferenceCoordinator,\n\ttype NativeCompactionOutputBinding,\n} from \"../inference-coordinator.js\";\nimport {\n\tCOMPACTION_SUMMARY_PREFIX,\n\tCOMPACTION_SUMMARY_SUFFIX,\n\tconvertToLlm,\n\tcreateBranchSummaryMessage,\n\tcreateCompactionSummaryMessage,\n\tcreateCustomMessage,\n} from \"../messages.js\";\nimport type { NativeCompactionRequestOutputAssociation } from \"../request-events.js\";\nimport { MODEL_REQUEST_ID_HEADER } from \"../semantic-edges.js\";\nimport { buildSessionContext, type CompactionEntry, type SessionEntry } from \"../session-manager.js\";\nimport { addAssistantUsage, emptyUsage } from \"../usage.js\";\nimport {\n\tcomputeFileLists,\n\tcreateFileOps,\n\textractFileOpsFromMessage,\n\ttype FileOperations,\n\tformatFileOperations,\n\tSUMMARIZATION_SYSTEM_PROMPT,\n\tserializeConversation,\n} from \"./utils.js\";\n/** Details stored in CompactionEntry.details for file tracking */\nexport interface CompactionDetails {\n\treadFiles: string[];\n\tmodifiedFiles: string[];\n}\n\nexport interface SummarySlice {\n\tsummary: string;\n\tusage?: Usage;\n}\n\n// Identity follows the actual completion -> text slice -> built-in composition, never copied fields.\nconst nativeSummarySlices = new WeakMap<SummarySlice, { summary: string; binding: NativeCompactionOutputBinding }>();\nconst nativeCompactionResults = new WeakMap<object, { summary: string; bindings: NativeCompactionOutputBinding[] }>();\n\nfunction captureSummarySlice(\n\tslice: SummarySlice,\n\trequests: InferenceCoordinator | undefined,\n\tcompletion: Promise<AssistantMessage>,\n\tpart: NativeCompactionRequestOutputAssociation[\"part\"],\n): SummarySlice {\n\tconst binding =\n\t\trequests instanceof InferenceCoordinator\n\t\t\t? InferenceCoordinator.prototype.takeCompactionOutput.call(requests, completion)\n\t\t\t: undefined;\n\tif (binding?.output.part === part) nativeSummarySlices.set(slice, { summary: slice.summary, binding });\n\treturn slice;\n}\n\n/** Internal append input: only this exact built-in result and original sink can contribute links. */\nexport function takeCompactionRequestOutputs(\n\tresult: object | undefined,\n\tsink: object,\n\tsummary: string,\n): readonly NativeCompactionRequestOutputAssociation[] | undefined {\n\tconst captured = result ? nativeCompactionResults.get(result) : undefined;\n\tif (result) nativeCompactionResults.delete(result);\n\t// Equality only checks an already privately bound projection for mutation; it never discovers a link.\n\tif (!captured || captured.summary !== summary) return undefined;\n\tconst outputs = captured.bindings.filter((binding) => binding.sink === sink).map((binding) => binding.output);\n\treturn outputs.length ? outputs : undefined;\n}\n\n/**\n * Extract file operations from messages and previous compaction entries.\n */\n/** Preserve file operations recorded by prior compactions and current tool calls. */\nfunction extractFileOperations(\n\tmessages: AgentMessage[],\n\tentries: SessionEntry[],\n\tprevCompactionIndex: number,\n): FileOperations {\n\tconst fileOps = createFileOps();\n\tif (prevCompactionIndex >= 0) {\n\t\tconst prevCompaction = entries[prevCompactionIndex] as CompactionEntry;\n\t\tif (!prevCompaction.fromHook && prevCompaction.details) {\n\t\t\t// fromHook field kept for session file compatibility\n\t\t\tconst details = prevCompaction.details as CompactionDetails;\n\t\t\tif (Array.isArray(details.readFiles)) {\n\t\t\t\tfor (const f of details.readFiles) fileOps.read.add(f);\n\t\t\t}\n\t\t\tif (Array.isArray(details.modifiedFiles)) {\n\t\t\t\tfor (const f of details.modifiedFiles) fileOps.edited.add(f);\n\t\t\t}\n\t\t}\n\t}\n\tfor (const msg of messages) {\n\t\textractFileOpsFromMessage(msg, fileOps);\n\t}\n\n\treturn fileOps;\n}\n/**\n * Extract AgentMessage from an entry if it produces one.\n * Returns undefined for entries that don't contribute to LLM context.\n */\nfunction getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {\n\tif (entry.type === \"message\") {\n\t\treturn entry.message;\n\t}\n\tif (entry.type === \"custom_message\") {\n\t\treturn createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp);\n\t}\n\tif (entry.type === \"branch_summary\") {\n\t\treturn createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);\n\t}\n\tif (entry.type === \"compaction\") {\n\t\treturn createCompactionSummaryMessage(\n\t\t\tentry.summary,\n\t\t\tentry.tokensBefore,\n\t\t\tentry.timestamp,\n\t\t\tentry.customInstructions,\n\t\t);\n\t}\n\treturn undefined;\n}\n\nfunction getMessageFromEntryForCompaction(entry: SessionEntry): AgentMessage | undefined {\n\tif (entry.type === \"compaction\") {\n\t\treturn undefined;\n\t}\n\treturn getMessageFromEntry(entry);\n}\n\n/** Result from compact() - SessionManager adds uuid/parentUuid when saving */\nexport interface CompactionResult<T = unknown> {\n\tsummary: string;\n\tfirstKeptEntryId: string;\n\t/** Prior-context estimate; null when the original context is not measurable. */\n\ttokensBefore: number | null;\n\t/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */\n\tdetails?: T;\n\t/** What the summarization call(s) billed; persisted on the compaction entry. */\n\tusage?: Usage;\n}\nexport const COMPACT_SKILL_NAME = \"compact\";\n\nexport interface CompactionSettings {\n\tenabled: boolean;\n\treserveTokens: number;\n\tkeepRecentTokens: number;\n}\n\nexport const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {\n\tenabled: true,\n\treserveTokens: 16384,\n\tkeepRecentTokens: 20000,\n};\n/**\n * Calculate total context tokens from usage.\n * Uses the native totalTokens field when available, falls back to computing from components.\n *\n * Includes output: the assistant's response becomes part of the prompt on the next\n * request, so it counts toward the context the next turn will send.\n */\nexport function calculateContextTokens(usage: Usage): number {\n\treturn usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;\n}\n\n/**\n * Get usage from an assistant message if available.\n * Skips aborted and error messages as they don't have valid usage data.\n */\nfunction getAssistantUsage(msg: AgentMessage): Usage | undefined {\n\tif (msg.role === \"assistant\" && \"usage\" in msg) {\n\t\tconst assistantMsg = msg as AssistantMessage;\n\t\tif (assistantMsg.stopReason !== \"aborted\" && assistantMsg.stopReason !== \"error\" && assistantMsg.usage) {\n\t\t\treturn assistantMsg.usage;\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/**\n * Find the last non-aborted assistant message usage from session entries.\n */\nexport function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined {\n\tfor (let i = entries.length - 1; i >= 0; i--) {\n\t\tconst entry = entries[i];\n\t\tif (entry.type === \"message\") {\n\t\t\tconst usage = getAssistantUsage(entry.message);\n\t\t\tif (usage) return usage;\n\t\t}\n\t}\n\treturn undefined;\n}\n\nexport interface ContextUsageEstimate {\n\ttokens: number;\n\tusageTokens: number;\n\ttrailingTokens: number;\n\tlastUsageIndex: number | null;\n}\n\nfunction getLastAssistantUsageInfo(messages: readonly AgentMessage[]): { usage: Usage; index: number } | undefined {\n\tfor (let i = messages.length - 1; i >= 0; i--) {\n\t\tconst usage = getAssistantUsage(messages[i]);\n\t\tif (usage) return { usage, index: i };\n\t}\n\treturn undefined;\n}\n\n/**\n * Estimate context tokens from messages, using the last assistant usage when available.\n * If there are messages after the last usage, estimate their tokens with estimateTokens.\n */\nexport function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate {\n\tconst usageInfo = getLastAssistantUsageInfo(messages);\n\n\tif (!usageInfo) {\n\t\tlet estimated = 0;\n\t\tfor (const message of messages) {\n\t\t\testimated += estimateTokens(message);\n\t\t}\n\t\treturn {\n\t\t\ttokens: estimated,\n\t\t\tusageTokens: 0,\n\t\t\ttrailingTokens: estimated,\n\t\t\tlastUsageIndex: null,\n\t\t};\n\t}\n\n\tconst usageTokens = calculateContextTokens(usageInfo.usage);\n\tlet trailingTokens = 0;\n\tfor (let i = usageInfo.index + 1; i < messages.length; i++) {\n\t\ttrailingTokens += estimateTokens(messages[i]);\n\t}\n\n\treturn {\n\t\ttokens: usageTokens + trailingTokens,\n\t\tusageTokens,\n\t\ttrailingTokens,\n\t\tlastUsageIndex: usageInfo.index,\n\t};\n}\n\n/**\n * Check if compaction should trigger based on context usage.\n */\nexport function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {\n\tif (!settings.enabled) return false;\n\tif (contextWindow <= 0) return false;\n\treturn contextTokens > contextWindow - settings.reserveTokens;\n}\n/** Raise suffix estimates when observed usage exceeds chars/4 for the same prefix. */\nfunction compactionTokenScale(messages: readonly AgentMessage[]): number {\n\tconst usageInfo = getLastAssistantUsageInfo(messages);\n\tif (!usageInfo) return 1;\n\tlet estimatedTokens = 0;\n\tfor (let index = 0; index <= usageInfo.index; index++) {\n\t\testimatedTokens += estimateTokens(messages[index]);\n\t}\n\treturn estimatedTokens > 0 ? Math.max(1, calculateContextTokens(usageInfo.usage) / estimatedTokens) : 1;\n}\n\n/** Estimate message tokens with chars/4; dense content can exceed this heuristic. */\nexport function estimateTokens(message: AgentMessage): number {\n\tlet chars = 0;\n\n\tswitch (message.role) {\n\t\tcase \"user\": {\n\t\t\tconst content = (message as { content: string | Array<{ type: string; text?: string }> }).content;\n\t\t\tif (typeof content === \"string\") {\n\t\t\t\tchars = content.length;\n\t\t\t} else if (Array.isArray(content)) {\n\t\t\t\tfor (const block of content) {\n\t\t\t\t\tif (block.type === \"text\" && block.text) {\n\t\t\t\t\t\tchars += block.text.length;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"assistant\": {\n\t\t\tconst assistant = message as AssistantMessage;\n\t\t\tfor (const block of assistant.content) {\n\t\t\t\tif (block.type === \"text\") {\n\t\t\t\t\tchars += block.text.length;\n\t\t\t\t} else if (block.type === \"thinking\") {\n\t\t\t\t\tchars += block.thinking.length;\n\t\t\t\t} else if (block.type === \"toolCall\") {\n\t\t\t\t\tchars += block.name.length + JSON.stringify(block.arguments).length;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"custom\":\n\t\tcase \"toolResult\": {\n\t\t\tif (typeof message.content === \"string\") {\n\t\t\t\tchars = message.content.length;\n\t\t\t} else {\n\t\t\t\tfor (const block of message.content) {\n\t\t\t\t\tif (block.type === \"text\" && block.text) {\n\t\t\t\t\t\tchars += block.text.length;\n\t\t\t\t\t}\n\t\t\t\t\tif (block.type === \"image\") {\n\t\t\t\t\t\tchars += 4800; // Estimate images as 4000 chars, or 1200 tokens\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"bashExecution\": {\n\t\t\tchars = message.command.length + message.output.length;\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t\tcase \"branchSummary\":\n\t\tcase \"compactionSummary\": {\n\t\t\tchars = message.summary.length;\n\t\t\treturn Math.ceil(chars / 4);\n\t\t}\n\t}\n\n\treturn 0;\n}\n\n/**\n * Find valid cut points: indices of user, assistant, custom, or bashExecution messages.\n * Never cut at tool results (they must follow their tool call).\n * When we cut at an assistant message with tool calls, its tool results follow it\n * and will be kept.\n * BashExecutionMessage is treated like a user message (user-initiated context).\n */\nfunction findValidCutPoints(entries: SessionEntry[], startIndex: number, endIndex: number): number[] {\n\tconst cutPoints: number[] = [];\n\tfor (let i = startIndex; i < endIndex; i++) {\n\t\tconst entry = entries[i];\n\t\tswitch (entry.type) {\n\t\t\tcase \"message\": {\n\t\t\t\tconst role = entry.message.role;\n\t\t\t\tswitch (role) {\n\t\t\t\t\tcase \"bashExecution\":\n\t\t\t\t\tcase \"custom\":\n\t\t\t\t\tcase \"branchSummary\":\n\t\t\t\t\tcase \"compactionSummary\":\n\t\t\t\t\tcase \"user\":\n\t\t\t\t\tcase \"assistant\":\n\t\t\t\t\t\tcutPoints.push(i);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"toolResult\":\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase \"thinking_level_change\":\n\t\t\tcase \"model_change\":\n\t\t\tcase \"compaction\":\n\t\t\tcase \"branch_summary\":\n\t\t\tcase \"custom\":\n\t\t\tcase \"custom_message\":\n\t\t\tcase \"label\":\n\t\t\tcase \"session_info\":\n\t\t\t\tbreak;\n\t\t}\n\t\t// Branch summaries and custom messages are user-role turn boundaries.\n\t\tif (entry.type === \"branch_summary\" || entry.type === \"custom_message\") {\n\t\t\tcutPoints.push(i);\n\t\t}\n\t}\n\treturn cutPoints;\n}\n\n/**\n * Find the user message (or bashExecution) that starts the turn containing the given entry index.\n * Returns -1 if no turn start found before the index.\n * BashExecutionMessage is treated like a user message for turn boundaries.\n */\nexport function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number {\n\tfor (let i = entryIndex; i >= startIndex; i--) {\n\t\tconst entry = entries[i];\n\t\tif (entry.type === \"branch_summary\" || entry.type === \"custom_message\") {\n\t\t\treturn i;\n\t\t}\n\t\tif (entry.type === \"message\") {\n\t\t\tconst role = entry.message.role;\n\t\t\tif (role === \"user\" || role === \"bashExecution\") {\n\t\t\t\treturn i;\n\t\t\t}\n\t\t}\n\t}\n\treturn -1;\n}\n\nexport interface CutPointResult {\n\t/** Index of first entry to keep */\n\tfirstKeptEntryIndex: number;\n\t/** Index of user message that starts the turn being split, or -1 if not splitting */\n\tturnStartIndex: number;\n\t/** Whether this cut splits a turn (cut point is not a user message) */\n\tisSplitTurn: boolean;\n}\n\n/**\n * Find the cut point in session entries that keeps approximately `keepRecentTokens`.\n *\n * Algorithm: Walk backwards from newest, accumulating estimated message sizes.\n * Stop when we've accumulated >= keepRecentTokens. Cut at that point.\n *\n * Can cut at user OR assistant messages (never tool results). When cutting at an\n * assistant message with tool calls, its tool results come after and will be kept.\n *\n * Returns CutPointResult with:\n * - firstKeptEntryIndex: the entry index to start keeping from\n * - turnStartIndex: if cutting mid-turn, the user message that started that turn\n * - isSplitTurn: whether we're cutting in the middle of a turn\n *\n * Only considers entries between `startIndex` and `endIndex` (exclusive).\n */\nexport function findCutPoint(\n\tentries: SessionEntry[],\n\tstartIndex: number,\n\tendIndex: number,\n\tkeepRecentTokens: number,\n\tallowShortSession = false,\n\ttokenScale = 1,\n): CutPointResult {\n\tconst cutPoints = findValidCutPoints(entries, startIndex, endIndex);\n\n\tif (cutPoints.length === 0) {\n\t\treturn { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false };\n\t}\n\tlet accumulatedTokens = 0;\n\tlet cutIndex = cutPoints[0]; // Default: keep from first message (not header)\n\n\tfor (let i = endIndex - 1; i >= startIndex; i--) {\n\t\tconst entry = entries[i];\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst messageTokens = estimateTokens(entry.message) * tokenScale;\n\t\taccumulatedTokens += messageTokens;\n\t\tif (accumulatedTokens >= keepRecentTokens) {\n\t\t\tcutIndex = cutPoints.filter((candidate) => candidate <= i).at(-1) ?? cutIndex;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (allowShortSession && cutIndex === cutPoints[0]) {\n\t\t// An explicit compact may summarize a short prefix, but must keep a real suffix.\n\t\tconst latest = cutPoints\n\t\t\t.filter((index) => {\n\t\t\t\tconst entry = entries[index];\n\t\t\t\treturn entry.type !== \"message\" || entry.message.role !== \"compactionSummary\";\n\t\t\t})\n\t\t\t.at(-1);\n\t\tif (latest !== undefined) cutIndex = latest;\n\t}\n\twhile (cutIndex > startIndex) {\n\t\tconst prevEntry = entries[cutIndex - 1];\n\t\tif (prevEntry.type === \"compaction\") {\n\t\t\tbreak;\n\t\t}\n\t\tif (prevEntry.type === \"message\") {\n\t\t\tbreak;\n\t\t}\n\t\tcutIndex--;\n\t}\n\tconst cutEntry = entries[cutIndex];\n\tconst isUserMessage = cutEntry.type === \"message\" && cutEntry.message.role === \"user\";\n\t// A cut in a non-user turn requires a prefix summary.\n\tconst turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);\n\n\treturn {\n\t\tfirstKeptEntryIndex: cutIndex,\n\t\tturnStartIndex,\n\t\tisSplitTurn: !isUserMessage && turnStartIndex !== -1,\n\t};\n}\nconst SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.\n\nUse this EXACT format:\n\n## Goal\n[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements mentioned by user]\n- [Or \"(none)\" if none were mentioned]\n\n## Progress\n### Done\n- [x] [Completed tasks/changes]\n\n### In Progress\n- [ ] [Current work]\n\n### Blocked\n- [Issues preventing progress, if any]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Ordered list of what should happen next]\n\n## Critical Context\n- [Any data, examples, or references needed to continue]\n- [Or \"(none)\" if not applicable]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.`;\n\nconst RUNTIME_STATE_SUMMARY_NOTE =\n\t\"Runtime note: this summary does not establish whether a Python kernel is live or whether its variables, imports, helpers, or jobs remain available. Preserve useful names and their last observed state, including uncertainty. Use current runtime reports before relying on them; do not infer either survival or loss from compaction.\";\n\nconst UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.\n\nUpdate the existing structured summary with new information. RULES:\n- PRESERVE all existing information from the previous summary\n- ADD new progress, decisions, and context from the new messages\n- UPDATE the Progress section: move items from \"In Progress\" to \"Done\" when completed\n- UPDATE \"Next Steps\" based on what was accomplished\n- PRESERVE exact file paths, function names, and error messages\n- If something is no longer relevant, you may remove it\n\nUse this EXACT format:\n\n## Goal\n[Preserve existing goals, add new ones if the task expanded]\n\n## Constraints & Preferences\n- [Preserve existing, add new ones discovered]\n\n## Progress\n### Done\n- [x] [Include previously done items AND newly completed items]\n\n### In Progress\n- [ ] [Current work - update based on progress]\n\n### Blocked\n- [Current blockers - remove if resolved]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale] (preserve all previous, add new)\n\n## Next Steps\n1. [Update based on current state]\n\n## Critical Context\n- [Preserve important context, add new if needed]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.`;\n\n/**\n * Build the instruction portion of the summarization prompt: the initial or\n * update template, optional user instructions, and the runtime-state qualification.\n */\nexport function buildSummarizationPrompt(customInstructions?: string, previousSummary?: string): string {\n\tlet basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;\n\tif (customInstructions) {\n\t\tbasePrompt += `\\n\\n<user-instructions>\\nThe user provided these instructions for this summary. Follow them with high priority while keeping the section format above: emphasize what they ask to focus on, and preserve verbatim anything they ask to remember.\\n${customInstructions}\\n</user-instructions>`;\n\t}\n\treturn `${basePrompt}\\n\\n${RUNTIME_STATE_SUMMARY_NOTE}`;\n}\n\n/**\n * Generate a summary of the conversation using the LLM.\n * If previousSummary is provided, uses the update prompt to merge.\n */\nexport async function generateSummary(\n\tcurrentMessages: AgentMessage[],\n\tmodel: Model<any>,\n\treserveTokens: number,\n\tapiKey: string,\n\theaders?: Record<string, string>,\n\tsignal?: AbortSignal,\n\tcustomInstructions?: string,\n\tpreviousSummary?: string,\n\tthinkingLevel?: ThinkingLevel,\n\trequests?: InferenceCoordinator,\n\toutputTokenLimit?: number,\n): Promise<SummarySlice> {\n\tconst maxTokens = outputTokenLimit ?? Math.floor(0.8 * reserveTokens);\n\n\tconst basePrompt = buildSummarizationPrompt(customInstructions, previousSummary);\n\t// Serialize before the LLM call so it summarizes rather than continues this conversation.\n\tconst llmMessages = convertToLlm(currentMessages);\n\tconst conversationText = serializeConversation(llmMessages);\n\tlet promptText = `<conversation>\\n${conversationText}\\n</conversation>\\n\\n`;\n\tif (previousSummary) {\n\t\tpromptText += `<previous-summary>\\n${previousSummary}\\n</previous-summary>\\n\\n`;\n\t}\n\tpromptText += basePrompt;\n\n\tconst summarizationMessages = [\n\t\t{\n\t\t\trole: \"user\" as const,\n\t\t\tcontent: [{ type: \"text\" as const, text: promptText }],\n\t\t\ttimestamp: Date.now(),\n\t\t},\n\t];\n\n\tconst completionOptions =\n\t\tmodel.reasoning && thinkingLevel && thinkingLevel !== \"off\"\n\t\t\t? { maxTokens, signal, apiKey, headers, reasoning: thinkingLevel }\n\t\t\t: { maxTokens, signal, apiKey, headers };\n\n\tconst completion = completeInference(\n\t\trequests,\n\t\tmodel,\n\t\t{ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },\n\t\tcompletionOptions,\n\t\t{\n\t\t\tpurpose: \"summary\",\n\t\t\tpurposeDetail: \"compaction\",\n\t\t\toperationId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t\tsemanticEdgeId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t},\n\t);\n\n\tconst response = await completion;\n\tif (response.stopReason === \"error\") {\n\t\tthrow new Error(`Summarization failed: ${response.errorMessage || \"Unknown error\"}`);\n\t}\n\n\tconst textContent = response.content\n\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t.map((c) => c.text)\n\t\t.join(\"\\n\");\n\n\treturn captureSummarySlice({ summary: textContent, usage: response.usage }, requests, completion, \"history\");\n}\nexport interface CompactionPreparation {\n\t/** UUID of first entry to keep */\n\tfirstKeptEntryId: string;\n\t/** Messages that will be summarized and discarded */\n\tmessagesToSummarize: AgentMessage[];\n\t/** Messages that will be turned into turn prefix summary (if splitting) */\n\tturnPrefixMessages: AgentMessage[];\n\t/** Whether this is a split turn (cut point in middle of turn) */\n\tisSplitTurn: boolean;\n\ttokensBefore: number;\n\t/** Summary from previous compaction, for iterative update */\n\tpreviousSummary?: string;\n\t/** File operations extracted from messagesToSummarize */\n\tfileOps: FileOperations;\n\t/** Compaction settions from settings.jsonl\t*/\n\tsettings: CompactionSettings;\n}\n\n/** Prepare the actual selected epoch view. Entry IDs are only real cut anchors, never synthetic rows. */\nexport function prepareViewCompaction(\n\tmessages: readonly AgentMessage[],\n\tentryIds: readonly (string | undefined)[],\n\tpathEntries: SessionEntry[],\n\tsettings: CompactionSettings,\n\tmaxCutEntryId?: string,\n\tallowShortSession = false,\n\tbudgetPressure = false,\n): CompactionPreparation | undefined {\n\tif (messages.length !== entryIds.length) throw new Error(\"Compaction views do not match their source anchors\");\n\t// firstKeptEntryId restores a chronological source suffix, not a selected-view suffix.\n\t// Older pinned views cannot become cut anchors across omitted source messages.\n\tconst selectedIds = new Set(entryIds);\n\tconst suffixAnchors = new Set<string>();\n\tfor (let index = pathEntries.length - 1; index >= 0; index--) {\n\t\tconst entry = pathEntries[index];\n\t\tif (!getMessageFromEntryForCompaction(entry)) continue;\n\t\tif (!selectedIds.has(entry.id)) break;\n\t\tsuffixAnchors.add(entry.id);\n\t}\n\tlet cuts = messages.flatMap((message, index) =>\n\t\tentryIds[index] &&\n\t\tsuffixAnchors.has(entryIds[index]!) &&\n\t\tmessage.role !== \"toolResult\" &&\n\t\tmessage.role !== \"compactionSummary\"\n\t\t\t? [index]\n\t\t\t: [],\n\t);\n\tlet relaxRetention = false;\n\tif (budgetPressure) {\n\t\t// Only caller-confirmed public OVER may relax retention; source/tool groups remain whole.\n\t\tconst spans: [number, number][] = [];\n\t\tconst sourceStarts = new Map<string, number>();\n\t\tconst resultEnds = new Map<string, number>();\n\t\t// Public history renders original roles as custom text; use its captured source anchors.\n\t\tconst sourceMessages = new Map(pathEntries.map((entry) => [entry.id, getMessageFromEntry(entry)]));\n\t\tconst anchoredMessages = messages.map((message, index) => sourceMessages.get(entryIds[index] ?? \"\") ?? message);\n\t\tfor (const [index, message] of anchoredMessages.entries()) {\n\t\t\tconst entryId = entryIds[index];\n\t\t\tif (entryId) {\n\t\t\t\tconst start = sourceStarts.get(entryId);\n\t\t\t\tif (start === undefined) sourceStarts.set(entryId, index);\n\t\t\t\telse spans.push([start, index]);\n\t\t\t}\n\t\t\tif (message.role === \"toolResult\") resultEnds.set(message.toolCallId, index);\n\t\t}\n\t\tlet latestCompleteExchange = messages.length - 1;\n\t\tconst completedAssistants: number[] = [];\n\t\tfor (const [index, message] of anchoredMessages.entries()) {\n\t\t\tif (message.role !== \"assistant\") continue;\n\t\t\tconst calls = message.content.filter((block) => block.type === \"toolCall\");\n\t\t\tconst completeExchange = calls.length > 0 && calls.every((call) => (resultEnds.get(call.id) ?? -1) > index);\n\t\t\tif (completeExchange) latestCompleteExchange = index;\n\t\t\tif (completeExchange || (!calls.length && message.stopReason === \"stop\")) completedAssistants.push(index);\n\t\t\tfor (const call of calls) {\n\t\t\t\tconst end = resultEnds.get(call.id);\n\t\t\t\tif (end !== undefined && end > index) spans.push([index, end]);\n\t\t\t}\n\t\t}\n\t\t// A lone current instruction before its first exchange is not removable history.\n\t\trelaxRetention = completedAssistants.some((index) => index < latestCompleteExchange);\n\t\tif (relaxRetention) {\n\t\t\tcuts = cuts.filter(\n\t\t\t\t(candidate) =>\n\t\t\t\t\tcandidate <= latestCompleteExchange &&\n\t\t\t\t\tspans.every(([start, end]) => candidate <= start || candidate > end),\n\t\t\t);\n\t\t}\n\t}\n\tif (!cuts.length) return;\n\tconst tokenScale = compactionTokenScale(messages);\n\tlet cut = cuts[0];\n\tlet tokens = 0;\n\tfor (let index = messages.length - 1; index >= 0; index--) {\n\t\tif (!entryIds[index] || messages[index].role === \"compactionSummary\") continue;\n\t\ttokens += estimateTokens(messages[index]) * tokenScale;\n\t\tif (tokens >= settings.keepRecentTokens) {\n\t\t\t// Include the message that crossed the threshold and its preceding legal group boundary.\n\t\t\tcut = cuts.filter((candidate) => candidate <= index).at(-1) ?? cut;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (relaxRetention || (allowShortSession && cut === cuts[0])) cut = cuts.at(-1)!;\n\tif (maxCutEntryId !== undefined) {\n\t\tconst maximum = entryIds.indexOf(maxCutEntryId);\n\t\tconst lastAllowed = cuts.filter((candidate) => candidate <= maximum).at(-1);\n\t\tif (lastAllowed === undefined) throw new Error(\"Compaction recovery boundary is unavailable\");\n\t\tcut = Math.min(cut, lastAllowed);\n\t}\n\tlet turnStart = -1;\n\tif (messages[cut].role !== \"user\") {\n\t\tfor (let index = cut; index >= 0; index--) {\n\t\t\tif (entryIds[index] && [\"user\", \"custom\", \"branchSummary\", \"bashExecution\"].includes(messages[index].role)) {\n\t\t\t\tturnStart = index;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\tconst isSplitTurn = turnStart >= 0;\n\tconst historyEnd = isSplitTurn ? turnStart : cut;\n\tlet previousSummary: string | undefined;\n\tlet previousSummaryIndex = -1;\n\tfor (const [index, message] of messages.entries()) {\n\t\tif (message.role !== \"compactionSummary\") continue;\n\t\tpreviousSummary = message.summary;\n\t\tpreviousSummaryIndex = pathEntries.findIndex((entry) => entry.id === entryIds[index]);\n\t}\n\tconst historical = messages.filter(\n\t\t(message, index) => entryIds[index] && index < historyEnd && message.role !== \"compactionSummary\",\n\t);\n\tconst turnPrefixMessages = isSplitTurn\n\t\t? messages.filter(\n\t\t\t\t(message, index) =>\n\t\t\t\t\tentryIds[index] && index >= turnStart && index < cut && message.role !== \"compactionSummary\",\n\t\t\t)\n\t\t: [];\n\tif (!historical.length && !turnPrefixMessages.length && (budgetPressure || allowShortSession || !previousSummary))\n\t\treturn;\n\t// Virtual TaskFrame displays are continuity input, never a canonical suffix boundary.\n\tconst messagesToSummarize = messages.filter(\n\t\t(message, index) => message.role !== \"compactionSummary\" && (!entryIds[index] || index < historyEnd),\n\t);\n\tconst fileOps = extractFileOperations(messagesToSummarize, pathEntries, previousSummaryIndex);\n\tfor (const message of turnPrefixMessages) extractFileOpsFromMessage(message, fileOps);\n\treturn {\n\t\tfirstKeptEntryId: entryIds[cut]!,\n\t\tmessagesToSummarize: structuredClone(messagesToSummarize),\n\t\tturnPrefixMessages: structuredClone(turnPrefixMessages),\n\t\tisSplitTurn,\n\t\ttokensBefore: estimateContextTokens([...messages]).tokens,\n\t\tpreviousSummary,\n\t\tfileOps,\n\t\tsettings,\n\t};\n}\n\nexport function prepareCompaction(\n\tpathEntries: SessionEntry[],\n\tsettings: CompactionSettings,\n\tallowShortSession = false,\n): CompactionPreparation | undefined {\n\tif (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === \"compaction\") {\n\t\treturn undefined;\n\t}\n\n\tlet prevCompactionIndex = -1;\n\tfor (let i = pathEntries.length - 1; i >= 0; i--) {\n\t\tif (pathEntries[i].type === \"compaction\") {\n\t\t\tprevCompactionIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tlet previousSummary: string | undefined;\n\tlet boundaryStart = 0;\n\tif (prevCompactionIndex >= 0) {\n\t\tconst prevCompaction = pathEntries[prevCompactionIndex] as CompactionEntry;\n\t\tpreviousSummary = prevCompaction.summary;\n\t\tconst firstKeptEntryIndex = pathEntries.findIndex((entry) => entry.id === prevCompaction.firstKeptEntryId);\n\t\tboundaryStart = firstKeptEntryIndex >= 0 ? firstKeptEntryIndex : prevCompactionIndex + 1;\n\t}\n\tconst boundaryEnd = pathEntries.length;\n\n\tconst messages = buildSessionContext(pathEntries).messages;\n\tconst tokensBefore = estimateContextTokens(messages).tokens;\n\n\tconst cutPoint = findCutPoint(\n\t\tpathEntries,\n\t\tboundaryStart,\n\t\tboundaryEnd,\n\t\tsettings.keepRecentTokens,\n\t\tallowShortSession,\n\t\tcompactionTokenScale(messages),\n\t);\n\tconst firstKeptEntry = pathEntries[cutPoint.firstKeptEntryIndex];\n\tif (!firstKeptEntry?.id) {\n\t\treturn undefined; // Session needs migration\n\t}\n\tconst firstKeptEntryId = firstKeptEntry.id;\n\n\tconst historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptEntryIndex;\n\tconst messagesToSummarize: AgentMessage[] = [];\n\tfor (let i = boundaryStart; i < historyEnd; i++) {\n\t\tconst msg = getMessageFromEntryForCompaction(pathEntries[i]);\n\t\tif (msg) messagesToSummarize.push(msg);\n\t}\n\tconst turnPrefixMessages: AgentMessage[] = [];\n\tif (cutPoint.isSplitTurn) {\n\t\tfor (let i = cutPoint.turnStartIndex; i < cutPoint.firstKeptEntryIndex; i++) {\n\t\t\tconst msg = getMessageFromEntryForCompaction(pathEntries[i]);\n\t\t\tif (msg) turnPrefixMessages.push(msg);\n\t\t}\n\t}\n\n\t// Avoid a compaction that would summarize no history.\n\tif (messagesToSummarize.length === 0 && turnPrefixMessages.length === 0 && (allowShortSession || !previousSummary)) {\n\t\treturn undefined;\n\t}\n\tconst fileOps = extractFileOperations(messagesToSummarize, pathEntries, prevCompactionIndex);\n\t// Split turns retain their suffix, but their prefix file operations still belong in the summary.\n\tif (cutPoint.isSplitTurn) {\n\t\tfor (const msg of turnPrefixMessages) {\n\t\t\textractFileOpsFromMessage(msg, fileOps);\n\t\t}\n\t}\n\n\treturn {\n\t\tfirstKeptEntryId,\n\t\tmessagesToSummarize,\n\t\tturnPrefixMessages,\n\t\tisSplitTurn: cutPoint.isSplitTurn,\n\t\ttokensBefore,\n\t\tpreviousSummary,\n\t\tfileOps,\n\t\tsettings,\n\t};\n}\nconst TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.\n\nSummarize the prefix to provide context for the retained suffix:\n\n## Original Request\n[What did the user ask for in this turn?]\n\n## Early Progress\n- [Key decisions and work done in the prefix]\n\n## Context for Suffix\n- [Information needed to understand the retained recent work]\n\nBe concise. Focus on what's needed to understand the kept suffix.`;\n\n/**\n * Generate summaries for compaction using prepared data.\n * Returns CompactionResult - SessionManager adds uuid/parentUuid when saving.\n *\n * @param preparation - Pre-calculated preparation from prepareCompaction()\n * @param customInstructions - Optional custom focus for the summary\n */\n/** Runs one summary wire call; hosts decorate each call with its own request identity. */\nexport type SummaryCallRunner = <T>(\n\tcall: (callHeaders: Record<string, string> | undefined) => Promise<T>,\n) => Promise<T>;\n\nexport async function compact(\n\tpreparation: CompactionPreparation,\n\tmodel: Model<any>,\n\tapiKey: string,\n\theaders?: Record<string, string>,\n\tcustomInstructions?: string,\n\tsignal?: AbortSignal,\n\tthinkingLevel?: ThinkingLevel,\n\tsummaryCall: SummaryCallRunner = (call) => call(headers),\n\trequests?: InferenceCoordinator,\n\tsummaryCapacity?: (wrapper: string) => number | undefined,\n): Promise<CompactionResult> {\n\tconst {\n\t\tfirstKeptEntryId,\n\t\tmessagesToSummarize,\n\t\tturnPrefixMessages,\n\t\tisSplitTurn,\n\t\ttokensBefore,\n\t\tpreviousSummary,\n\t\tfileOps,\n\t\tsettings,\n\t} = preparation;\n\tlet summary: string;\n\tconst slices: SummarySlice[] = [];\n\tconst { readFiles, modifiedFiles } = computeFileLists(fileOps);\n\tconst fileSummary = formatFileOperations(readFiles, modifiedFiles);\n\tconst split = isSplitTurn && turnPrefixMessages.length > 0;\n\tconst splitSeparator = \"\\n\\n---\\n\\n**Turn Context (split turn):**\\n\\n\";\n\tconst wrapper =\n\t\tCOMPACTION_SUMMARY_PREFIX +\n\t\t(split ? (messagesToSummarize.length ? \"\" : \"No prior history.\") + splitSeparator : \"\") +\n\t\tfileSummary +\n\t\tCOMPACTION_SUMMARY_SUFFIX;\n\tconst capacity = summaryCapacity?.(wrapper);\n\tconst historyNeeded = !split || messagesToSummarize.length > 0;\n\tconst calls = Number(historyNeeded) + Number(split);\n\tif (capacity !== undefined && capacity < calls)\n\t\tthrow new Error(\n\t\t\t\"Context capacity exceeded: required evidence, retained tail and summary wrapper leave no room for a summary.\",\n\t\t);\n\tconst historyLimit =\n\t\tcapacity === undefined\n\t\t\t? undefined\n\t\t\t: Math.min(\n\t\t\t\t\tMath.floor(0.8 * settings.reserveTokens),\n\t\t\t\t\tsplit && historyNeeded ? Math.max(1, Math.floor(capacity * 0.6)) : capacity,\n\t\t\t\t);\n\tconst turnLimit =\n\t\tcapacity === undefined\n\t\t\t? undefined\n\t\t\t: Math.min(Math.floor(0.5 * settings.reserveTokens), capacity - (historyNeeded ? historyLimit! : 0));\n\n\tif (split) {\n\t\t// Split turns make two wire calls with different bodies; each needs its own identity.\n\t\tconst [historyResult, turnPrefixResult] = await Promise.all([\n\t\t\tmessagesToSummarize.length > 0\n\t\t\t\t? summaryCall((callHeaders) =>\n\t\t\t\t\t\tgenerateSummary(\n\t\t\t\t\t\t\tmessagesToSummarize,\n\t\t\t\t\t\t\tmodel,\n\t\t\t\t\t\t\tsettings.reserveTokens,\n\t\t\t\t\t\t\tapiKey,\n\t\t\t\t\t\t\tcallHeaders,\n\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t\tcustomInstructions,\n\t\t\t\t\t\t\tpreviousSummary,\n\t\t\t\t\t\t\tthinkingLevel,\n\t\t\t\t\t\t\trequests,\n\t\t\t\t\t\t\thistoryLimit,\n\t\t\t\t\t\t),\n\t\t\t\t\t)\n\t\t\t\t: Promise.resolve<SummarySlice>({ summary: \"No prior history.\" }),\n\t\t\tsummaryCall((callHeaders) =>\n\t\t\t\tgenerateTurnPrefixSummary(\n\t\t\t\t\tturnPrefixMessages,\n\t\t\t\t\tmodel,\n\t\t\t\t\tsettings.reserveTokens,\n\t\t\t\t\tapiKey,\n\t\t\t\t\tcallHeaders,\n\t\t\t\t\tsignal,\n\t\t\t\t\tthinkingLevel,\n\t\t\t\t\trequests,\n\t\t\t\t\tturnLimit,\n\t\t\t\t),\n\t\t\t),\n\t\t]);\n\t\tslices.push(historyResult, turnPrefixResult);\n\t\tsummary = `${historyResult.summary}${splitSeparator}${turnPrefixResult.summary}`;\n\t} else {\n\t\tconst result = await summaryCall((callHeaders) =>\n\t\t\tgenerateSummary(\n\t\t\t\tmessagesToSummarize,\n\t\t\t\tmodel,\n\t\t\t\tsettings.reserveTokens,\n\t\t\t\tapiKey,\n\t\t\t\tcallHeaders,\n\t\t\t\tsignal,\n\t\t\t\tcustomInstructions,\n\t\t\t\tpreviousSummary,\n\t\t\t\tthinkingLevel,\n\t\t\t\trequests,\n\t\t\t\thistoryLimit,\n\t\t\t),\n\t\t);\n\t\tslices.push(result);\n\t\tsummary = result.summary;\n\t}\n\tsummary += fileSummary;\n\n\tif (!firstKeptEntryId) {\n\t\tthrow new Error(\"First kept entry has no UUID - session may need migration\");\n\t}\n\n\tlet usage: Usage | undefined;\n\tfor (const slice of slices) {\n\t\tif (!slice.usage) continue;\n\t\tusage ??= emptyUsage();\n\t\taddAssistantUsage(usage, slice.usage);\n\t}\n\tconst result: CompactionResult = {\n\t\tsummary,\n\t\tfirstKeptEntryId,\n\t\ttokensBefore,\n\t\tdetails: { readFiles, modifiedFiles } as CompactionDetails,\n\t\tusage,\n\t};\n\tconst bindings = slices.flatMap((slice) => {\n\t\tconst captured = nativeSummarySlices.get(slice);\n\t\tnativeSummarySlices.delete(slice);\n\t\treturn captured?.summary === slice.summary ? [captured.binding] : [];\n\t});\n\tif (bindings.length) nativeCompactionResults.set(result, { summary, bindings });\n\treturn result;\n}\n\n/**\n * Generate a summary for a turn prefix (when splitting a turn).\n */\nasync function generateTurnPrefixSummary(\n\tmessages: AgentMessage[],\n\tmodel: Model<any>,\n\treserveTokens: number,\n\tapiKey: string,\n\theaders?: Record<string, string>,\n\tsignal?: AbortSignal,\n\tthinkingLevel?: ThinkingLevel,\n\trequests?: InferenceCoordinator,\n\toutputTokenLimit?: number,\n): Promise<SummarySlice> {\n\tconst maxTokens = outputTokenLimit ?? Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix\n\tconst llmMessages = convertToLlm(messages);\n\tconst conversationText = serializeConversation(llmMessages);\n\tconst promptText = `<conversation>\\n${conversationText}\\n</conversation>\\n\\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;\n\tconst summarizationMessages = [\n\t\t{\n\t\t\trole: \"user\" as const,\n\t\t\tcontent: [{ type: \"text\" as const, text: promptText }],\n\t\t\ttimestamp: Date.now(),\n\t\t},\n\t];\n\n\tconst completion = completeInference(\n\t\trequests,\n\t\tmodel,\n\t\t{ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },\n\t\tmodel.reasoning && thinkingLevel && thinkingLevel !== \"off\"\n\t\t\t? { maxTokens, signal, apiKey, headers, reasoning: thinkingLevel }\n\t\t\t: { maxTokens, signal, apiKey, headers },\n\t\t{\n\t\t\tpurpose: \"summary\",\n\t\t\tpurposeDetail: \"compaction-turn-prefix\",\n\t\t\toperationId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t\tsemanticEdgeId: headers?.[MODEL_REQUEST_ID_HEADER],\n\t\t},\n\t);\n\n\tconst response = await completion;\n\tif (response.stopReason === \"error\") {\n\t\tthrow new Error(`Turn prefix summarization failed: ${response.errorMessage || \"Unknown error\"}`);\n\t}\n\n\tconst slice: SummarySlice = {\n\t\tsummary: response.content\n\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t.map((c) => c.text)\n\t\t\t.join(\"\\n\"),\n\t\tusage: response.usage,\n\t};\n\treturn captureSummarySlice(slice, requests, completion, \"turn-prefix\");\n}\n"]}

package/dist/core/compaction/compaction.js

@@ -5,7 +5,7 @@
  * and after compaction the session is reloaded.
  */
 import { completeInference, InferenceCoordinator, } from "../inference-coordinator.js";
-import { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
+import { COMPACTION_SUMMARY_PREFIX, COMPACTION_SUMMARY_SUFFIX, convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
 import { MODEL_REQUEST_ID_HEADER } from "../semantic-edges.js";
 import { buildSessionContext } from "../session-manager.js";
 import { addAssistantUsage, emptyUsage } from "../usage.js";
@@ -463,8 +463,8 @@ export function buildSummarizationPrompt(customInstructions, previousSummary) {
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
  */
-export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, requests) {
-    const maxTokens = Math.floor(0.8 * reserveTokens);
+export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, requests, outputTokenLimit) {
+    const maxTokens = outputTokenLimit ?? Math.floor(0.8 * reserveTokens);
     const basePrompt = buildSummarizationPrompt(customInstructions, previousSummary);
     // Serialize before the LLM call so it summarizes rather than continues this conversation.
     const llmMessages = convertToLlm(currentMessages);
@@ -711,28 +711,46 @@ Summarize the prefix to provide context for the retained suffix:
 - [Information needed to understand the retained recent work]
 
 Be concise. Focus on what's needed to understand the kept suffix.`;
-export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, summaryCall = (call) => call(headers), requests) {
+export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, summaryCall = (call) => call(headers), requests, summaryCapacity) {
     const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, settings, } = preparation;
     let summary;
     const slices = [];
-    if (isSplitTurn && turnPrefixMessages.length > 0) {
+    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+    const fileSummary = formatFileOperations(readFiles, modifiedFiles);
+    const split = isSplitTurn && turnPrefixMessages.length > 0;
+    const splitSeparator = "\n\n---\n\n**Turn Context (split turn):**\n\n";
+    const wrapper = COMPACTION_SUMMARY_PREFIX +
+        (split ? (messagesToSummarize.length ? "" : "No prior history.") + splitSeparator : "") +
+        fileSummary +
+        COMPACTION_SUMMARY_SUFFIX;
+    const capacity = summaryCapacity?.(wrapper);
+    const historyNeeded = !split || messagesToSummarize.length > 0;
+    const calls = Number(historyNeeded) + Number(split);
+    if (capacity !== undefined && capacity < calls)
+        throw new Error("Context capacity exceeded: required evidence, retained tail and summary wrapper leave no room for a summary.");
+    const historyLimit = capacity === undefined
+        ? undefined
+        : Math.min(Math.floor(0.8 * settings.reserveTokens), split && historyNeeded ? Math.max(1, Math.floor(capacity * 0.6)) : capacity);
+    const turnLimit = capacity === undefined
+        ? undefined
+        : Math.min(Math.floor(0.5 * settings.reserveTokens), capacity - (historyNeeded ? historyLimit : 0));
+    if (split) {
         // Split turns make two wire calls with different bodies; each needs its own identity.
         const [historyResult, turnPrefixResult] = await Promise.all([
             messagesToSummarize.length > 0
-                ? summaryCall((callHeaders) => generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, callHeaders, signal, customInstructions, previousSummary, thinkingLevel, requests))
+                ? summaryCall((callHeaders) => generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, callHeaders, signal, customInstructions, previousSummary, thinkingLevel, requests, historyLimit))
                 : Promise.resolve({ summary: "No prior history." }),
-            summaryCall((callHeaders) => generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, callHeaders, signal, thinkingLevel, requests)),
+            summaryCall((callHeaders) => generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, callHeaders, signal, thinkingLevel, requests, turnLimit)),
         ]);
         slices.push(historyResult, turnPrefixResult);
-        summary = `${historyResult.summary}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult.summary}`;
+        summary = `${historyResult.summary}${splitSeparator}${turnPrefixResult.summary}`;
     }
     else {
-        const result = await summaryCall((callHeaders) => generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, callHeaders, signal, customInstructions, previousSummary, thinkingLevel, requests));
+        const result = await summaryCall((callHeaders) => generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, callHeaders, signal, customInstructions, previousSummary, thinkingLevel, requests, historyLimit));
         slices.push(result);
         summary = result.summary;
     }
-    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
-    summary += formatFileOperations(readFiles, modifiedFiles);
+    summary += fileSummary;
     if (!firstKeptEntryId) {
         throw new Error("First kept entry has no UUID - session may need migration");
     }
@@ -762,8 +780,8 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
 /**
  * Generate a summary for a turn prefix (when splitting a turn).
  */
-async function generateTurnPrefixSummary(messages, model, reserveTokens, apiKey, headers, signal, thinkingLevel, requests) {
-    const maxTokens = Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix
+async function generateTurnPrefixSummary(messages, model, reserveTokens, apiKey, headers, signal, thinkingLevel, requests, outputTokenLimit) {
+    const maxTokens = outputTokenLimit ?? Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix
     const llmMessages = convertToLlm(messages);
     const conversationText = serializeConversation(llmMessages);
     const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;