@myagentroam/agent 0.10.29 → 0.10.31

package/dist/agent-core/sdk/session.js

@@ -2,7 +2,7 @@ import { isProviderContextOverflow, recoverModelStream } from '../model/recovery
 import { estimatedRequestTokens } from '../runtime/context/request-budget.js';
 import { restoreMessages } from '../runtime/context/restore.js';
 import { lastConfigurationEffort, latestModelUsage, reasoningEffortBaseline, shouldUseNativeCompaction } from '../runtime/context/usage.js';
-import { splitContextualPrompt, projectCompactPromptMessages } from '../runtime/context/contextual-blocks.js';
+import { splitContextualPrompt } from '../runtime/context/contextual-blocks.js';
 import { contextualInstructionInsertIndex, insertContextualWorldState, latestContextualWorldStateGeneration, parsePersistedContextualWorldState, persistContextualWorldState, resetContextualWorldState, updateContextualWorldState, updatePromptWorldState } from '../runtime/context/world-state.js';
 import { eventForPersistence, publicModelUsage } from '../runtime/event-projection.js';
 import { ExecutionLoop } from '../runtime/execution.js';
@@ -32,12 +32,16 @@ import { retainedSessionResourcesSnapshot } from '../prompts/resources.js';
 import { childSubagentInstruction } from '../prompts/subagent.js';
 import { AsyncQueue } from '../runtime/async-queue.js';
 import { CompactionOperation } from '../runtime/compaction/operation.js';
+import { CompactCoordinator } from '../runtime/compaction/coordinator.js';
+import { CompactRequests } from '../runtime/compaction/requests.js';
+import { compactSnapshotAnchor } from '../runtime/compaction/retained-context.js';
 import { DEFAULT_COMPACTION_FOCUS, buildCompactedHistory, buildCompactionInput, buildCompactionMessages, buildNativeCompactionMessages, compactedHistoryMessages } from '../runtime/compaction/history.js';
 import { currentLocalTimeContext, environmentContextUpdate, restoreEnvironmentState } from '../runtime/context/environment.js';
 import { ContextGcRuntime } from '../runtime/context/gc-runtime.js';
 import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
 import { loadAgentInstructions, renderAgentInstructions } from '../runtime/context/instructions.js';
 import { normalizeMessagesForModel } from '../runtime/context/normalize.js';
+import { latestSmartContextTokens, projectSmartCompactionMessage, requestSmartCompaction } from '../runtime/compaction/smart.js';
 import { compactSummaryFromCheckpoint, inputMetadataFromRecord } from '../session/jsonl-store.js';
 import { SubagentSessionController } from '../subagent/session-controller.js';
 import { agentStartToolDefinitionWithModels } from '../tools/agent/agent-start.js';
@@ -197,6 +201,11 @@ export function createSessionOpener(services) {
                 executionModels.get(input.modelId ?? executionDefaultModelId)?.conversationModel === false)
                 throw new MarAgentError('MAR_AGENT_MODEL_DISABLED', 'The selected model is not a conversation model.');
             const executionId = randomUUID(), turnId = internal.turnId ?? randomUUID(), queue = new AsyncQueue(), controller = new AbortController();
+            const compactCoordinator = new CompactCoordinator();
+            const messageSources = new WeakMap();
+            let liveModelMessages = [];
+            const compactRequests = new CompactRequests(executionId, () => compactCoordinator.assertNotReentrant());
+            sessionRuntime.compactRequests = compactRequests;
             const permissionPolicy = new ExecutionToolPermissions(mode === 'compact' ? 'full-access' : resolvePermissionMode(input.permissionMode), { sessionId, executionId }, host.requestToolApproval
                 ? {
                     request: (request, signal) => host.requestToolApproval(request, signal),
@@ -265,7 +274,6 @@ export function createSessionOpener(services) {
                 acceptParent(message);
             let acceptsMailbox = sessionSource.type === 'subagent' && mode !== 'compact';
             let sequence = 0;
-            let manualCompactionStarted = false;
             let emitTail = Promise.resolve();
             let releaseSession;
             let exhaustedModelAttempt;
@@ -284,14 +292,21 @@ export function createSessionOpener(services) {
                 const operation = emitTail.then(async () => {
                     assertLive?.();
                     const persistent = eventForPersistence(full);
-                    if (persistent !== undefined && releaseSession !== undefined)
-                        await store.append(sessionId, {
+                    if (persistent !== undefined && releaseSession !== undefined) {
+                        const stored = await store.append(sessionId, {
                             type: full.type,
                             payload: persistent,
                             executionId,
                             turnId
                         });
+                        if (full.type === 'message.completed') {
+                            const message = liveModelMessages.findLast((item) => item.role === 'assistant' && item.content === full.text);
+                            if (message)
+                                messageSources.set(message, stored);
+                        }
+                    }
                     queue.push(full);
+                    compactRequests.publish(full);
                     if (internal.publishHostEvents !== false)
                         await host.emit(full);
                 });
@@ -337,7 +352,6 @@ export function createSessionOpener(services) {
             const result = withToolPermissions(permissionPolicy, async () => {
                 let finalAnswer = '';
                 let executionLoop;
-                let manualCompaction;
                 let executionToolSources;
                 let selectedTurn;
                 const contextGc = new ContextGcRuntime();
@@ -392,9 +406,11 @@ export function createSessionOpener(services) {
                     }
                     const compactMayContainAgentInstructions = contextRecords.some((record) => compactSummaryFromCheckpoint(record) !== undefined);
                     const restored = await restoreMessages(store, sessionId, contextRecords, {
+                        messageSources,
                         includeImages: mode !== 'compact'
                     });
                     const messages = restored.messages;
+                    liveModelMessages = messages;
                     const restoredRecordIds = new Set(contextRecords.map((record) => record.recordId));
                     for (const pending of pendingAppends)
                         if (!restoredRecordIds.has(pending.recordId))
@@ -402,13 +418,25 @@ export function createSessionOpener(services) {
                     pendingAppends.length = 0;
                     immediateTarget = messages;
                     let recordedEnvironment = restored.environmentState;
+                    let smartInput;
                     let compactContext;
+                    let startCompact;
                     const writeInputRecord = async (content, type, metadata, call, committed) => {
                         call.signal.throwIfAborted();
                         if (content.images?.length && !selectedModel.inputCapabilities.includes('IMAGE'))
                             throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
                         await withRecordProjection(async () => {
                             call.signal.throwIfAborted();
+                            const smartPercent = smartContextTokens === undefined
+                                ? undefined
+                                : (smartContextTokens * 100) / selectedModel.contextWindowTokens;
+                            const smartCompaction = mode !== 'compact' &&
+                                sessionSource.type === 'user' &&
+                                type === 'turn.user' &&
+                                metadata.inputSource === undefined &&
+                                smartPercent !== undefined &&
+                                smartPercent >= AGENT_EXECUTION_POLICY.smartCompactionPercent &&
+                                smartPercent < AGENT_EXECUTION_POLICY.automaticCompactionPercent;
                             const images = content.images?.length
                                 ? await store.persistInputImages(sessionId, content.images)
                                 : [];
@@ -417,6 +445,7 @@ export function createSessionOpener(services) {
                                 payload: {
                                     ...metadata,
                                     prompt: content.text,
+                                    ...(smartCompaction ? { smartCompaction: true } : {}),
                                     ...(content.modelText === undefined ? {} : { modelText: content.modelText }),
                                     ...(content.context === undefined ? {} : { context: content.context }),
                                     ...(content.modelContext === undefined
@@ -428,6 +457,11 @@ export function createSessionOpener(services) {
                                 turnId
                             }, { signal: call.signal });
                             const inputMetadata = inputMetadataFromRecord(record);
+                            smartInput = {
+                                recordId: record.recordId,
+                                eligible: smartCompaction,
+                                requested: false
+                            };
                             compactionUserMessages.push({
                                 content: content.modelText ?? content.text,
                                 metadata: inputMetadata
@@ -439,8 +473,14 @@ export function createSessionOpener(services) {
                     };
                     const appendMailboxMessages = async () => inputs.drain(async (entry, request, call) => {
                         call.signal.throwIfAborted();
-                        if (request.kind === 'compact')
+                        if (request.kind === 'compact') {
+                            if (request.input.async) {
+                                const flight = startCompact(request.input);
+                                entry.start();
+                                return { changed: await flight.result, executionId };
+                            }
                             return { changed: await compactContext(request.input), executionId };
+                        }
                         if (request.kind === 'append') {
                             const result = await appendExtensionMessage(entry, request, call);
                             return { ...result, executionId };
@@ -527,6 +567,7 @@ export function createSessionOpener(services) {
                     const selected = createModelTurnSession(selectedAdapter);
                     selectedTurn = selected;
                     let lastServerUsage = latestModelUsage(contextRecords, selectedModel.id);
+                    let smartContextTokens = latestSmartContextTokens(contextRecords, selectedModel.id, selectedModel.contextWindowTokens);
                     const compactUserTokenLimit = Math.min(20_000, Math.floor(selectedModel.contextWindowTokens / 8));
                     const reasoningEffort = input.reasoningEffort ?? selectedModel.defaultReasoningEffort;
                     const useEffortUpdates = usesResponsesConfigurationUpdates(selectedModel);
@@ -765,14 +806,31 @@ export function createSessionOpener(services) {
                         contextualWorldState = next;
                         sessionRuntime.contextualWorldState = next;
                     };
-                    const resetCompactWorldState = async (generation) => {
+                    const resetCompactWorldState = async (generation, committed) => {
                         agentInstructionInsertIndex = contextualInstructionInsertIndex(messages);
                         const next = resetContextualWorldState(generation, agentInstructionInsertIndex, {
                             instructionSnapshot: currentInstructionSnapshot,
                             instructionContent: renderAgentInstructions(instructionEntries, true),
-                            resourceSnapshot: retainedSessionResourcesSnapshot(await loadRetainedSessionResources())
+                            resourceSnapshot: committed
+                                ? committed.resources
+                                : retainedSessionResourcesSnapshot(await loadRetainedSessionResources())
                         });
-                        await commitWorldState(next);
+                        if (!committed)
+                            await commitWorldState(next);
+                        else {
+                            // The checkpoint is authoritative; its sidecar is recoverable on restart.
+                            contextualWorldState = next;
+                            sessionRuntime.contextualWorldState = next;
+                            try {
+                                await persistContextualWorldState(store, sessionId, next);
+                            }
+                            catch {
+                                coreExtensions.diagnose({
+                                    code: 'MAR_AGENT_COMPACT_SIDECAR_PERSIST_FAILED',
+                                    sessionId
+                                });
+                            }
+                        }
                     };
                     // A missing sidecar is rebuilt only for the latest Compact, never for a GC boundary.
                     if (!contextualWorldState.initialized &&
@@ -848,8 +906,24 @@ export function createSessionOpener(services) {
                         const parentFrame = subagents === undefined || mode === 'compact'
                             ? undefined
                             : subagents.captureParentFrame(executionId);
+                        const roundSmartInput = smartInput;
                         const toolContext = {
                             host: host,
+                            requestSmartCompact: () => {
+                                controller.signal.throwIfAborted();
+                                requestSmartCompaction(roundSmartInput === smartInput ? roundSmartInput : undefined, () => {
+                                    // The Session owns this background operation, not the short-lived tool callback.
+                                    services.extensions.operations.enter({
+                                        sessionId,
+                                        sessionEpoch: coreExtensions.epoch,
+                                        executionId,
+                                        turnId,
+                                        actor: 'sdk',
+                                        entry: 'native-api',
+                                        signal: controller.signal
+                                    }, () => startCompact({ async: true }));
+                                });
+                            },
                             permissionPolicy,
                             writeToolResultResource: (text) => store.writeToolResultResource(sessionId, text),
                             todo,
@@ -1062,8 +1136,6 @@ export function createSessionOpener(services) {
                         const initialSystemPrompt = mode === 'compact'
                             ? buildExecutionSystemPrompt(executionTools, 'run')
                             : buildExecutionSystemPrompt();
-                        let useManualCompactionFallback;
-                        const manualAppendBoundary = pendingAppends.length;
                         const generateCompactExtension = async (history, reason, focus, compaction) => {
                             if (!coreExtensions.hooks.hasInterceptors('compact.generate'))
                                 return undefined;
@@ -1114,50 +1186,6 @@ export function createSessionOpener(services) {
                                 acceptsDiagnostics = false;
                             }
                         };
-                        let manualExtension;
-                        if (mode === 'compact' && coreExtensions.hooks.hasInterceptors('compact.generate')) {
-                            manualCompactionStarted = true;
-                            manualCompaction = createCompactionOperation(manualCompactionId, compactSignal);
-                            await emit({ type: 'context.compacting', compactionId: manualCompactionId });
-                            manualExtension = await generateCompactExtension(messages, 'manual', compactFocus, manualCompaction);
-                        }
-                        if (mode === 'compact' && manualExtension === undefined) {
-                            preparedCompactPrompt = await operation((call) => coreExtensions.composeModelSystem(promptComposition(executionTools, 'run'), call));
-                            const compactComposition = splitContextualPrompt(preparedCompactPrompt);
-                            const compactSystemPrompt = compactComposition.system;
-                            const projectCompact = (input) => projectCompactPromptMessages(input, compactComposition.parts, contextualWorldState.promptSnapshot ?? []);
-                            const compactHistory = [...messages];
-                            const projectedHistory = normalizeMessagesForModel(insertContextualWorldState(compactHistory, contextualWorldState.entries), { supportsImages: false });
-                            const nativeMessages = buildNativeCompactionMessages(projectedHistory, {
-                                focus: compactFocus
-                            });
-                            const compactOverheadTokens = estimatedRequestTokens(compactSystemPrompt, projectCompact(buildCompactionMessages('')), executionTools);
-                            const compactInputTokens = selectedModel.contextWindowTokens - compactOverheadTokens;
-                            if (compactInputTokens <= 0)
-                                throw new MarAgentError('MAR_AGENT_CONTEXT_LIMIT', 'Compaction prompt exceeds the selected model context window.');
-                            const fallbackMessages = () => buildCompactionMessages(buildCompactionInput(compactHistory, {
-                                focus: compactFocus,
-                                maxTokens: compactInputTokens
-                            }));
-                            const useNative = shouldUseNativeCompaction({
-                                estimatedRequestTokens: estimatedRequestTokens(compactSystemPrompt, projectCompact(nativeMessages), executionTools),
-                                contextWindowTokens: selectedModel.contextWindowTokens,
-                                latestUsage: lastServerUsage,
-                                historyMessages: compactHistory,
-                                appendedMessages: projectCompact(nativeMessages).slice(projectedHistory.length)
-                            });
-                            messages.splice(0, messages.length, ...(useNative ? nativeMessages : fallbackMessages()));
-                            if (useNative) {
-                                let available = true;
-                                useManualCompactionFallback = () => {
-                                    if (!available)
-                                        return false;
-                                    available = false;
-                                    messages.splice(0, messages.length, ...fallbackMessages(), ...pendingAppends.slice(manualAppendBoundary).map((entry) => entry.message));
-                                    return true;
-                                };
-                            }
-                        }
                         await store.append(sessionId, {
                             type: 'execution.header',
                             payload: {
@@ -1173,29 +1201,53 @@ export function createSessionOpener(services) {
                             turnId
                         });
                         let lastServerContextTokens = lastServerUsage?.contextInputTokens;
-                        const compactLeaf = async (input = {}, signal = controller.signal) => {
+                        let compactBoundary = messages.length;
+                        const compactLeaf = async (input, signal, prepare, compactionId) => {
                             if (messages.length < 2)
                                 return false;
                             let compactSummary = '';
-                            const current = messages.at(-1);
-                            const retainCurrent = current.role === 'user' && current.contextKind === undefined;
-                            const compactHistory = retainCurrent ? messages.slice(0, -1) : [...messages];
-                            const appendBoundary = pendingAppends.length;
-                            const compactComposition = splitContextualPrompt(await operation((call) => coreExtensions.composeModelSystem(promptComposition(executionTools, 'run'), call)));
+                            const cutoff = Math.min(compactBoundary, messages.length);
+                            const current = messages[cutoff - 1];
+                            const retainCurrent = mode !== 'compact' && current.role === 'user' && current.contextKind === undefined;
+                            const prefix = messages.slice(0, cutoff - (retainCurrent ? 1 : 0));
+                            if (!prefix.some((message) => message.role !== 'user' ||
+                                message.contextKind === undefined ||
+                                message.contextKind === 'summary'))
+                                return false;
+                            const compactHistory = structuredClone(prefix);
+                            const prefixInputs = compactionUserMessages.filter((entry) => prefix.some((message) => message.role === 'user' &&
+                                message.contextKind === undefined &&
+                                (entry.metadata?.recordId
+                                    ? message.metadata?.recordId === entry.metadata.recordId
+                                    : message.content === entry.content)));
+                            const snapshotTools = structuredClone(projectTools(executionTools));
+                            const generation = contextualWorldState.generation;
+                            const snapshotUsage = lastServerUsage;
+                            const snapshotEffort = requestReasoningEffort ?? reasoningEffort;
+                            const anchorRecordId = prefix
+                                .map((message) => messageSources.get(message)?.recordId ?? message.metadata?.recordId)
+                                .findLast((id) => id !== undefined);
+                            const visibleAnchor = compactSnapshotAnchor(prefix, messageSources);
+                            const anchor = {
+                                ...(anchorRecordId ? { anchorRecordId } : {}),
+                                ...(visibleAnchor ? { anchor: visibleAnchor } : {})
+                            };
+                            const compactComposition = splitContextualPrompt(await operation((call) => coreExtensions.composeModelSystem(promptComposition(snapshotTools, 'run'), call)));
                             const compactSystemPrompt = compactComposition.system;
-                            const projectCompact = (input) => projectCompactPromptMessages(input, compactComposition.parts, contextualWorldState.promptSnapshot ?? []);
-                            const projectedHistory = normalizeMessagesForModel(insertContextualWorldState(compactHistory, contextualWorldState.entries), { supportsImages: false });
+                            const projectedHistory = normalizeMessagesForModel(compactHistory, {
+                                supportsImages: false
+                            }).map(projectSmartCompactionMessage);
                             const nativeCompactMessages = buildNativeCompactionMessages(projectedHistory, {
                                 ...(input.focus === undefined ? {} : { focus: input.focus })
                             });
-                            const compactOverheadTokens = estimatedRequestTokens(compactSystemPrompt, projectCompact(buildCompactionMessages('')), executionTools);
+                            const compactOverheadTokens = estimatedRequestTokens(compactSystemPrompt, buildCompactionMessages(''), snapshotTools);
                             const compactInputTokens = Math.max(0, selectedModel.contextWindowTokens - compactOverheadTokens);
                             let usingNativeMessages = shouldUseNativeCompaction({
-                                estimatedRequestTokens: estimatedRequestTokens(compactSystemPrompt, projectCompact(nativeCompactMessages), executionTools),
+                                estimatedRequestTokens: estimatedRequestTokens(compactSystemPrompt, nativeCompactMessages, snapshotTools),
                                 contextWindowTokens: selectedModel.contextWindowTokens,
-                                latestUsage: lastServerUsage,
+                                latestUsage: snapshotUsage,
                                 historyMessages: compactHistory,
-                                appendedMessages: projectCompact(nativeCompactMessages).slice(projectedHistory.length)
+                                appendedMessages: nativeCompactMessages.slice(projectedHistory.length)
                             });
                             const fallbackMessages = () => buildCompactionMessages(buildCompactionInput(compactHistory, {
                                 ...(input.focus === undefined ? {} : { focus: input.focus }),
@@ -1204,18 +1256,28 @@ export function createSessionOpener(services) {
                             let compactMessages = usingNativeMessages
                                 ? nativeCompactMessages
                                 : fallbackMessages();
-                            const compactionId = randomUUID();
-                            await emit({ type: 'context.compacting', compactionId });
+                            await emit({
+                                type: 'context.compacting',
+                                compactionId,
+                                async: input.async === true,
+                                stage: 'GENERATING',
+                                ...anchor
+                            });
                             let latestUsage;
                             const compactionRetryState = { attempts: 0 };
                             const compaction = createCompactionOperation(compactionId, signal);
+                            const compactTurn = createModelTurnSession(selectedAdapter);
                             try {
-                                const extensionResult = await generateCompactExtension(compactHistory, 'automatic', input.focus, compaction);
+                                const extensionResult = await generateCompactExtension(compactHistory, mode === 'compact' ? 'manual' : 'automatic', input.focus, compaction);
                                 if (extensionResult) {
                                     compactSummary = extensionResult.summary;
                                     latestUsage = extensionResult.usage;
                                     if (latestUsage)
-                                        await emit({ type: 'usage.updated', ...publicModelUsage(latestUsage) });
+                                        await emit({
+                                            type: 'usage.updated',
+                                            purpose: 'compact',
+                                            ...publicModelUsage(latestUsage)
+                                        });
                                 }
                                 while (extensionResult === undefined) {
                                     if (compactInputTokens === 0)
@@ -1229,20 +1291,24 @@ export function createSessionOpener(services) {
                                             ...(compactComposition.systemBlocks === undefined
                                                 ? {}
                                                 : { systemBlocks: compactComposition.systemBlocks }),
-                                            messages: projectCompact(compactMessages),
-                                            tools: executionTools,
+                                            messages: compactMessages,
+                                            tools: snapshotTools,
                                             toolChoice: 'none',
                                             promptCacheKey: sessionId,
-                                            reasoningEffort: requestReasoningEffort ?? reasoningEffort,
+                                            reasoningEffort: snapshotEffort,
                                             onAttemptDiagnostic: recordModelAttempt('COMPACTION')
                                         }, undefined, selectedModel.id, 'compact');
-                                        for await (const event of streamModel((signal) => compaction.start({ start: (request) => selected.start(request, signal) }, request), compaction.signal)) {
+                                        for await (const event of streamModel((signal) => compaction.start({ start: (request) => compactTurn.start(request, signal) }, request), compaction.signal)) {
                                             if (event.type === 'text.completed' &&
                                                 (event.phase ?? 'final_answer') === 'final_answer')
                                                 compactSummary = event.text.trim();
                                             else if (event.type === 'usage') {
                                                 latestUsage = event.usage;
-                                                await emit({ type: 'usage.updated', ...publicModelUsage(event.usage) });
+                                                await emit({
+                                                    type: 'usage.updated',
+                                                    purpose: 'compact',
+                                                    ...publicModelUsage(event.usage)
+                                                });
                                             }
                                             else if (event.type === 'client_tool.call')
                                                 throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Compaction returned a tool call while tools were disabled.');
@@ -1267,32 +1333,36 @@ export function createSessionOpener(services) {
                             }
                             finally {
                                 await compaction.dispose();
+                                await compactTurn.close();
                             }
                             if (!compactSummary)
                                 throw new MarAgentError('MAR_AGENT_COMPACT_FAILED', 'Automatic compact failed.');
-                            let replacementHistory = buildCompactedHistory(compactSummary, retainCurrent ? compactionUserMessages.slice(0, -1) : compactionUserMessages, compactUserTokenLimit, retainCurrent
-                                ? {
-                                    content: current.content,
-                                    ...(current.metadata ? { metadata: current.metadata } : {})
-                                }
-                                : undefined);
+                            await emit({
+                                type: 'context.compacting',
+                                compactionId,
+                                async: !compactCoordinator.waiting && input.async === true,
+                                stage: compactCoordinator.waiting ? 'WAITING' : 'READY',
+                                ...anchor
+                            });
+                            await prepare();
                             signal.throwIfAborted();
+                            const compactResources = retainedSessionResourcesSnapshot(await loadRetainedSessionResources());
+                            const replacementHistory = buildCompactedHistory(compactSummary, prefixInputs, compactUserTokenLimit);
+                            let retainedModelContext = [];
                             const compactRecord = await writeCompactionRecord(compactSummary, true, signal, async (actual, options) => {
-                                compactSummary = actual;
-                                replacementHistory = buildCompactedHistory(actual, retainCurrent ? compactionUserMessages.slice(0, -1) : compactionUserMessages, compactUserTokenLimit, retainCurrent
-                                    ? {
-                                        content: current.content,
-                                        ...(current.metadata ? { metadata: current.metadata } : {})
-                                    }
-                                    : undefined);
-                                const retainedModelContext = pendingAppends
-                                    .slice(appendBoundary)
-                                    .map((entry) => entry.message);
+                                if (contextualWorldState.generation !== generation ||
+                                    prefix.some((message, index) => messages[index] !== message))
+                                    throw new MarAgentError('MAR_AGENT_COMPACT_STALE', 'The compaction prefix has changed.');
+                                retainedModelContext = messages
+                                    .slice(prefix.length)
+                                    .filter((message) => message.contextKind !== 'private' || message.role === 'provider');
                                 const record = await store.compact(sessionId, {
-                                    summary: compactSummary,
+                                    summary: actual,
                                     replacementHistory,
                                     retainedModelContext,
-                                    automatic: true,
+                                    snapshotMessageCount: prefix.length,
+                                    ...(anchorRecordId ? { snapshotRecordId: anchorRecordId } : {}),
+                                    automatic: mode !== 'compact',
                                     environment: executionEnvironment,
                                     modelId: selectedModel.id,
                                     contextWindowTokens: selectedModel.contextWindowTokens,
@@ -1314,30 +1384,119 @@ export function createSessionOpener(services) {
                                 content: message.content,
                                 ...(message.metadata ? { metadata: { ...message.metadata } } : {})
                             }));
-                            await resetCompactWorldState(compactRecord.recordId);
+                            compactionUserMessages.push(...retainedModelContext
+                                .filter((message) => message.role === 'user' && message.contextKind === undefined)
+                                .map((message) => ({
+                                content: message.content,
+                                ...(message.metadata ? { metadata: message.metadata } : {})
+                            })));
+                            await resetCompactWorldState(compactRecord.recordId, { resources: compactResources });
                             lastServerContextTokens = undefined;
                             lastServerUsage = undefined;
+                            smartContextTokens = undefined;
                             requestReasoningEffort = reasoningEffort;
                             effectiveReasoningEffort = reasoningEffort;
-                            await emit({ type: 'context.compacted', compactionId });
+                            await emit({
+                                type: 'context.compacted',
+                                compactionId,
+                                async: input.async === true,
+                                retainedContext: retainedModelContext.length > 0,
+                                ...anchor
+                            });
                             return true;
                         };
+                        startCompact = (input = {}) => {
+                            const id = manualCompactionId ?? randomUUID();
+                            const flight = compactCoordinator.start(id, input.focus, async (prepare, signal) => {
+                                const linked = AbortSignal.any([signal, controller.signal, compactSignal]);
+                                try {
+                                    if (mode === 'compact' && inputs.currentCompact())
+                                        return await compactLeaf(input, linked, prepare, id);
+                                    return (await performCompact(input, async (effective, call) => ({
+                                        changed: await compactLeaf({ ...effective, async: input.async === true }, AbortSignal.any([linked, call.signal]), prepare, id),
+                                        executionId
+                                    }))).changed;
+                                }
+                                catch (error) {
+                                    const diagnostic = describeMarAgentError(error, 'MAR_AGENT_COMPACT_FAILED');
+                                    await emit({
+                                        type: 'context.compact_failed',
+                                        compactionId: id,
+                                        code: diagnostic.code,
+                                        async: input.async === true,
+                                        cancelled: linked.aborted
+                                    });
+                                    throw error;
+                                }
+                            });
+                            if (smartInput)
+                                smartInput.requested = true;
+                            return flight;
+                        };
                         compactContext = async (input = {}) => {
-                            sources.bind(captureRoundToolScope().toolScope);
-                            return (await performCompact(input, async (effective, call) => ({
-                                changed: await compactLeaf(effective, call.signal),
-                                executionId
-                            }))).changed;
+                            const flight = startCompact(input);
+                            if (input.async)
+                                return false;
+                            await emit({
+                                type: 'context.compacting',
+                                compactionId: flight.id,
+                                stage: 'WAITING',
+                                async: false
+                            });
+                            return (await compactCoordinator.checkpoint(true)) ?? false;
                         };
+                        compactRequests.bind((input) => compactCoordinator.pending
+                            ? startCompact({
+                                ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                                async: input.async === true
+                            })
+                            : undefined);
+                        if (mode === 'compact') {
+                            startCompact({ focus: compactFocus });
+                            compactRequests.drain((input) => startCompact({
+                                ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                                async: input.async === true
+                            }));
+                            await compactCoordinator.checkpoint(true);
+                            compactRequests.seal();
+                            compactRequests.drain((input) => startCompact({
+                                ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                                async: input.async === true
+                            }));
+                            await compactCoordinator.checkpoint(true);
+                            return;
+                        }
                         const ensureContextBudget = async () => {
-                            if (mode === 'compact' || lastServerContextTokens === undefined)
-                                return;
-                            const hardLimit = selectedModel.contextWindowTokens;
-                            const compactLimit = Math.floor((hardLimit * AGENT_EXECUTION_POLICY.automaticCompactionPercent) / 100);
-                            if (lastServerContextTokens < compactLimit)
-                                return;
-                            if (!(await compactContext()))
-                                throw new MarAgentError('MAR_AGENT_CONTEXT_LIMIT', 'Provider usage reached the compaction threshold but no history can be compacted.');
+                            const percent = lastServerContextTokens === undefined
+                                ? undefined
+                                : (lastServerContextTokens * 100) / selectedModel.contextWindowTokens;
+                            if (percent !== undefined &&
+                                percent >= AGENT_EXECUTION_POLICY.automaticCompactionPercent) {
+                                const hadPending = compactCoordinator.pending;
+                                let compacted;
+                                try {
+                                    compacted = await compactContext();
+                                }
+                                catch (error) {
+                                    controller.signal.throwIfAborted();
+                                    if (!hadPending)
+                                        throw error;
+                                    compactBoundary = messages.length;
+                                    compacted = await compactContext();
+                                }
+                                if (!compacted)
+                                    throw new MarAgentError('MAR_AGENT_CONTEXT_LIMIT', 'Provider usage reached the compaction threshold but no history can be compacted.');
+                            }
+                            else {
+                                const adopted = await compactCoordinator.checkpoint(false).catch(() => {
+                                    controller.signal.throwIfAborted();
+                                });
+                                if (!adopted &&
+                                    percent !== undefined &&
+                                    percent >= AGENT_EXECUTION_POLICY.backgroundCompactionPercent &&
+                                    !compactCoordinator.pending)
+                                    startCompact({ async: true });
+                            }
                         };
                         executionLoop = new ExecutionLoop({
                             mode,
@@ -1349,27 +1508,30 @@ export function createSessionOpener(services) {
                             toolImages: currentExecutionToolImages,
                             publish: emit,
                             appendContext: (message) => withRecordProjection(async () => {
-                                await store.append(sessionId, {
+                                const stored = await store.append(sessionId, {
                                     type: 'model.context',
                                     payload: message,
                                     executionId,
                                     turnId
                                 });
+                                messageSources.set(message, stored);
                             }),
-                            prepareRound: async (pendingOutputContinuation) => {
-                                if (mode !== 'compact')
-                                    await appendMailboxMessages();
+                            prepareRound: async function prepareRound(pendingOutputContinuation) {
+                                await appendMailboxMessages();
                                 updateMcpRegistry();
                                 executionTools = mcpRegistry.project(baseTools());
-                                if (mode !== 'compact')
-                                    await syncMcpWorldState(messages.length);
+                                await syncMcpWorldState(messages.length);
+                                compactBoundary = messages.length;
+                                const blocking = compactRequests.drain((input) => startCompact({
+                                    ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                                    async: input.async === true
+                                }));
+                                if (blocking)
+                                    await compactCoordinator.checkpoint(true);
                                 await ensureContextBudget();
-                                if (mode !== 'compact')
-                                    await syncMcpWorldState(messages.length);
-                                if (mode !== 'compact') {
-                                    executionEnvironment = { ...currentEnvironment, ...currentLocalTimeContext() };
-                                    await recordEnvironment();
-                                }
+                                await syncMcpWorldState(messages.length);
+                                executionEnvironment = { ...currentEnvironment, ...currentLocalTimeContext() };
+                                await recordEnvironment();
                                 const { roundTools, roundBindings, toolScope, composeSystemPrompt } = captureRoundToolScope();
                                 const codeModeEnabled = roundTools.some((tool) => tool.name === 'code_exec');
                                 const residentTools = projectTools(mcpRegistry.projectDirect(baseTools()));
@@ -1385,13 +1547,8 @@ export function createSessionOpener(services) {
                                     : [...messages, pendingOutputContinuation];
                                 sources.bind(toolScope);
                                 const composedSystem = splitContextualPrompt(await composeSystemPrompt());
-                                const candidateWorld = mode === 'compact'
-                                    ? contextualWorldState
-                                    : updatePromptWorldState(contextualWorldState, messages.length, composedSystem.parts);
-                                const projectedMessages = projectSessionRequestMessages(requestContextMessages, mode === 'compact' ? [] : candidateWorld.entries, mode !== 'compact' && selectedModel.inputCapabilities.includes('IMAGE'), codeModeEnabled, permissionPolicy.mode === 'auto');
-                                const modelMessages = mode === 'compact'
-                                    ? projectCompactPromptMessages(projectedMessages, composedSystem.parts, contextualWorldState.promptSnapshot ?? [])
-                                    : projectedMessages;
+                                const candidateWorld = updatePromptWorldState(contextualWorldState, messages.length, composedSystem.parts);
+                                const modelMessages = projectSessionRequestMessages(requestContextMessages, candidateWorld.entries, selectedModel.inputCapabilities.includes('IMAGE'), codeModeEnabled, permissionPolicy.mode === 'auto');
                                 const systemPrompt = composedSystem.system;
                                 const candidateRequest = {
                                     system: systemPrompt,
@@ -1401,12 +1558,11 @@ export function createSessionOpener(services) {
                                     messages: modelMessages,
                                     tools: requestTools,
                                     ...(permissionPolicy.mode === 'auto' ? { allowHostedTools: false } : {}),
-                                    ...(mode === 'compact' ? { toolChoice: 'none' } : {}),
                                     promptCacheKey: sessionId,
                                     reasoningEffort,
                                     ...(requestReasoningEffort === undefined ? {} : { requestReasoningEffort }),
                                     ...(modelInputImages?.length ? { images: modelInputImages } : {}),
-                                    onAttemptDiagnostic: recordModelAttempt(mode === 'compact' ? 'COMPACTION' : 'EXECUTION')
+                                    onAttemptDiagnostic: recordModelAttempt('EXECUTION')
                                 };
                                 preparingRequestMessages = modelMessages;
                                 preparingRequestBaseLength = messages.length;
@@ -1422,44 +1578,65 @@ export function createSessionOpener(services) {
                                     // Commit only after request middleware accepts the entire candidate.
                                     await commitWorldState(candidateWorld);
                                 }
+                                const lateCoreChange = inputs.hasBoundaryCompactPending && (await appendMailboxMessages());
+                                const lateBlocking = compactRequests.drain((input) => startCompact({
+                                    ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                                    async: input.async === true
+                                }));
+                                const lateAdopted = lateBlocking && (await compactCoordinator.checkpoint(true));
+                                if (lateCoreChange || lateAdopted) {
+                                    // Middleware may admit a blocking join after the initial checkpoint.
+                                    // Never sample the candidate assembled against the replaced context.
+                                    return prepareRound(pendingOutputContinuation);
+                                }
                                 return { request, toolScope };
                             },
                             startModel: async function* (request) {
-                                const snapshots = mode === 'compact'
-                                    ? undefined
-                                    : (sessionRuntime.requestSnapshots ??= new ExtensionRequestSnapshots());
-                                const snapshot = snapshots?.record(selectedModel.id, request);
-                                if (manualCompactionId !== undefined && !manualCompactionStarted) {
-                                    manualCompactionStarted = true;
-                                    manualCompaction = createCompactionOperation(manualCompactionId, compactSignal);
-                                    await emit({ type: 'context.compacting', compactionId: manualCompactionId });
-                                }
-                                const compaction = manualCompaction;
+                                const snapshots = (sessionRuntime.requestSnapshots ??=
+                                    new ExtensionRequestSnapshots());
+                                const snapshot = snapshots.record(selectedModel.id, request);
                                 yield* streamModel(async function* (nativeSignal) {
-                                    const events = compaction
-                                        ? compaction.start({ start: (value) => selected.start(value, nativeSignal) }, request)
-                                        : selected.start(request, nativeSignal);
-                                    for await (const event of events) {
+                                    for await (const event of selected.start(request, nativeSignal)) {
                                         if (snapshot && event.type === 'completed' && event.reason !== 'cancelled')
                                             snapshots.complete(snapshot);
                                         yield event;
                                     }
-                                }, compaction?.signal ?? controller.signal);
+                                }, controller.signal);
                             },
-                            recoverySignal: () => manualCompaction?.signal ?? controller.signal,
+                            recoverySignal: () => controller.signal,
                             compactContext,
-                            compactionFallback: useManualCompactionFallback,
+                            afterModel: async (closedPrefixLength) => {
+                                compactBoundary = closedPrefixLength;
+                                if (lastServerContextTokens !== undefined &&
+                                    (lastServerContextTokens * 100) / selectedModel.contextWindowTokens >=
+                                        AGENT_EXECUTION_POLICY.backgroundCompactionPercent &&
+                                    !compactCoordinator.pending)
+                                    startCompact({ async: true });
+                            },
                             observeContextTokens: (tokens) => {
                                 lastServerContextTokens = tokens;
+                                smartContextTokens = tokens;
                             },
                             observeUsage: (usage) => {
                                 if (usage !== undefined) {
                                     lastServerContextTokens = usage.contextInputTokens;
+                                    smartContextTokens = usage.contextInputTokens;
                                     lastServerUsage = { ...usage, historyMessages: [...messages] };
                                 }
                             },
                             checkpoint: async (round, latestUsage) => {
-                                if (mode !== 'compact' &&
+                                compactBoundary = messages.length;
+                                const blocking = compactRequests.drain((input) => startCompact({
+                                    ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                                    async: input.async === true
+                                }));
+                                if (blocking)
+                                    await compactCoordinator.checkpoint(true);
+                                else
+                                    await compactCoordinator.checkpoint(false).catch(() => {
+                                        controller.signal.throwIfAborted();
+                                    });
+                                if (!compactCoordinator.pending &&
                                     sessionSource.type !== 'subagent' &&
                                     latestUsage !== undefined) {
                                     // Only a committed GC checkpoint may replace active context and invalidate continuation.
@@ -1486,6 +1663,7 @@ export function createSessionOpener(services) {
                                         }
                                     });
                                     if (committed) {
+                                        smartContextTokens = undefined;
                                         selected.resetContinuation?.();
                                         const refreshed = await restoreMessages(store, sessionId, committed.records, {
                                             includeImages: true,
@@ -1511,51 +1689,23 @@ export function createSessionOpener(services) {
                                 }
                             },
                             mailbox: {
-                                hasPending: () => inputs.hasBoundaryPending && !inputs.executing && mode !== 'compact',
+                                hasPending: () => inputs.hasBoundaryPending && !inputs.executing,
                                 append: appendMailboxMessages,
                                 close: () => {
                                     acceptsMailbox = false;
                                 }
                             }
                         });
-                        if (manualExtension) {
-                            if (manualExtension.usage)
-                                await emit({ type: 'usage.updated', ...publicModelUsage(manualExtension.usage) });
-                        }
-                        const completed = manualExtension
-                            ? { finalAnswer: manualExtension.summary, usage: manualExtension.usage }
-                            : await executionLoop.run();
+                        const completed = await executionLoop.run();
+                        compactRequests.seal();
+                        compactRequests.drain((input) => startCompact({
+                            ...(input.prompt === undefined ? {} : { focus: input.prompt }),
+                            async: input.async === true
+                        }));
+                        await compactCoordinator.checkpoint(true).catch(() => {
+                            controller.signal.throwIfAborted();
+                        });
                         finalAnswer = completed.finalAnswer;
-                        const compactSummary = mode === 'compact' ? finalAnswer.trim() : '';
-                        if (manualCompaction) {
-                            manualCompaction.signal.throwIfAborted();
-                            await manualCompaction.dispose();
-                        }
-                        if (mode === 'compact') {
-                            const compactRecord = await writeCompactionRecord(compactSummary, false, compactSignal, async (actual, options) => {
-                                const retainedModelContext = pendingAppends
-                                    .slice(manualAppendBoundary)
-                                    .map((entry) => entry.message);
-                                const replacementHistory = buildCompactedHistory(actual, compactionUserMessages, compactUserTokenLimit);
-                                const record = await store.compact(sessionId, {
-                                    summary: actual,
-                                    retainedModelContext,
-                                    replacementHistory,
-                                    modelId: selectedModel.id,
-                                    contextWindowTokens: selectedModel.contextWindowTokens,
-                                    ...(completed.usage === undefined ? {} : { usage: completed.usage }),
-                                    executionId,
-                                    turnId
-                                }, options);
-                                messages.splice(0, messages.length, ...compactedHistoryMessages(replacementHistory), ...retainedModelContext);
-                                pendingAppends.length = 0;
-                                selected.resetContinuation?.();
-                                return record;
-                            });
-                            await resetCompactWorldState(compactRecord.recordId);
-                        }
-                        if (mode === 'compact' && manualCompactionId !== undefined)
-                            await emit({ type: 'context.compacted', compactionId: manualCompactionId });
                     };
                     if (mode === 'compact')
                         await performCompact({ focus: input.prompt }, async (effective, call) => {
@@ -1579,6 +1729,10 @@ export function createSessionOpener(services) {
                 catch (error) {
                     finalAnswer = executionLoop?.finalAnswer ?? finalAnswer;
                     acceptsMailbox = false;
+                    await compactCoordinator.close(error);
+                    compactRequests.close(new MarAgentError('MAR_AGENT_CANCELLED', 'Execution ended.'));
+                    if (sessionRuntime.compactRequests === compactRequests)
+                        delete sessionRuntime.compactRequests;
                     if (controller.signal.aborted) {
                         subagents?.endParentExecution(executionId);
                         await emit({ type: 'execution.cancelled' });
@@ -1602,6 +1756,9 @@ export function createSessionOpener(services) {
                 finally {
                     if (sessionRuntime.requestMessages?.executionId === executionId)
                         delete sessionRuntime.requestMessages;
+                    compactRequests.close(new MarAgentError('MAR_AGENT_CANCELLED', 'Execution ended.'));
+                    if (sessionRuntime.compactRequests === compactRequests)
+                        delete sessionRuntime.compactRequests;
                     if (sessionRuntime.appendedMessages?.executionId === executionId)
                         delete sessionRuntime.appendedMessages;
                     if (promptDefaults?.executionId === executionId)
@@ -1611,7 +1768,7 @@ export function createSessionOpener(services) {
                     if (sessionRuntime.toolSources === executionToolSources)
                         delete sessionRuntime.toolSources;
                     internal.signal?.removeEventListener('abort', abortSource);
-                    await manualCompaction?.dispose();
+                    await compactCoordinator.close(controller.signal.reason ?? new MarAgentError('MAR_AGENT_CANCELLED', 'Execution ended.'));
                     await selectedTurn?.close().catch(() => undefined);
                     try {
                         await closeModelAdapters(executionScopedAdapters);
@@ -1900,10 +2057,11 @@ export function createSessionOpener(services) {
             id: sessionId,
             run: (input) => execution('run', input),
             plan: (input) => execution('plan', input),
-            compact: (input = {}) => execution('compact', {
-                prompt: input.prompt ?? DEFAULT_COMPACTION_FOCUS,
-                ...input
-            }),
+            compact: (input = {}) => sessionRuntime.compactRequests?.request(input) ??
+                execution('compact', {
+                    prompt: input.prompt ?? DEFAULT_COMPACTION_FOCUS,
+                    ...input
+                }),
             cancel: async (executionId) => active.get(`${sessionId}:${executionId}`)?.abort(),
             startSubagentTurn: (turn) => execution(turn.role === 'explore' ? 'plan' : 'run', {
                 prompt: turn.prompt,
@@ -1954,7 +2112,7 @@ function projectSessionRequestMessages(messages, entries, supportsImages, codeMo
         supportsImages
     }).map((message) => projectCodeModeSearchResult(autoPermission && message.toolSearchTools
         ? { ...message, toolSearchTools: message.toolSearchTools.map(projectPermissionTool) }
-        : message, codeMode));
+        : projectSmartCompactionMessage(message), codeMode));
 }
 function projectAppendedModelMessage(input) {
     if (input.visibility === 'transcript')