@iaforged/context-code 1.0.72 → 1.0.73

package/dist/src/services/compact/compact.js

@@ -0,0 +1,1258 @@
+import { feature } from '../../recovery/bunBundleShim.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+import uniqBy from 'lodash-es/uniqBy.js';
+/* eslint-disable @typescript-eslint/no-require-imports */
+const sessionTranscriptModule = feature('KAIROS')
+    ? require('../sessionTranscript/sessionTranscript.js')
+    : null;
+import { APIUserAbortError } from '@anthropic-ai/sdk/index.js';
+import { markPostCompaction } from '../../bootstrap/state.js';
+import { getInvokedSkillsForAgent } from '../../bootstrap/state.js';
+import { FileReadTool } from '../../tools/FileReadTool/FileReadTool.js';
+import { FILE_READ_TOOL_NAME, FILE_UNCHANGED_STUB, } from '../../tools/FileReadTool/prompt.js';
+import { ToolSearchTool } from '../../tools/ToolSearchTool/ToolSearchTool.js';
+import { createAttachmentMessage, generateFileAttachment, getAgentListingDeltaAttachment, getDeferredToolsDeltaAttachment, getMcpInstructionsDeltaAttachment, } from '../../utils/attachments.js';
+import { getMemoryPath } from '../../utils/config.js';
+import { COMPACT_MAX_OUTPUT_TOKENS } from '../../utils/context.js';
+import { analyzeContext, tokenStatsToStatsigMetrics, } from '../../utils/contextAnalysis.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { hasExactErrorMessage } from '../../utils/errors.js';
+import { cacheToObject } from '../../utils/fileStateCache.js';
+import { runForkedAgent, } from '../../utils/forkedAgent.js';
+import { executePostCompactHooks, executePreCompactHooks, } from '../../utils/hooks.js';
+import { logError } from '../../utils/log.js';
+import { MEMORY_TYPE_VALUES } from '../../utils/memory/types.js';
+import { createCompactBoundaryMessage, createUserMessage, getAssistantMessageText, getLastAssistantMessage, getMessagesAfterCompactBoundary, isCompactBoundaryMessage, normalizeMessagesForAPI, } from '../../utils/messages.js';
+import { expandPath } from '../../utils/path.js';
+import { getPlan, getPlanFilePath } from '../../utils/plans.js';
+import { isSessionActivityTrackingActive, sendSessionActivitySignal, } from '../../utils/sessionActivity.js';
+import { processSessionStartHooks } from '../../utils/sessionStart.js';
+import { getTranscriptPath, reAppendSessionMetadata, } from '../../utils/sessionStorage.js';
+import { sleep } from '../../utils/sleep.js';
+import { jsonStringify } from '../../utils/slowOperations.js';
+/* eslint-enable @typescript-eslint/no-require-imports */
+import { asSystemPrompt } from '../../utils/systemPromptType.js';
+import { getTaskOutputPath } from '../../utils/task/diskOutput.js';
+import { getTokenUsage, tokenCountFromLastAPIResponse, tokenCountWithEstimation, } from '../../utils/tokens.js';
+import { extractDiscoveredToolNames, isToolSearchEnabled, } from '../../utils/toolSearch.js';
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../analytics/growthbook.js';
+import { logEvent, } from '../analytics/index.js';
+import { getMaxOutputTokensForModel, queryModelWithStreaming, } from '../api/claude.js';
+import { getPromptTooLongTokenGap, PROMPT_TOO_LONG_ERROR_MESSAGE, startsWithApiErrorPrefix, } from '../api/errors.js';
+import { notifyCompaction } from '../api/promptCacheBreakDetection.js';
+import { getRetryDelay } from '../api/withRetry.js';
+import { logPermissionContextForAnts } from '../internalLogging.js';
+import { roughTokenCountEstimation, roughTokenCountEstimationForMessages, } from '../tokenEstimation.js';
+import { groupMessagesByApiRound } from './grouping.js';
+import { getCompactPrompt, getCompactUserSummaryMessage, getPartialCompactPrompt, } from './prompt.js';
+export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5;
+export const POST_COMPACT_TOKEN_BUDGET = 50_000;
+export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000;
+// Skills can be large (verify=18.7KB, claude-api=20.1KB). Previously re-injected
+// unbounded on every compact → 5-10K tok/compact. Per-skill truncation beats
+// dropping — instructions at the top of a skill file are usually the critical
+// part. Budget sized to hold ~5 skills at the per-skill cap.
+export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000;
+export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000;
+const MAX_COMPACT_STREAMING_RETRIES = 2;
+/**
+ * Strip image blocks from user messages before sending for compaction.
+ * Images are not needed for generating a conversation summary and can
+ * cause the compaction API call itself to hit the prompt-too-long limit,
+ * especially in CCD sessions where users frequently attach images.
+ * Replaces image blocks with a text marker so the summary still notes
+ * that an image was shared.
+ *
+ * Note: Only user messages contain images (either directly attached or within
+ * tool_result content from tools). Assistant messages contain text, tool_use,
+ * and thinking blocks but not images.
+ */
+export function stripImagesFromMessages(messages) {
+    return messages.map(message => {
+        if (message.type !== 'user') {
+            return message;
+        }
+        const content = message.message.content;
+        if (!Array.isArray(content)) {
+            return message;
+        }
+        let hasMediaBlock = false;
+        const newContent = content.flatMap(block => {
+            if (block.type === 'image') {
+                hasMediaBlock = true;
+                return [{ type: 'text', text: '[image]' }];
+            }
+            if (block.type === 'document') {
+                hasMediaBlock = true;
+                return [{ type: 'text', text: '[document]' }];
+            }
+            // Also strip images/documents nested inside tool_result content arrays
+            if (block.type === 'tool_result' && Array.isArray(block.content)) {
+                let toolHasMedia = false;
+                const newToolContent = block.content.map(item => {
+                    if (item.type === 'image') {
+                        toolHasMedia = true;
+                        return { type: 'text', text: '[image]' };
+                    }
+                    if (item.type === 'document') {
+                        toolHasMedia = true;
+                        return { type: 'text', text: '[document]' };
+                    }
+                    return item;
+                });
+                if (toolHasMedia) {
+                    hasMediaBlock = true;
+                    return [{ ...block, content: newToolContent }];
+                }
+            }
+            return [block];
+        });
+        if (!hasMediaBlock) {
+            return message;
+        }
+        return {
+            ...message,
+            message: {
+                ...message.message,
+                content: newContent,
+            },
+        };
+    });
+}
+/**
+ * Strip attachment types that are re-injected post-compaction anyway.
+ * skill_discovery/skill_listing are re-surfaced by resetSentSkillNames()
+ * + the next turn's discovery signal, so feeding them to the summarizer
+ * wastes tokens and pollutes the summary with stale skill suggestions.
+ *
+ * No-op when EXPERIMENTAL_SKILL_SEARCH is off (the attachment types
+ * don't exist on external builds).
+ */
+export function stripReinjectedAttachments(messages) {
+    if (feature('EXPERIMENTAL_SKILL_SEARCH')) {
+        return messages.filter(m => !(m.type === 'attachment' &&
+            (m.attachment.type === 'skill_discovery' ||
+                m.attachment.type === 'skill_listing')));
+    }
+    return messages;
+}
+export const ERROR_MESSAGE_NOT_ENOUGH_MESSAGES = 'Not enough messages to compact.';
+const MAX_PTL_RETRIES = 3;
+const PTL_RETRY_MARKER = '[earlier conversation truncated for compaction retry]';
+/**
+ * Drops the oldest API-round groups from messages until tokenGap is covered.
+ * Falls back to dropping 20% of groups when the gap is unparseable (some
+ * Vertex/Bedrock error formats). Returns null when nothing can be dropped
+ * without leaving an empty summarize set.
+ *
+ * This is the last-resort escape hatch for CC-1180 — when the compact request
+ * itself hits prompt-too-long, the user is otherwise stuck. Dropping the
+ * oldest context is lossy but unblocks them. The reactive-compact path
+ * (compactMessages.ts) has the proper retry loop that peels from the tail;
+ * this helper is the dumb-but-safe fallback for the proactive/manual path
+ * that wasn't migrated in bfdb472f's unification.
+ */
+export function truncateHeadForPTLRetry(messages, ptlResponse) {
+    // Strip our own synthetic marker from a previous retry before grouping.
+    // Otherwise it becomes its own group 0 and the 20% fallback stalls
+    // (drops only the marker, re-adds it, zero progress on retry 2+).
+    const input = messages[0]?.type === 'user' &&
+        messages[0].isMeta &&
+        messages[0].message.content === PTL_RETRY_MARKER
+        ? messages.slice(1)
+        : messages;
+    const groups = groupMessagesByApiRound(input);
+    if (groups.length < 2)
+        return null;
+    const tokenGap = getPromptTooLongTokenGap(ptlResponse);
+    let dropCount;
+    if (tokenGap !== undefined) {
+        let acc = 0;
+        dropCount = 0;
+        for (const g of groups) {
+            acc += roughTokenCountEstimationForMessages(g);
+            dropCount++;
+            if (acc >= tokenGap)
+                break;
+        }
+    }
+    else {
+        dropCount = Math.max(1, Math.floor(groups.length * 0.2));
+    }
+    // Keep at least one group so there's something to summarize.
+    dropCount = Math.min(dropCount, groups.length - 1);
+    if (dropCount < 1)
+        return null;
+    const sliced = groups.slice(dropCount).flat();
+    // groupMessagesByApiRound puts the preamble in group 0 and starts every
+    // subsequent group with an assistant message. Dropping group 0 leaves an
+    // assistant-first sequence which the API rejects (first message must be
+    // role=user). Prepend a synthetic user marker — ensureToolResultPairing
+    // already handles any orphaned tool_results this creates.
+    if (sliced[0]?.type === 'assistant') {
+        return [
+            createUserMessage({ content: PTL_RETRY_MARKER, isMeta: true }),
+            ...sliced,
+        ];
+    }
+    return sliced;
+}
+export const ERROR_MESSAGE_PROMPT_TOO_LONG = 'Conversation too long. Press esc twice to go up a few messages and try again.';
+export const ERROR_MESSAGE_USER_ABORT = 'API Error: Request was aborted.';
+export const ERROR_MESSAGE_INCOMPLETE_RESPONSE = 'Compaction interrupted · This may be due to network issues — please try again.';
+/**
+ * Build the base post-compact messages array from a CompactionResult.
+ * This ensures consistent ordering across all compaction paths.
+ * Order: boundaryMarker, summaryMessages, messagesToKeep, attachments, hookResults
+ */
+export function buildPostCompactMessages(result) {
+    return [
+        result.boundaryMarker,
+        ...result.summaryMessages,
+        ...(result.messagesToKeep ?? []),
+        ...result.attachments,
+        ...result.hookResults,
+    ];
+}
+/**
+ * Annotate a compact boundary with relink metadata for messagesToKeep.
+ * Preserved messages keep their original parentUuids on disk (dedup-skipped);
+ * the loader uses this to patch head→anchor and anchor's-other-children→tail.
+ *
+ * `anchorUuid` = what sits immediately before keep[0] in the desired chain:
+ *   - suffix-preserving (reactive/session-memory): last summary message
+ *   - prefix-preserving (partial compact): the boundary itself
+ */
+export function annotateBoundaryWithPreservedSegment(boundary, anchorUuid, messagesToKeep) {
+    const keep = messagesToKeep ?? [];
+    if (keep.length === 0)
+        return boundary;
+    return {
+        ...boundary,
+        compactMetadata: {
+            ...boundary.compactMetadata,
+            preservedSegment: {
+                headUuid: keep[0].uuid,
+                anchorUuid,
+                tailUuid: keep.at(-1).uuid,
+            },
+        },
+    };
+}
+/**
+ * Merges user-supplied custom instructions with hook-provided instructions.
+ * User instructions come first; hook instructions are appended.
+ * Empty strings normalize to undefined.
+ */
+export function mergeHookInstructions(userInstructions, hookInstructions) {
+    if (!hookInstructions)
+        return userInstructions || undefined;
+    if (!userInstructions)
+        return hookInstructions;
+    return `${userInstructions}\n\n${hookInstructions}`;
+}
+/**
+ * Creates a compact version of a conversation by summarizing older messages
+ * and preserving recent conversation history.
+ */
+export async function compactConversation(messages, context, cacheSafeParams, suppressFollowUpQuestions, customInstructions, isAutoCompact = false, recompactionInfo) {
+    try {
+        if (messages.length === 0) {
+            throw new Error(ERROR_MESSAGE_NOT_ENOUGH_MESSAGES);
+        }
+        const preCompactTokenCount = tokenCountWithEstimation(messages);
+        const appState = context.getAppState();
+        void logPermissionContextForAnts(appState.toolPermissionContext, 'summary');
+        context.onCompactProgress?.({
+            type: 'hooks_start',
+            hookType: 'pre_compact',
+        });
+        // Execute PreCompact hooks
+        context.setSDKStatus?.('compacting');
+        const hookResult = await executePreCompactHooks({
+            trigger: isAutoCompact ? 'auto' : 'manual',
+            customInstructions: customInstructions ?? null,
+        }, context.abortController.signal);
+        customInstructions = mergeHookInstructions(customInstructions, hookResult.newCustomInstructions);
+        const userDisplayMessage = hookResult.userDisplayMessage;
+        // Show requesting mode with up arrow and custom message
+        context.setStreamMode?.('requesting');
+        context.setResponseLength?.(() => 0);
+        context.onCompactProgress?.({ type: 'compact_start' });
+        // 3P default: true — forked-agent path reuses main conversation's prompt cache.
+        // Experiment (Jan 2026) confirmed: false path is 98% cache miss, costs ~0.76% of
+        // fleet cache_creation (~38B tok/day), concentrated in ephemeral envs (CCR/GHA/SDK)
+        // with cold GB cache and 3P providers where GB is disabled. GB gate kept as kill-switch.
+        const promptCacheSharingEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_compact_cache_prefix', true);
+        const compactPrompt = getCompactPrompt(customInstructions);
+        const summaryRequest = createUserMessage({
+            content: compactPrompt,
+        });
+        let messagesToSummarize = messages;
+        let retryCacheSafeParams = cacheSafeParams;
+        let summaryResponse;
+        let summary;
+        let ptlAttempts = 0;
+        for (;;) {
+            summaryResponse = await streamCompactSummary({
+                messages: messagesToSummarize,
+                summaryRequest,
+                appState,
+                context,
+                preCompactTokenCount,
+                cacheSafeParams: retryCacheSafeParams,
+            });
+            summary = getAssistantMessageText(summaryResponse);
+            if (!summary?.startsWith(PROMPT_TOO_LONG_ERROR_MESSAGE))
+                break;
+            // CC-1180: compact request itself hit prompt-too-long. Truncate the
+            // oldest API-round groups and retry rather than leaving the user stuck.
+            ptlAttempts++;
+            const truncated = ptlAttempts <= MAX_PTL_RETRIES
+                ? truncateHeadForPTLRetry(messagesToSummarize, summaryResponse)
+                : null;
+            if (!truncated) {
+                logEvent('tengu_compact_failed', {
+                    reason: 'prompt_too_long',
+                    preCompactTokenCount,
+                    promptCacheSharingEnabled,
+                    ptlAttempts,
+                });
+                throw new Error(ERROR_MESSAGE_PROMPT_TOO_LONG);
+            }
+            logEvent('tengu_compact_ptl_retry', {
+                attempt: ptlAttempts,
+                droppedMessages: messagesToSummarize.length - truncated.length,
+                remainingMessages: truncated.length,
+            });
+            messagesToSummarize = truncated;
+            // The forked-agent path reads from cacheSafeParams.forkContextMessages,
+            // not the messages param — thread the truncated set through both paths.
+            retryCacheSafeParams = {
+                ...retryCacheSafeParams,
+                forkContextMessages: truncated,
+            };
+        }
+        if (!summary) {
+            logForDebugging(`Compact failed: no summary text in response. Response: ${jsonStringify(summaryResponse)}`, { level: 'error' });
+            logEvent('tengu_compact_failed', {
+                reason: 'no_summary',
+                preCompactTokenCount,
+                promptCacheSharingEnabled,
+            });
+            throw new Error(`Failed to generate conversation summary - response did not contain valid text content`);
+        }
+        else if (startsWithApiErrorPrefix(summary)) {
+            logEvent('tengu_compact_failed', {
+                reason: 'api_error',
+                preCompactTokenCount,
+                promptCacheSharingEnabled,
+            });
+            throw new Error(summary);
+        }
+        // Store the current file state before clearing
+        const preCompactReadFileState = cacheToObject(context.readFileState);
+        // Clear the cache
+        context.readFileState.clear();
+        context.loadedNestedMemoryPaths?.clear();
+        // Intentionally NOT resetting sentSkillNames: re-injecting the full
+        // skill_listing (~4K tokens) post-compact is pure cache_creation with
+        // marginal benefit. The model still has SkillTool in its schema and
+        // invoked_skills attachment (below) preserves used-skill content. Ants
+        // with EXPERIMENTAL_SKILL_SEARCH already skip re-injection via the
+        // early-return in getSkillListingAttachments.
+        // Run async attachment generation in parallel
+        const [fileAttachments, asyncAgentAttachments] = await Promise.all([
+            createPostCompactFileAttachments(preCompactReadFileState, context, POST_COMPACT_MAX_FILES_TO_RESTORE),
+            createAsyncAgentAttachmentsIfNeeded(context),
+        ]);
+        const postCompactFileAttachments = [
+            ...fileAttachments,
+            ...asyncAgentAttachments,
+        ];
+        const planAttachment = createPlanAttachmentIfNeeded(context.agentId);
+        if (planAttachment) {
+            postCompactFileAttachments.push(planAttachment);
+        }
+        // Add plan mode instructions if currently in plan mode, so the model
+        // continues operating in plan mode after compaction
+        const planModeAttachment = await createPlanModeAttachmentIfNeeded(context);
+        if (planModeAttachment) {
+            postCompactFileAttachments.push(planModeAttachment);
+        }
+        // Add skill attachment if skills were invoked in this session
+        const skillAttachment = createSkillAttachmentIfNeeded(context.agentId);
+        if (skillAttachment) {
+            postCompactFileAttachments.push(skillAttachment);
+        }
+        // Compaction ate prior delta attachments. Re-announce from the current
+        // state so the model has tool/instruction context on the first
+        // post-compact turn. Empty message history → diff against nothing →
+        // announces the full set.
+        for (const att of getDeferredToolsDeltaAttachment(context.options.tools, context.options.mainLoopModel, [], { callSite: 'compact_full' })) {
+            postCompactFileAttachments.push(createAttachmentMessage(att));
+        }
+        for (const att of getAgentListingDeltaAttachment(context, [])) {
+            postCompactFileAttachments.push(createAttachmentMessage(att));
+        }
+        for (const att of getMcpInstructionsDeltaAttachment(context.options.mcpClients, context.options.tools, context.options.mainLoopModel, [])) {
+            postCompactFileAttachments.push(createAttachmentMessage(att));
+        }
+        context.onCompactProgress?.({
+            type: 'hooks_start',
+            hookType: 'session_start',
+        });
+        // Execute SessionStart hooks after successful compaction
+        const hookMessages = await processSessionStartHooks('compact', {
+            model: context.options.mainLoopModel,
+        });
+        // Create the compact boundary marker and summary messages before the
+        // event so we can compute the true resulting-context size.
+        const boundaryMarker = createCompactBoundaryMessage(isAutoCompact ? 'auto' : 'manual', preCompactTokenCount ?? 0, messages.at(-1)?.uuid);
+        // Carry loaded-tool state — the summary doesn't preserve tool_reference
+        // blocks, so the post-compact schema filter needs this to keep sending
+        // already-loaded deferred tool schemas to the API.
+        const preCompactDiscovered = extractDiscoveredToolNames(messages);
+        if (preCompactDiscovered.size > 0) {
+            boundaryMarker.compactMetadata.preCompactDiscoveredTools = [
+                ...preCompactDiscovered,
+            ].sort();
+        }
+        const transcriptPath = getTranscriptPath();
+        const summaryMessages = [
+            createUserMessage({
+                content: getCompactUserSummaryMessage(summary, suppressFollowUpQuestions, transcriptPath),
+                isCompactSummary: true,
+                isVisibleInTranscriptOnly: true,
+            }),
+        ];
+        // Previously "postCompactTokenCount" — renamed because this is the
+        // compact API call's total usage (input_tokens ≈ preCompactTokenCount),
+        // NOT the size of the resulting context. Kept for event-field continuity.
+        const compactionCallTotalTokens = tokenCountFromLastAPIResponse([
+            summaryResponse,
+        ]);
+        // Message-payload estimate of the resulting context. The next iteration's
+        // shouldAutoCompact will see this PLUS ~20-40K for system prompt + tools +
+        // userContext (via API usage.input_tokens). So `willRetriggerNextTurn: true`
+        // is a strong signal; `false` may still retrigger when this is close to threshold.
+        const truePostCompactTokenCount = roughTokenCountEstimationForMessages([
+            boundaryMarker,
+            ...summaryMessages,
+            ...postCompactFileAttachments,
+            ...hookMessages,
+        ]);
+        // Extract compaction API usage metrics
+        const compactionUsage = getTokenUsage(summaryResponse);
+        const querySourceForEvent = recompactionInfo?.querySource ?? context.options.querySource ?? 'unknown';
+        logEvent('tengu_compact', {
+            preCompactTokenCount,
+            // Kept for continuity — semantically the compact API call's total usage
+            postCompactTokenCount: compactionCallTotalTokens,
+            truePostCompactTokenCount,
+            autoCompactThreshold: recompactionInfo?.autoCompactThreshold ?? -1,
+            willRetriggerNextTurn: recompactionInfo !== undefined &&
+                truePostCompactTokenCount >= recompactionInfo.autoCompactThreshold,
+            isAutoCompact,
+            querySource: querySourceForEvent,
+            queryChainId: (context.queryTracking?.chainId ??
+                ''),
+            queryDepth: context.queryTracking?.depth ?? -1,
+            isRecompactionInChain: recompactionInfo?.isRecompactionInChain ?? false,
+            turnsSincePreviousCompact: recompactionInfo?.turnsSincePreviousCompact ?? -1,
+            previousCompactTurnId: (recompactionInfo?.previousCompactTurnId ??
+                ''),
+            compactionInputTokens: compactionUsage?.input_tokens,
+            compactionOutputTokens: compactionUsage?.output_tokens,
+            compactionCacheReadTokens: compactionUsage?.cache_read_input_tokens ?? 0,
+            compactionCacheCreationTokens: compactionUsage?.cache_creation_input_tokens ?? 0,
+            compactionTotalTokens: compactionUsage
+                ? compactionUsage.input_tokens +
+                    (compactionUsage.cache_creation_input_tokens ?? 0) +
+                    (compactionUsage.cache_read_input_tokens ?? 0) +
+                    compactionUsage.output_tokens
+                : 0,
+            promptCacheSharingEnabled,
+            // analyzeContext walks every content block (~11ms on a 4.5K-message
+            // session) purely for this telemetry breakdown. Computed here, past
+            // the compaction-API await, so the sync walk doesn't starve the
+            // render loop before compaction even starts. Same deferral pattern
+            // as reactiveCompact.ts.
+            ...(() => {
+                try {
+                    return tokenStatsToStatsigMetrics(analyzeContext(messages));
+                }
+                catch (error) {
+                    logError(error);
+                    return {};
+                }
+            })(),
+        });
+        // Reset cache read baseline so the post-compact drop isn't flagged as a break
+        if (feature('PROMPT_CACHE_BREAK_DETECTION')) {
+            notifyCompaction(context.options.querySource ?? 'compact', context.agentId);
+        }
+        markPostCompaction();
+        // Re-append session metadata (custom title, tag) so it stays within
+        // the 16KB tail window that readLiteMetadata reads for --resume display.
+        // Without this, enough post-compaction messages push the metadata entry
+        // out of the window, causing --resume to show the auto-generated title
+        // instead of the user-set session name.
+        reAppendSessionMetadata();
+        // Write a reduced transcript segment for the pre-compaction messages
+        // (assistant mode only). Fire-and-forget — errors are logged internally.
+        if (feature('KAIROS')) {
+            void sessionTranscriptModule?.writeSessionTranscriptSegment(messages);
+        }
+        context.onCompactProgress?.({
+            type: 'hooks_start',
+            hookType: 'post_compact',
+        });
+        const postCompactHookResult = await executePostCompactHooks({
+            trigger: isAutoCompact ? 'auto' : 'manual',
+            compactSummary: summary,
+        }, context.abortController.signal);
+        const combinedUserDisplayMessage = [
+            userDisplayMessage,
+            postCompactHookResult.userDisplayMessage,
+        ]
+            .filter(Boolean)
+            .join('\n');
+        return {
+            boundaryMarker,
+            summaryMessages,
+            attachments: postCompactFileAttachments,
+            hookResults: hookMessages,
+            userDisplayMessage: combinedUserDisplayMessage || undefined,
+            preCompactTokenCount,
+            postCompactTokenCount: compactionCallTotalTokens,
+            truePostCompactTokenCount,
+            compactionUsage,
+        };
+    }
+    catch (error) {
+        // Only show the error notification for manual /compact.
+        // Auto-compact failures are retried on the next turn and the
+        // notification is confusing when compaction eventually succeeds.
+        if (!isAutoCompact) {
+            addErrorNotificationIfNeeded(error, context);
+        }
+        throw error;
+    }
+    finally {
+        context.setStreamMode?.('requesting');
+        context.setResponseLength?.(() => 0);
+        context.onCompactProgress?.({ type: 'compact_end' });
+        context.setSDKStatus?.(null);
+    }
+}
+/**
+ * Performs a partial compaction around the selected message index.
+ * Direction 'from': summarizes messages after the index, keeps earlier ones.
+ *   Prompt cache for kept (earlier) messages is preserved.
+ * Direction 'up_to': summarizes messages before the index, keeps later ones.
+ *   Prompt cache is invalidated since the summary precedes the kept messages.
+ */
+export async function partialCompactConversation(allMessages, pivotIndex, context, cacheSafeParams, userFeedback, direction = 'from') {
+    try {
+        const messagesToSummarize = direction === 'up_to'
+            ? allMessages.slice(0, pivotIndex)
+            : allMessages.slice(pivotIndex);
+        // 'up_to' must strip old compact boundaries/summaries: for 'up_to',
+        // summary_B sits BEFORE kept, so a stale boundary_A in kept wins
+        // findLastCompactBoundaryIndex's backward scan and drops summary_B.
+        // 'from' keeps them: summary_B sits AFTER kept (backward scan still
+        // works), and removing an old summary would lose its covered history.
+        const messagesToKeep = direction === 'up_to'
+            ? allMessages
+                .slice(pivotIndex)
+                .filter(m => m.type !== 'progress' &&
+                !isCompactBoundaryMessage(m) &&
+                !(m.type === 'user' && m.isCompactSummary))
+            : allMessages.slice(0, pivotIndex).filter(m => m.type !== 'progress');
+        if (messagesToSummarize.length === 0) {
+            throw new Error(direction === 'up_to'
+                ? 'Nothing to summarize before the selected message.'
+                : 'Nothing to summarize after the selected message.');
+        }
+        const preCompactTokenCount = tokenCountWithEstimation(allMessages);
+        context.onCompactProgress?.({
+            type: 'hooks_start',
+            hookType: 'pre_compact',
+        });
+        context.setSDKStatus?.('compacting');
+        const hookResult = await executePreCompactHooks({
+            trigger: 'manual',
+            customInstructions: null,
+        }, context.abortController.signal);
+        // Merge hook instructions with user feedback
+        let customInstructions;
+        if (hookResult.newCustomInstructions && userFeedback) {
+            customInstructions = `${hookResult.newCustomInstructions}\n\nUser context: ${userFeedback}`;
+        }
+        else if (hookResult.newCustomInstructions) {
+            customInstructions = hookResult.newCustomInstructions;
+        }
+        else if (userFeedback) {
+            customInstructions = `User context: ${userFeedback}`;
+        }
+        context.setStreamMode?.('requesting');
+        context.setResponseLength?.(() => 0);
+        context.onCompactProgress?.({ type: 'compact_start' });
+        const compactPrompt = getPartialCompactPrompt(customInstructions, direction);
+        const summaryRequest = createUserMessage({
+            content: compactPrompt,
+        });
+        const failureMetadata = {
+            preCompactTokenCount,
+            direction: direction,
+            messagesSummarized: messagesToSummarize.length,
+        };
+        // 'up_to' prefix hits cache directly; 'from' sends all (tail wouldn't cache).
+        // PTL retry breaks the cache prefix but unblocks the user (CC-1180).
+        let apiMessages = direction === 'up_to' ? messagesToSummarize : allMessages;
+        let retryCacheSafeParams = direction === 'up_to'
+            ? { ...cacheSafeParams, forkContextMessages: messagesToSummarize }
+            : cacheSafeParams;
+        let summaryResponse;
+        let summary;
+        let ptlAttempts = 0;
+        for (;;) {
+            summaryResponse = await streamCompactSummary({
+                messages: apiMessages,
+                summaryRequest,
+                appState: context.getAppState(),
+                context,
+                preCompactTokenCount,
+                cacheSafeParams: retryCacheSafeParams,
+            });
+            summary = getAssistantMessageText(summaryResponse);
+            if (!summary?.startsWith(PROMPT_TOO_LONG_ERROR_MESSAGE))
+                break;
+            ptlAttempts++;
+            const truncated = ptlAttempts <= MAX_PTL_RETRIES
+                ? truncateHeadForPTLRetry(apiMessages, summaryResponse)
+                : null;
+            if (!truncated) {
+                logEvent('tengu_partial_compact_failed', {
+                    reason: 'prompt_too_long',
+                    ...failureMetadata,
+                    ptlAttempts,
+                });
+                throw new Error(ERROR_MESSAGE_PROMPT_TOO_LONG);
+            }
+            logEvent('tengu_compact_ptl_retry', {
+                attempt: ptlAttempts,
+                droppedMessages: apiMessages.length - truncated.length,
+                remainingMessages: truncated.length,
+                path: 'partial',
+            });
+            apiMessages = truncated;
+            retryCacheSafeParams = {
+                ...retryCacheSafeParams,
+                forkContextMessages: truncated,
+            };
+        }
+        if (!summary) {
+            logEvent('tengu_partial_compact_failed', {
+                reason: 'no_summary',
+                ...failureMetadata,
+            });
+            throw new Error('Failed to generate conversation summary - response did not contain valid text content');
+        }
+        else if (startsWithApiErrorPrefix(summary)) {
+            logEvent('tengu_partial_compact_failed', {
+                reason: 'api_error',
+                ...failureMetadata,
+            });
+            throw new Error(summary);
+        }
+        // Store the current file state before clearing
+        const preCompactReadFileState = cacheToObject(context.readFileState);
+        context.readFileState.clear();
+        context.loadedNestedMemoryPaths?.clear();
+        // Intentionally NOT resetting sentSkillNames — see compactConversation()
+        // for rationale (~4K tokens saved per compact event).
+        const [fileAttachments, asyncAgentAttachments] = await Promise.all([
+            createPostCompactFileAttachments(preCompactReadFileState, context, POST_COMPACT_MAX_FILES_TO_RESTORE, messagesToKeep),
+            createAsyncAgentAttachmentsIfNeeded(context),
+        ]);
+        const postCompactFileAttachments = [
+            ...fileAttachments,
+            ...asyncAgentAttachments,
+        ];
+        const planAttachment = createPlanAttachmentIfNeeded(context.agentId);
+        if (planAttachment) {
+            postCompactFileAttachments.push(planAttachment);
+        }
+        // Add plan mode instructions if currently in plan mode
+        const planModeAttachment = await createPlanModeAttachmentIfNeeded(context);
+        if (planModeAttachment) {
+            postCompactFileAttachments.push(planModeAttachment);
+        }
+        const skillAttachment = createSkillAttachmentIfNeeded(context.agentId);
+        if (skillAttachment) {
+            postCompactFileAttachments.push(skillAttachment);
+        }
+        // Re-announce only what was in the summarized portion — messagesToKeep
+        // is scanned, so anything already announced there is skipped.
+        for (const att of getDeferredToolsDeltaAttachment(context.options.tools, context.options.mainLoopModel, messagesToKeep, { callSite: 'compact_partial' })) {
+            postCompactFileAttachments.push(createAttachmentMessage(att));
+        }
+        for (const att of getAgentListingDeltaAttachment(context, messagesToKeep)) {
+            postCompactFileAttachments.push(createAttachmentMessage(att));
+        }
+        for (const att of getMcpInstructionsDeltaAttachment(context.options.mcpClients, context.options.tools, context.options.mainLoopModel, messagesToKeep)) {
+            postCompactFileAttachments.push(createAttachmentMessage(att));
+        }
+        context.onCompactProgress?.({
+            type: 'hooks_start',
+            hookType: 'session_start',
+        });
+        const hookMessages = await processSessionStartHooks('compact', {
+            model: context.options.mainLoopModel,
+        });
+        const postCompactTokenCount = tokenCountFromLastAPIResponse([
+            summaryResponse,
+        ]);
+        const compactionUsage = getTokenUsage(summaryResponse);
+        logEvent('tengu_partial_compact', {
+            preCompactTokenCount,
+            postCompactTokenCount,
+            messagesKept: messagesToKeep.length,
+            messagesSummarized: messagesToSummarize.length,
+            direction: direction,
+            hasUserFeedback: !!userFeedback,
+            trigger: 'message_selector',
+            compactionInputTokens: compactionUsage?.input_tokens,
+            compactionOutputTokens: compactionUsage?.output_tokens,
+            compactionCacheReadTokens: compactionUsage?.cache_read_input_tokens ?? 0,
+            compactionCacheCreationTokens: compactionUsage?.cache_creation_input_tokens ?? 0,
+        });
+        // Progress messages aren't loggable, so forkSessionImpl would null out
+        // a logicalParentUuid pointing at one. Both directions skip them.
+        const lastPreCompactUuid = direction === 'up_to'
+            ? allMessages.slice(0, pivotIndex).findLast(m => m.type !== 'progress')
+                ?.uuid
+            : messagesToKeep.at(-1)?.uuid;
+        const boundaryMarker = createCompactBoundaryMessage('manual', preCompactTokenCount ?? 0, lastPreCompactUuid, userFeedback, messagesToSummarize.length);
+        // allMessages not just messagesToSummarize — set union is idempotent,
+        // simpler than tracking which half each tool lived in.
+        const preCompactDiscovered = extractDiscoveredToolNames(allMessages);
+        if (preCompactDiscovered.size > 0) {
+            boundaryMarker.compactMetadata.preCompactDiscoveredTools = [
+                ...preCompactDiscovered,
+            ].sort();
+        }
+        const transcriptPath = getTranscriptPath();
+        const summaryMessages = [
+            createUserMessage({
+                content: getCompactUserSummaryMessage(summary, false, transcriptPath),
+                isCompactSummary: true,
+                ...(messagesToKeep.length > 0
+                    ? {
+                        summarizeMetadata: {
+                            messagesSummarized: messagesToSummarize.length,
+                            userContext: userFeedback,
+                            direction,
+                        },
+                    }
+                    : { isVisibleInTranscriptOnly: true }),
+            }),
+        ];
+        if (feature('PROMPT_CACHE_BREAK_DETECTION')) {
+            notifyCompaction(context.options.querySource ?? 'compact', context.agentId);
+        }
+        markPostCompaction();
+        // Re-append session metadata (custom title, tag) so it stays within
+        // the 16KB tail window that readLiteMetadata reads for --resume display.
+        reAppendSessionMetadata();
+        if (feature('KAIROS')) {
+            void sessionTranscriptModule?.writeSessionTranscriptSegment(messagesToSummarize);
+        }
+        context.onCompactProgress?.({
+            type: 'hooks_start',
+            hookType: 'post_compact',
+        });
+        const postCompactHookResult = await executePostCompactHooks({
+            trigger: 'manual',
+            compactSummary: summary,
+        }, context.abortController.signal);
+        // 'from': prefix-preserving → boundary; 'up_to': suffix → last summary
+        const anchorUuid = direction === 'up_to'
+            ? (summaryMessages.at(-1)?.uuid ?? boundaryMarker.uuid)
+            : boundaryMarker.uuid;
+        return {
+            boundaryMarker: annotateBoundaryWithPreservedSegment(boundaryMarker, anchorUuid, messagesToKeep),
+            summaryMessages,
+            messagesToKeep,
+            attachments: postCompactFileAttachments,
+            hookResults: hookMessages,
+            userDisplayMessage: postCompactHookResult.userDisplayMessage,
+            preCompactTokenCount,
+            postCompactTokenCount,
+            compactionUsage,
+        };
+    }
+    catch (error) {
+        addErrorNotificationIfNeeded(error, context);
+        throw error;
+    }
+    finally {
+        context.setStreamMode?.('requesting');
+        context.setResponseLength?.(() => 0);
+        context.onCompactProgress?.({ type: 'compact_end' });
+        context.setSDKStatus?.(null);
+    }
+}
+function addErrorNotificationIfNeeded(error, context) {
+    if (!hasExactErrorMessage(error, ERROR_MESSAGE_USER_ABORT) &&
+        !hasExactErrorMessage(error, ERROR_MESSAGE_NOT_ENOUGH_MESSAGES)) {
+        context.addNotification?.({
+            key: 'error-compacting-conversation',
+            text: 'Error compacting conversation',
+            priority: 'immediate',
+            color: 'error',
+        });
+    }
+}
+export function createCompactCanUseTool() {
+    return async () => ({
+        behavior: 'deny',
+        message: 'Tool use is not allowed during compaction',
+        decisionReason: {
+            type: 'other',
+            reason: 'compaction agent should only produce text summary',
+        },
+    });
+}
+async function streamCompactSummary({ messages, summaryRequest, appState, context, preCompactTokenCount, cacheSafeParams, }) {
+    // When prompt cache sharing is enabled, use forked agent to reuse the
+    // main conversation's cached prefix (system prompt, tools, context messages).
+    // Falls back to regular streaming path on failure.
+    // 3P default: true — see comment at the other tengu_compact_cache_prefix read above.
+    const promptCacheSharingEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_compact_cache_prefix', true);
+    // Send keep-alive signals during compaction to prevent remote session
+    // WebSocket idle timeouts from dropping bridge connections. Compaction
+    // API calls can take 5-10+ seconds, during which no other messages
+    // flow through the transport — without keep-alives, the server may
+    // close the WebSocket for inactivity.
+    // Two signals: (1) PUT /worker heartbeat via sessionActivity, and
+    // (2) re-emit 'compacting' status so the SDK event stream stays active
+    // and the server doesn't consider the session stale.
+    const activityInterval = isSessionActivityTrackingActive()
+        ? setInterval((statusSetter) => {
+            sendSessionActivitySignal();
+            statusSetter?.('compacting');
+        }, 30_000, context.setSDKStatus)
+        : undefined;
+    try {
+        if (promptCacheSharingEnabled) {
+            try {
+                // DO NOT set maxOutputTokens here. The fork piggybacks on the main thread's
+                // prompt cache by sending identical cache-key params (system, tools, model,
+                // messages prefix, thinking config). Setting maxOutputTokens would clamp
+                // budget_tokens via Math.min(budget, maxOutputTokens-1) in claude.ts,
+                // creating a thinking config mismatch that invalidates the cache.
+                // The streaming fallback path (below) can safely set maxOutputTokensOverride
+                // since it doesn't share cache with the main thread.
+                const result = await runForkedAgent({
+                    promptMessages: [summaryRequest],
+                    cacheSafeParams,
+                    canUseTool: createCompactCanUseTool(),
+                    querySource: 'compact',
+                    forkLabel: 'compact',
+                    maxTurns: 1,
+                    skipCacheWrite: true,
+                    // Pass the compact context's abortController so user Esc aborts the
+                    // fork — same signal the streaming fallback uses at
+                    // `signal: context.abortController.signal` below.
+                    overrides: { abortController: context.abortController },
+                });
+                const assistantMsg = getLastAssistantMessage(result.messages);
+                const assistantText = assistantMsg
+                    ? getAssistantMessageText(assistantMsg)
+                    : null;
+                // Guard isApiErrorMessage: query() catches API errors (including
+                // APIUserAbortError on ESC) and yields them as synthetic assistant
+                // messages. Without this check, an aborted compact "succeeds" with
+                // "Request was aborted." as the summary — the text doesn't start with
+                // "API Error" so the caller's startsWithApiErrorPrefix guard misses it.
+                if (assistantMsg && assistantText && !assistantMsg.isApiErrorMessage) {
+                    // Skip success logging for PTL error text — it's returned so the
+                    // caller's retry loop catches it, but it's not a successful summary.
+                    if (!assistantText.startsWith(PROMPT_TOO_LONG_ERROR_MESSAGE)) {
+                        logEvent('tengu_compact_cache_sharing_success', {
+                            preCompactTokenCount,
+                            outputTokens: result.totalUsage.output_tokens,
+                            cacheReadInputTokens: result.totalUsage.cache_read_input_tokens,
+                            cacheCreationInputTokens: result.totalUsage.cache_creation_input_tokens,
+                            cacheHitRate: result.totalUsage.cache_read_input_tokens > 0
+                                ? result.totalUsage.cache_read_input_tokens /
+                                    (result.totalUsage.cache_read_input_tokens +
+                                        result.totalUsage.cache_creation_input_tokens +
+                                        result.totalUsage.input_tokens)
+                                : 0,
+                        });
+                    }
+                    return assistantMsg;
+                }
+                logForDebugging(`Compact cache sharing: no text in response, falling back. Response: ${jsonStringify(assistantMsg)}`, { level: 'warn' });
+                logEvent('tengu_compact_cache_sharing_fallback', {
+                    reason: 'no_text_response',
+                    preCompactTokenCount,
+                });
+            }
+            catch (error) {
+                logError(error);
+                logEvent('tengu_compact_cache_sharing_fallback', {
+                    reason: 'error',
+                    preCompactTokenCount,
+                });
+            }
+        }
+        // Regular streaming path (fallback when cache sharing fails or is disabled)
+        const retryEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_compact_streaming_retry', false);
+        const maxAttempts = retryEnabled ? MAX_COMPACT_STREAMING_RETRIES : 1;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            // Reset state for retry
+            let hasStartedStreaming = false;
+            let response;
+            context.setResponseLength?.(() => 0);
+            // Check if tool search is enabled using the main loop's tools list.
+            // context.options.tools includes MCP tools merged via useMergedTools.
+            const useToolSearch = await isToolSearchEnabled(context.options.mainLoopModel, context.options.tools, async () => appState.toolPermissionContext, context.options.agentDefinitions.activeAgents, 'compact');
+            // When tool search is enabled, include ToolSearchTool and MCP tools. They get
+            // defer_loading: true and don't count against context - the API filters them out
+            // of system_prompt_tools before token counting (see api/token_count_api/counting.py:188
+            // and api/public_api/messages/handler.py:324).
+            // Filter MCP tools from context.options.tools (not appState.mcp.tools) so we
+            // get the permission-filtered set from useMergedTools — same source used for
+            // isToolSearchEnabled above and normalizeMessagesForAPI below.
+            // Deduplicate by name to avoid API errors when MCP tools share names with built-in tools.
+            const tools = useToolSearch
+                ? uniqBy([
+                    FileReadTool,
+                    ToolSearchTool,
+                    ...context.options.tools.filter(t => t.isMcp),
+                ], 'name')
+                : [FileReadTool];
+            const streamingGen = queryModelWithStreaming({
+                messages: normalizeMessagesForAPI(stripImagesFromMessages(stripReinjectedAttachments([
+                    ...getMessagesAfterCompactBoundary(messages),
+                    summaryRequest,
+                ])), context.options.tools),
+                systemPrompt: asSystemPrompt([
+                    'You are a helpful AI assistant tasked with summarizing conversations.',
+                ]),
+                thinkingConfig: { type: 'disabled' },
+                tools,
+                signal: context.abortController.signal,
+                options: {
+                    async getToolPermissionContext() {
+                        const appState = context.getAppState();
+                        return appState.toolPermissionContext;
+                    },
+                    model: context.options.mainLoopModel,
+                    toolChoice: undefined,
+                    isNonInteractiveSession: context.options.isNonInteractiveSession,
+                    hasAppendSystemPrompt: !!context.options.appendSystemPrompt,
+                    maxOutputTokensOverride: Math.min(COMPACT_MAX_OUTPUT_TOKENS, getMaxOutputTokensForModel(context.options.mainLoopModel)),
+                    querySource: 'compact',
+                    agents: context.options.agentDefinitions.activeAgents,
+                    mcpTools: [],
+                    effortValue: appState.effortValue,
+                },
+            });
+            const streamIter = streamingGen[Symbol.asyncIterator]();
+            let next = await streamIter.next();
+            while (!next.done) {
+                const event = next.value;
+                if (!hasStartedStreaming &&
+                    event.type === 'stream_event' &&
+                    event.event.type === 'content_block_start' &&
+                    event.event.content_block.type === 'text') {
+                    hasStartedStreaming = true;
+                    context.setStreamMode?.('responding');
+                }
+                if (event.type === 'stream_event' &&
+                    event.event.type === 'content_block_delta' &&
+                    event.event.delta.type === 'text_delta') {
+                    const charactersStreamed = event.event.delta.text.length;
+                    context.setResponseLength?.(length => length + charactersStreamed);
+                }
+                if (event.type === 'assistant') {
+                    response = event;
+                }
+                next = await streamIter.next();
+            }
+            if (response) {
+                return response;
+            }
+            if (attempt < maxAttempts) {
+                logEvent('tengu_compact_streaming_retry', {
+                    attempt,
+                    preCompactTokenCount,
+                    hasStartedStreaming,
+                });
+                await sleep(getRetryDelay(attempt), context.abortController.signal, {
+                    abortError: () => new APIUserAbortError(),
+                });
+                continue;
+            }
+            logForDebugging(`Compact streaming failed after ${attempt} attempts. hasStartedStreaming=${hasStartedStreaming}`, { level: 'error' });
+            logEvent('tengu_compact_failed', {
+                reason: 'no_streaming_response',
+                preCompactTokenCount,
+                hasStartedStreaming,
+                retryEnabled,
+                attempts: attempt,
+                promptCacheSharingEnabled,
+            });
+            throw new Error(ERROR_MESSAGE_INCOMPLETE_RESPONSE);
+        }
+        // This should never be reached due to the throw above, but TypeScript needs it
+        throw new Error(ERROR_MESSAGE_INCOMPLETE_RESPONSE);
+    }
+    finally {
+        clearInterval(activityInterval);
+    }
+}
+/**
+ * Creates attachment messages for recently accessed files to restore them after compaction.
+ * This prevents the model from having to re-read files that were recently accessed.
+ * Re-reads files using FileReadTool to get fresh content with proper validation.
+ * Files are selected based on recency, but constrained by both file count and token budget limits.
+ *
+ * Files already present as Read tool results in preservedMessages are skipped —
+ * re-injecting identical content the model can already see in the preserved tail
+ * is pure waste (up to 25K tok/compact). Mirrors the diff-against-preserved
+ * pattern that getDeferredToolsDeltaAttachment uses at the same call sites.
+ *
+ * @param readFileState The current file state tracking recently read files
+ * @param toolUseContext The tool use context for calling FileReadTool
+ * @param maxFiles Maximum number of files to restore (default: 5)
+ * @param preservedMessages Messages kept post-compact; Read results here are skipped
+ * @returns Array of attachment messages for the most recently accessed files that fit within token budget
+ */
+export async function createPostCompactFileAttachments(readFileState, toolUseContext, maxFiles, preservedMessages = []) {
+    const preservedReadPaths = collectReadToolFilePaths(preservedMessages);
+    const recentFiles = Object.entries(readFileState)
+        .map(([filename, state]) => ({ filename, ...state }))
+        .filter(file => !shouldExcludeFromPostCompactRestore(file.filename, toolUseContext.agentId) && !preservedReadPaths.has(expandPath(file.filename)))
+        .sort((a, b) => b.timestamp - a.timestamp)
+        .slice(0, maxFiles);
+    const results = await Promise.all(recentFiles.map(async (file) => {
+        const attachment = await generateFileAttachment(file.filename, {
+            ...toolUseContext,
+            fileReadingLimits: {
+                maxTokens: POST_COMPACT_MAX_TOKENS_PER_FILE,
+            },
+        }, 'tengu_post_compact_file_restore_success', 'tengu_post_compact_file_restore_error', 'compact');
+        return attachment ? createAttachmentMessage(attachment) : null;
+    }));
+    let usedTokens = 0;
+    return results.filter((result) => {
+        if (result === null) {
+            return false;
+        }
+        const attachmentTokens = roughTokenCountEstimation(jsonStringify(result));
+        if (usedTokens + attachmentTokens <= POST_COMPACT_TOKEN_BUDGET) {
+            usedTokens += attachmentTokens;
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * Creates a plan file attachment if a plan file exists for the current session.
+ * This ensures the plan is preserved after compaction.
+ */
+export function createPlanAttachmentIfNeeded(agentId) {
+    const planContent = getPlan(agentId);
+    if (!planContent) {
+        return null;
+    }
+    const planFilePath = getPlanFilePath(agentId);
+    return createAttachmentMessage({
+        type: 'plan_file_reference',
+        planFilePath,
+        planContent,
+    });
+}
+/**
+ * Creates an attachment for invoked skills to preserve their content across compaction.
+ * Only includes skills scoped to the given agent (or main session when agentId is null/undefined).
+ * This ensures skill guidelines remain available after the conversation is summarized
+ * without leaking skills from other agent contexts.
+ */
+export function createSkillAttachmentIfNeeded(agentId) {
+    const invokedSkills = getInvokedSkillsForAgent(agentId);
+    if (invokedSkills.size === 0) {
+        return null;
+    }
+    // Sorted most-recent-first so budget pressure drops the least-relevant skills.
+    // Per-skill truncation keeps the head of each file (where setup/usage
+    // instructions typically live) rather than dropping whole skills.
+    let usedTokens = 0;
+    const skills = Array.from(invokedSkills.values())
+        .sort((a, b) => b.invokedAt - a.invokedAt)
+        .map(skill => ({
+        name: skill.skillName,
+        path: skill.skillPath,
+        content: truncateToTokens(skill.content, POST_COMPACT_MAX_TOKENS_PER_SKILL),
+    }))
+        .filter(skill => {
+        const tokens = roughTokenCountEstimation(skill.content);
+        if (usedTokens + tokens > POST_COMPACT_SKILLS_TOKEN_BUDGET) {
+            return false;
+        }
+        usedTokens += tokens;
+        return true;
+    });
+    if (skills.length === 0) {
+        return null;
+    }
+    return createAttachmentMessage({
+        type: 'invoked_skills',
+        skills,
+    });
+}
+/**
+ * Creates a plan_mode attachment if the user is currently in plan mode.
+ * This ensures the model continues to operate in plan mode after compaction
+ * (otherwise it would lose the plan mode instructions since those are
+ * normally only injected on tool-use turns via getAttachmentMessages).
+ */
+export async function createPlanModeAttachmentIfNeeded(context) {
+    const appState = context.getAppState();
+    if (appState.toolPermissionContext.mode !== 'plan') {
+        return null;
+    }
+    const planFilePath = getPlanFilePath(context.agentId);
+    const planExists = getPlan(context.agentId) !== null;
+    return createAttachmentMessage({
+        type: 'plan_mode',
+        reminderType: 'full',
+        isSubAgent: !!context.agentId,
+        planFilePath,
+        planExists,
+    });
+}
+/**
+ * Creates attachments for async agents so the model knows about them after
+ * compaction. Covers both agents still running in the background (so the model
+ * doesn't spawn a duplicate) and agents that have finished but whose results
+ * haven't been retrieved yet.
+ */
+export async function createAsyncAgentAttachmentsIfNeeded(context) {
+    const appState = context.getAppState();
+    const asyncAgents = Object.values(appState.tasks).filter((task) => task.type === 'local_agent');
+    return asyncAgents.flatMap(agent => {
+        if (agent.retrieved ||
+            agent.status === 'pending' ||
+            agent.agentId === context.agentId) {
+            return [];
+        }
+        return [
+            createAttachmentMessage({
+                type: 'task_status',
+                taskId: agent.agentId,
+                taskType: 'local_agent',
+                description: agent.description,
+                status: agent.status,
+                deltaSummary: agent.status === 'running'
+                    ? (agent.progress?.summary ?? null)
+                    : (agent.error ?? null),
+                outputFilePath: getTaskOutputPath(agent.agentId),
+            }),
+        ];
+    });
+}
+/**
+ * Scan messages for Read tool_use blocks and collect their file_path inputs
+ * (normalized via expandPath). Used to dedup post-compact file restoration
+ * against what's already visible in the preserved tail.
+ *
+ * Skips Reads whose tool_result is a dedup stub — the stub points at an
+ * earlier full Read that may have been compacted away, so we want
+ * createPostCompactFileAttachments to re-inject the real content.
+ */
+function collectReadToolFilePaths(messages) {
+    const stubIds = new Set();
+    for (const message of messages) {
+        if (message.type !== 'user' || !Array.isArray(message.message.content)) {
+            continue;
+        }
+        for (const block of message.message.content) {
+            if (block.type === 'tool_result' &&
+                typeof block.content === 'string' &&
+                block.content.startsWith(FILE_UNCHANGED_STUB)) {
+                stubIds.add(block.tool_use_id);
+            }
+        }
+    }
+    const paths = new Set();
+    for (const message of messages) {
+        if (message.type !== 'assistant' ||
+            !Array.isArray(message.message.content)) {
+            continue;
+        }
+        for (const block of message.message.content) {
+            if (block.type !== 'tool_use' ||
+                block.name !== FILE_READ_TOOL_NAME ||
+                stubIds.has(block.id)) {
+                continue;
+            }
+            const input = block.input;
+            if (input &&
+                typeof input === 'object' &&
+                'file_path' in input &&
+                typeof input.file_path === 'string') {
+                paths.add(expandPath(input.file_path));
+            }
+        }
+    }
+    return paths;
+}
+const SKILL_TRUNCATION_MARKER = '\n\n[... skill content truncated for compaction; use Read on the skill path if you need the full text]';
+/**
+ * Truncate content to roughly maxTokens, keeping the head. roughTokenCountEstimation
+ * uses ~4 chars/token (its default bytesPerToken), so char budget = maxTokens * 4
+ * minus the marker so the result stays within budget. Marker tells the model it
+ * can Read the full file if needed.
+ */
+function truncateToTokens(content, maxTokens) {
+    if (roughTokenCountEstimation(content) <= maxTokens) {
+        return content;
+    }
+    const charBudget = maxTokens * 4 - SKILL_TRUNCATION_MARKER.length;
+    return content.slice(0, charBudget) + SKILL_TRUNCATION_MARKER;
+}
+function shouldExcludeFromPostCompactRestore(filename, agentId) {
+    const normalizedFilename = expandPath(filename);
+    // Exclude plan files
+    try {
+        const planFilePath = expandPath(getPlanFilePath(agentId));
+        if (normalizedFilename === planFilePath) {
+            return true;
+        }
+    }
+    catch {
+        // If we can't get plan file path, continue with other checks
+    }
+    // Exclude all types of claude.md files
+    // TODO: Refactor to use isMemoryFilePath() from claudemd.ts for consistency
+    // and to also match child directory memory files (.claude/rules/*.md, etc.)
+    try {
+        const normalizedMemoryPaths = new Set(MEMORY_TYPE_VALUES.map(type => expandPath(getMemoryPath(type))));
+        if (normalizedMemoryPaths.has(normalizedFilename)) {
+            return true;
+        }
+    }
+    catch {
+        // If we can't get memory paths, continue
+    }
+    return false;
+}