@myagentroam/agent 0.9.141 → 0.9.143

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

@@ -0,0 +1,1147 @@
+import { isProviderContextOverflow, recoverModelStream } from '../model/recovery.js';
+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 { compactHistoryMayContainRetainedResources, contextualInstructionInsertIndex, insertContextualWorldState, latestContextualWorldStateGeneration, parsePersistedContextualWorldState, persistContextualWorldState, resetContextualWorldState, updateContextualWorldState } from '../runtime/context/world-state.js';
+import { eventForPersistence, publicModelUsage } from '../runtime/event-projection.js';
+import { ExecutionLoop } from '../runtime/execution.js';
+import { closeModelAdapters, createModelTurnSession } from './model-runtime.js';
+import { generateSessionTitle } from './session-title.js';
+import { createSubagentBackend } from './subagent-backend.js';
+import { discoveredMcpToolNames, rebindMcpToolSearchOutputs } from '../tools/mcp/history.js';
+import { currentExecutionImages } from '../tools/output-projection.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { MarAgentError, describeMarAgentError } from '../error.js';
+import { usesResponsesConfigurationUpdates } from '../model/configuration.js';
+import { buildEnvironmentContext } from '../prompts/core.js';
+import { executionBudgetEnvironmentEntry } from '../prompts/execution-budget.js';
+import { MAR_AGENT_PROMPT_VERSION, buildSystemPrompt } from '../prompts/index.js';
+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 { 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 { RolloutBudget } from '../runtime/rollout-budget.js';
+import { compactSummaryFromCheckpoint } from '../session/jsonl-store.js';
+import { SubagentSessionController } from '../subagent/session-controller.js';
+import { agentStartToolDefinitionWithModels } from '../tools/agent/agent-start.js';
+import { allowsDirectTool, allowsToolCaller, toolCallers } from '../tools/callers.js';
+import { projectCodeModeSearchResult, projectCodeModeTools } from '../tools/code-mode/index.js';
+import { assertMcpToolCatalog } from '../tools/mcp/catalog.js';
+import { BUILTIN_TOOL_DEFINITIONS } from '../tools/registry.js';
+import { createSessionToolScheduler } from '../tools/scheduler.js';
+import { TodoStore } from '../tools/agent/todo.js';
+import { DeferredMcpRegistry } from '../tools/mcp/tool-search.js';
+/** SDK Session orchestration owns warm resources; Runtime owns only the model/tool loop. */
+export function createSessionOpener(services) {
+    const { host, description, settings, store, rolloutBudgetOptions, createAdapter, activeAdaptersExcept } = services;
+    const { active, activeExecutionAdapters, executionResults, sessionRuntimes, sessionWriterOwner } = services.registry;
+    const openSession = async (sessionId, workspace) => {
+        const storedSession = await store.getSession(sessionId);
+        const storedWorkspace = storedSession.workspace;
+        const sessionSource = storedSession.source;
+        const logicalWorkspace = settings.workspaceMapping?.logicalPath ?? workspace ?? storedWorkspace ?? '';
+        const instructionWorkspace = settings.workspaceMapping?.physicalPath ?? workspace ?? storedWorkspace ?? '';
+        const currentEnvironment = {
+            platform: description.platform,
+            ...(description.architecture ? { architecture: description.architecture } : {}),
+            ...(description.shell ? { shell: description.shell } : {}),
+            ...(description.guaranteedCommands
+                ? { guaranteedCommands: description.guaranteedCommands }
+                : {}),
+            workspace: logicalWorkspace
+        };
+        if (!restoreEnvironmentState({ version: 1, state: currentEnvironment }))
+            throw new MarAgentError('MAR_AGENT_HOST_INCOMPATIBLE', 'Host environment facts are invalid or exceed the context limit.');
+        const environmentContext = buildEnvironmentContext(currentEnvironment);
+        let sessionRuntime = sessionRuntimes.get(sessionId);
+        if (sessionRuntime === undefined) {
+            sessionRuntime = {
+                sourceType: sessionSource.type,
+                scheduleTool: createSessionToolScheduler(),
+                adapterGeneration: services.modelState().generation,
+                adapters: new Map()
+            };
+            sessionRuntimes.set(sessionId, sessionRuntime);
+        }
+        if (sessionSource.type === 'user' && sessionRuntime.subagents === undefined) {
+            sessionRuntime.subagentsOpening ??= SubagentSessionController.open({
+                parentSessionId: sessionId,
+                rootSessionId: sessionId,
+                backend: createSubagentBackend(store, storedWorkspace)
+            });
+            try {
+                sessionRuntime.subagents = await sessionRuntime.subagentsOpening;
+            }
+            finally {
+                delete sessionRuntime.subagentsOpening;
+            }
+        }
+        const sessionAdapter = (modelId, configuredModels) => {
+            let selected = sessionRuntime.adapters.get(modelId);
+            if (selected === undefined) {
+                selected = createAdapter(modelId, configuredModels);
+                if (!services.hasCustomAdapters || selected.createTurnSession !== undefined)
+                    sessionRuntime.adapters.set(modelId, selected);
+            }
+            return selected;
+        };
+        const refreshSessionAdapters = async (generation) => {
+            if (sessionRuntime.adapterGeneration === generation)
+                return;
+            const retainedByActiveSessions = activeAdaptersExcept(sessionId);
+            await closeModelAdapters([...sessionRuntime.adapters.values()].filter((adapter) => !retainedByActiveSessions.has(adapter)));
+            sessionRuntime.adapters.clear();
+            sessionRuntime.adapterGeneration = generation;
+        };
+        const execution = (mode, input, internal = {}) => {
+            services.assertCanStart();
+            if ([...active.keys()].some((key) => key.startsWith(`${sessionId}:`)))
+                throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Session already has an active execution.');
+            const executionId = randomUUID(), turnId = internal.turnId ?? randomUUID(), queue = new AsyncQueue(), controller = new AbortController();
+            let executionEnvironment = {
+                ...currentEnvironment,
+                ...currentLocalTimeContext()
+            };
+            const { models: executionModels, defaultModelId: executionDefaultModelId, generation: executionModelGeneration } = services.modelState();
+            const manualCompactionId = mode === 'compact' ? randomUUID() : undefined;
+            active.set(`${sessionId}:${executionId}`, controller);
+            const mailbox = [...(internal.initialMailbox ?? [])];
+            let acceptsMailbox = sessionSource.type === 'subagent' && mode !== 'compact';
+            let sequence = 0;
+            let manualCompactionStarted = false;
+            let emitTail = Promise.resolve();
+            let exhaustedModelAttempt;
+            // Serialize durable events before either the local stream or Host observes them.
+            const emit = (event) => {
+                const full = {
+                    ...event,
+                    eventId: randomUUID(),
+                    sequence: ++sequence,
+                    timestamp: new Date().toISOString(),
+                    sessionId,
+                    executionId,
+                    turnId
+                };
+                const operation = emitTail.then(async () => {
+                    // Transport-only progress events never become recoverable history.
+                    const persistent = eventForPersistence(full);
+                    if (persistent !== undefined)
+                        await store.append(sessionId, {
+                            type: full.type,
+                            payload: persistent,
+                            executionId,
+                            turnId
+                        });
+                    queue.push(full);
+                    if (internal.publishHostEvents !== false)
+                        await host.emit(full);
+                });
+                emitTail = operation.catch(() => undefined);
+                return operation;
+            };
+            const recordModelAttempt = (purpose) => (diagnostic) => {
+                if (purpose === 'EXECUTION' || purpose === 'COMPACTION') {
+                    if ((diagnostic.state === 'STARTED' && diagnostic.attempt === 1) ||
+                        diagnostic.state === 'SUCCEEDED')
+                        exhaustedModelAttempt = undefined;
+                    else if (diagnostic.state === 'FAILED' &&
+                        diagnostic.willRetry === false &&
+                        diagnostic.attempt > 1)
+                        exhaustedModelAttempt = {
+                            attempts: diagnostic.attempt,
+                            retries: diagnostic.attempt - 1
+                        };
+                }
+                const operation = emitTail.then(async () => {
+                    await store.append(sessionId, {
+                        type: 'model.attempt',
+                        payload: { purpose, ...diagnostic },
+                        executionId,
+                        turnId
+                    });
+                });
+                emitTail = operation.catch(() => undefined);
+                return operation;
+            };
+            const createCompactionOperation = (compactionId) => new CompactionOperation(controller.signal, (progress) => {
+                const operation = emitTail.then(async () => {
+                    await store.append(sessionId, {
+                        type: 'compact.progress',
+                        payload: { compactionId, ...progress },
+                        executionId,
+                        turnId
+                    });
+                });
+                emitTail = operation.catch(() => undefined);
+                return operation;
+            });
+            const result = (async () => {
+                let finalAnswer = '';
+                let executionLoop;
+                let manualCompaction;
+                const rolloutBudget = internal.sharedRolloutBudget ??
+                    (rolloutBudgetOptions ? new RolloutBudget(rolloutBudgetOptions) : undefined);
+                const ownsRolloutBudget = rolloutBudget !== undefined && internal.sharedRolloutBudget === undefined;
+                let releaseSession;
+                let selectedTurn;
+                const contextGc = new ContextGcRuntime();
+                let selectedAdapter;
+                let titleAdapter;
+                const executionScopedAdapters = new Set();
+                let titleTask;
+                let titleSettled = false;
+                const settleTitle = async () => {
+                    if (titleSettled)
+                        return;
+                    titleSettled = true;
+                    const generatedTitle = await titleTask;
+                    if (generatedTitle)
+                        await store
+                            .updateTitle(sessionId, generatedTitle, { executionId, turnId })
+                            .catch(() => undefined);
+                };
+                const subagents = sessionSource.type === 'user' ? sessionRuntime.subagents : undefined;
+                try {
+                    releaseSession = await store.acquireSessionLease(sessionId, sessionWriterOwner);
+                    await refreshSessionAdapters(executionModelGeneration);
+                    const sessionState = await store.readExecutionState(sessionId);
+                    if (!store.hasRetainedSessionLease(sessionId, sessionWriterOwner))
+                        sessionRuntime.todo = TodoStore.restore(sessionState.todo);
+                    const todo = (sessionRuntime.todo ??= TodoStore.restore(sessionState.todo));
+                    const contextRecords = sessionState.contextRecords;
+                    const contextualWorldStateGeneration = latestContextualWorldStateGeneration(contextRecords);
+                    const restoredContextualWorldState = sessionRuntime.contextualWorldState;
+                    const persistedContextualWorldState = parsePersistedContextualWorldState(await store.readContextualWorldState(sessionId));
+                    let contextualWorldState;
+                    if (restoredContextualWorldState !== undefined &&
+                        restoredContextualWorldState.generation === contextualWorldStateGeneration)
+                        contextualWorldState = restoredContextualWorldState;
+                    else if (persistedContextualWorldState !== undefined &&
+                        persistedContextualWorldState.generation === contextualWorldStateGeneration) {
+                        contextualWorldState = persistedContextualWorldState;
+                        sessionRuntime.contextualWorldState = contextualWorldState;
+                    }
+                    else {
+                        contextualWorldState = {
+                            generation: contextualWorldStateGeneration,
+                            initialized: false,
+                            instructionSnapshot: undefined,
+                            resourceSnapshot: undefined,
+                            entries: []
+                        };
+                        sessionRuntime.contextualWorldState = contextualWorldState;
+                    }
+                    const compactMayContainAgentInstructions = contextRecords.some((record) => compactSummaryFromCheckpoint(record) !== undefined);
+                    const compactMayContainRetainedResources = compactHistoryMayContainRetainedResources(contextRecords);
+                    const restored = await restoreMessages(store, sessionId, contextRecords, {
+                        includeImages: mode !== 'compact'
+                    });
+                    const messages = restored.messages;
+                    let recordedEnvironment = restored.environmentState;
+                    let projectedExecutionBudgetStage;
+                    const appendExecutionBudgetEnvironment = () => {
+                        const currentStage = rolloutBudget?.active ? rolloutBudget.stage : 'inactive';
+                        if (currentStage === projectedExecutionBudgetStage)
+                            return;
+                        const previousStage = projectedExecutionBudgetStage;
+                        projectedExecutionBudgetStage = currentStage;
+                        if ((previousStage === undefined &&
+                            (currentStage === 'normal' || currentStage === 'inactive')) ||
+                            (currentStage === 'inactive' && previousStage === 'normal'))
+                            return;
+                        const entry = executionBudgetEnvironmentEntry(currentStage === 'normal' ? 'inactive' : currentStage);
+                        messages.push(environmentContextUpdate(executionEnvironment, executionEnvironment, [entry]));
+                    };
+                    const appendMailboxMessages = async () => {
+                        let appended = false;
+                        while (mailbox.length > 0) {
+                            const pending = mailbox.splice(0);
+                            for (const { text: prompt, delivery } of pending) {
+                                await store.append(sessionId, {
+                                    type: 'turn.user',
+                                    payload: {
+                                        prompt,
+                                        inputSource: 'parent_agent',
+                                        ...(delivery ? { messageId: delivery.messageId } : {})
+                                    },
+                                    executionId,
+                                    turnId
+                                });
+                                messages.push({ role: 'user', content: prompt });
+                                delivery?.applied();
+                                appended = true;
+                            }
+                        }
+                        return appended;
+                    };
+                    const recordEnvironment = async () => {
+                        const message = environmentContextUpdate(executionEnvironment, recordedEnvironment);
+                        if (!message)
+                            return;
+                        await store.append(sessionId, {
+                            type: 'context.environment',
+                            payload: { version: 1, state: executionEnvironment },
+                            executionId,
+                            turnId
+                        });
+                        messages.push(message);
+                        recordedEnvironment = executionEnvironment;
+                    };
+                    let compactionUserMessages = [
+                        ...restored.userMessages,
+                        ...(mode === 'compact' ? [] : [input.prompt])
+                    ];
+                    const hasRestoredUserImages = messages.some((message) => message.role === 'user' && Boolean(message.images?.length));
+                    const modelInputImages = mode === 'compact'
+                        ? undefined
+                        : input.images?.map(({ mimeType, dataBase64 }) => ({
+                            mimeType,
+                            dataBase64
+                        }));
+                    const currentExecutionToolImages = [];
+                    let currentExecutionUserIndex;
+                    if (mode !== 'compact') {
+                        await recordEnvironment();
+                        const inputImageMetadata = input.images?.length
+                            ? await store.persistInputImages(sessionId, input.images)
+                            : [];
+                        // A failed sync can still leave a complete record; lease recovery decides image ownership.
+                        await store.append(sessionId, {
+                            type: 'turn.user',
+                            payload: {
+                                prompt: input.prompt,
+                                ...(internal.delivery ? { messageId: internal.delivery.messageId } : {}),
+                                ...(internal.inputSource === undefined
+                                    ? {}
+                                    : { inputSource: internal.inputSource }),
+                                ...(input.clientMessageId ? { clientMessageId: input.clientMessageId } : {}),
+                                ...(inputImageMetadata.length ? { images: inputImageMetadata } : {})
+                            },
+                            executionId,
+                            turnId
+                        });
+                        messages.push({ role: 'user', content: input.prompt });
+                        currentExecutionUserIndex = messages.length - 1;
+                        internal.delivery?.applied();
+                        await appendMailboxMessages();
+                        if (sessionState.automaticTitlePending) {
+                            const titleModel = [...executionModels.values()].find((model) => model.titleGeneration) ??
+                                executionModels.get(input.modelId ?? executionDefaultModelId);
+                            titleAdapter = createAdapter(titleModel.id, executionModels);
+                            activeExecutionAdapters.add(titleAdapter);
+                            titleTask = generateSessionTitle(titleAdapter, input.prompt, titleModel.defaultReasoningEffort, controller.signal, recordModelAttempt('TITLE')).catch(() => undefined);
+                        }
+                    }
+                    await emit({ type: 'execution.started', mode });
+                    if (restored.ignoredImages > 0)
+                        await store.append(sessionId, {
+                            type: 'context.warning',
+                            payload: {
+                                code: 'MAR_AGENT_INPUT_IMAGE_IGNORED',
+                                message: 'One or more corrupt historical input images were ignored.',
+                                ignoredImages: restored.ignoredImages
+                            },
+                            executionId,
+                            turnId
+                        });
+                    selectedAdapter = sessionAdapter(input.modelId ?? executionDefaultModelId, executionModels);
+                    const selectedModel = executionModels.get(input.modelId ?? executionDefaultModelId);
+                    if (services.hasCustomAdapters && selectedAdapter.createTurnSession === undefined) {
+                        executionScopedAdapters.add(selectedAdapter);
+                        activeExecutionAdapters.add(selectedAdapter);
+                    }
+                    const selected = createModelTurnSession(selectedAdapter);
+                    selectedTurn = selected;
+                    let lastServerUsage = latestModelUsage(contextRecords, selectedModel.id);
+                    const compactUserTokenLimit = Math.min(20_000, Math.floor(selectedModel.contextWindowTokens / 8));
+                    const reasoningEffort = input.reasoningEffort ?? selectedModel.defaultReasoningEffort;
+                    const useEffortUpdates = usesResponsesConfigurationUpdates(selectedModel);
+                    const previousReasoningEffort = useEffortUpdates
+                        ? reasoningEffortBaseline(contextRecords, selectedModel.id)
+                        : undefined;
+                    let requestReasoningEffort = useEffortUpdates
+                        ? (previousReasoningEffort ?? reasoningEffort)
+                        : undefined;
+                    let effectiveReasoningEffort = useEffortUpdates
+                        ? previousReasoningEffort === undefined
+                            ? requestReasoningEffort
+                            : (lastConfigurationEffort(messages, selectedModel.id) ?? requestReasoningEffort)
+                        : undefined;
+                    if (mode !== 'compact' &&
+                        useEffortUpdates &&
+                        effectiveReasoningEffort !== reasoningEffort) {
+                        const update = {
+                            role: 'provider',
+                            content: '',
+                            provider: 'OPENAI_RESPONSES',
+                            providerModelId: selectedModel.id,
+                            item: { type: 'configuration_update', reasoning: { effort: reasoningEffort } }
+                        };
+                        messages.push(update);
+                        await store.append(sessionId, {
+                            type: 'model.context',
+                            payload: update,
+                            executionId,
+                            turnId
+                        });
+                        effectiveReasoningEffort = reasoningEffort;
+                    }
+                    if (mode !== 'compact' && subagents)
+                        await subagents.beginParentExecution({
+                            executionId,
+                            modelId: selectedModel.id,
+                            reasoningEffort,
+                            models: executionModels,
+                            emitTerminal: async (task) => emit({
+                                type: 'subagent.completed',
+                                agentId: task.agentId,
+                                description: task.description,
+                                status: task.status,
+                                ...(task.modelId === undefined ? {} : { modelId: task.modelId }),
+                                ...(task.modelName === undefined ? {} : { modelName: task.modelName }),
+                                ...(task.reasoningEffort === undefined
+                                    ? {}
+                                    : { reasoningEffort: task.reasoningEffort }),
+                                ...(task.latestMessage === undefined
+                                    ? {}
+                                    : { latestMessage: task.latestMessage }),
+                                ...(task.latestActivity === undefined
+                                    ? {}
+                                    : { latestActivity: task.latestActivity }),
+                                ...(task.errorCode === undefined ? {} : { errorCode: task.errorCode }),
+                                ...(task.errorMessage === undefined ? {} : { errorMessage: task.errorMessage })
+                            }),
+                            startTurn: async (turn) => {
+                                const child = await openSession(turn.sessionId);
+                                return child.startSubagentTurn({
+                                    prompt: turn.prompt,
+                                    modelId: turn.modelId,
+                                    reasoningEffort: turn.reasoningEffort,
+                                    role: turn.role,
+                                    initialMailbox: turn.initialMailbox,
+                                    turnId: turn.turnId,
+                                    mcpExecutionScopeId: executionId,
+                                    ...(turn.delivery ? { delivery: turn.delivery } : {}),
+                                    ...(rolloutBudget === undefined ? {} : { sharedRolloutBudget: rolloutBudget })
+                                });
+                            }
+                        });
+                    if (mode !== 'compact' &&
+                        (input.images?.length || hasRestoredUserImages) &&
+                        !selectedModel.inputCapabilities.includes('IMAGE'))
+                        throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
+                    const catalogContext = {
+                        sessionId,
+                        executionId,
+                        ...(sessionSource.type === 'subagent'
+                            ? internal.mcpExecutionScopeId === undefined
+                                ? {}
+                                : { executionScopeId: internal.mcpExecutionScopeId }
+                            : { claimExecutionScope: true })
+                    };
+                    const readMcpCatalog = async () => {
+                        if (host.listMcpToolCatalog) {
+                            const catalog = await host.listMcpToolCatalog(catalogContext);
+                            assertMcpToolCatalog(catalog);
+                            return catalog;
+                        }
+                        const definitions = (await host.listMcpTools?.(catalogContext)) ?? [];
+                        return {
+                            revision: createHash('sha256').update(JSON.stringify(definitions)).digest('hex'),
+                            servers: [{ id: 'legacy', name: 'External MCP' }],
+                            tools: definitions.map((definition) => ({
+                                definition,
+                                serverId: 'legacy',
+                                rawName: definition.name,
+                                sourceIdentity: `legacy:${executionId}`,
+                                definitionRevision: createHash('sha256')
+                                    .update(JSON.stringify(definition))
+                                    .digest('hex'),
+                                lifetime: 'execution',
+                                exposure: 'deferred'
+                            }))
+                        };
+                    };
+                    const mcpCatalog = await readMcpCatalog();
+                    const mcpRegistry = new DeferredMcpRegistry(discoveredMcpToolNames(messages));
+                    const mcpTools = mcpCatalog.tools.map((tool) => tool.definition);
+                    const extensions = (await host.listExecutionExtensions?.(catalogContext)) ?? {};
+                    if (extensions.tools?.some((tool) => tool.name.startsWith('mcp__')))
+                        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Host tools cannot use the MCP namespace.');
+                    const selectedModelForTools = executionModels.get(input.modelId ?? executionDefaultModelId);
+                    const builtinTools = BUILTIN_TOOL_DEFINITIONS.map((tool) => tool.name === 'agent_start'
+                        ? agentStartToolDefinitionWithModels([...executionModels.values()].map((configuration) => ({
+                            id: configuration.id,
+                            name: configuration.name,
+                            reasoningEfforts: configuration.reasoningEfforts
+                        })))
+                        : tool);
+                    const combinedTools = [...builtinTools, ...(extensions.tools ?? []), ...mcpTools];
+                    if (new Set(combinedTools.map((tool) => tool.name)).size !== combinedTools.length)
+                        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Tool names conflict.');
+                    const toolEligible = (tool) => {
+                        toolCallers(tool);
+                        if (sessionSource.type === 'subagent' && tool.agentScope === 'ROOT_ONLY')
+                            return false;
+                        if (sessionSource.type === 'subagent' &&
+                            (tool.name.startsWith('agent_') || tool.name === 'question'))
+                            return false;
+                        if (tool.name === 'tool_search')
+                            return mcpRegistry.hasDeferred;
+                        return tool.name === 'code_exec' || tool.name === 'code_exec_wait'
+                            ? selectedModelForTools.codeMode && description.capabilities.includes('code.execute')
+                            : tool.name === 'question'
+                                ? mode === 'plan'
+                                : tool.name === 'web_search'
+                                    ? !selectedModelForTools.hostedWebSearch &&
+                                        description.capabilities.includes('web.search')
+                                    : tool.name === 'view_image'
+                                        ? selectedModelForTools.inputCapabilities.includes('IMAGE')
+                                        : tool.name !== 'web_fetch' || description.capabilities.includes('web.fetch');
+                    };
+                    mcpRegistry.update(mcpCatalog, (tool) => toolEligible(tool.definition));
+                    rebindMcpToolSearchOutputs(messages, mcpRegistry);
+                    const availableTools = combinedTools.filter(toolEligible);
+                    const instructionContext = await loadAgentInstructions({
+                        home: description.homeDirectory,
+                        workspace: instructionWorkspace,
+                        availableTools: new Set(availableTools.map((tool) => tool.name)),
+                        hostSkills: extensions.skills ?? [],
+                        ...(settings.workspaceMapping === undefined
+                            ? {}
+                            : { workspaceDisplayPath: logicalWorkspace })
+                    });
+                    const instructionEntries = instructionContext?.entries ?? [];
+                    const currentInstructionSnapshot = renderAgentInstructions(instructionEntries, false);
+                    let agentInstructionInsertIndex = mode === 'compact'
+                        ? contextualInstructionInsertIndex(messages)
+                        : (currentExecutionUserIndex ?? Math.max(0, messages.length - 1));
+                    if (mode !== 'compact' &&
+                        agentInstructionInsertIndex &&
+                        messages[agentInstructionInsertIndex - 1]?.contextKind === 'environment')
+                        agentInstructionInsertIndex--;
+                    const baseTools = () => [...builtinTools, ...(extensions.tools ?? [])].filter((tool) => toolEligible(tool) &&
+                        (tool.name !== 'skill' || (instructionContext?.skills.size ?? 0) > 0));
+                    let executionTools = mcpRegistry.project(baseTools());
+                    const restoreMcpDiscovery = () => {
+                        mcpRegistry.restore(discoveredMcpToolNames(messages));
+                        rebindMcpToolSearchOutputs(messages, mcpRegistry);
+                        executionTools = mcpRegistry.project(baseTools());
+                    };
+                    const loadRetainedSessionResources = async () => {
+                        const hostResources = (await host.listSessionResources?.(sessionId)) ?? {
+                            processes: []
+                        };
+                        return {
+                            ...(hostResources.idleTtlMs === undefined
+                                ? {}
+                                : { idleTtlMs: hostResources.idleTtlMs }),
+                            processes: hostResources.processes,
+                            ...(hostResources.codeCells ? { codeCells: hostResources.codeCells } : {}),
+                            subagents: subagents?.listSessionResources() ?? []
+                        };
+                    };
+                    let currentResourceSnapshot = retainedSessionResourcesSnapshot(await loadRetainedSessionResources());
+                    const previousContextualWorldState = contextualWorldState;
+                    contextualWorldState = updateContextualWorldState(contextualWorldState, agentInstructionInsertIndex, {
+                        instructionSnapshot: currentInstructionSnapshot,
+                        instructionContent: renderAgentInstructions(instructionEntries, compactMayContainAgentInstructions ||
+                            contextualWorldState.instructionSnapshot !== undefined),
+                        resourceSnapshot: currentResourceSnapshot,
+                        previousMayContainResources: (!contextualWorldState.initialized && compactMayContainRetainedResources) ||
+                            (host.listSessionResources !== undefined &&
+                                currentResourceSnapshot === undefined &&
+                                messages
+                                    .slice(contextualWorldState.entries.findLast((entry) => entry.kind === 'resources')
+                                    ?.index ?? 0)
+                                    .some((message) => message.role === 'tool_call' &&
+                                    ['exec', 'code_exec', 'code_mode', 'agent_start'].includes(message.name ?? '')))
+                    });
+                    sessionRuntime.contextualWorldState = contextualWorldState;
+                    if (!isDeepStrictEqual(previousContextualWorldState, contextualWorldState))
+                        await persistContextualWorldState(store, sessionId, contextualWorldState);
+                    const buildExecutionSystemPrompt = (availableTools = executionTools, promptMode = mode) => buildSystemPrompt({
+                        mode: promptMode,
+                        platform: description.platform,
+                        ...(description.architecture ? { architecture: description.architecture } : {}),
+                        ...(description.shell ? { shell: description.shell } : {}),
+                        ...(description.guaranteedCommands
+                            ? { guaranteedCommands: description.guaranteedCommands }
+                            : {}),
+                        workspace: logicalWorkspace,
+                        tools: availableTools
+                            .filter((tool) => !tool.name.startsWith('mcp__'))
+                            .map((tool) => tool.name),
+                        directTools: availableTools
+                            .filter((tool) => !tool.name.startsWith('mcp__') &&
+                            allowsDirectTool(tool, availableTools.some((candidate) => candidate.name === 'code_exec')))
+                            .map((tool) => tool.name),
+                        highDensityCompaction: selectedModel.highDensityCompaction,
+                        extension: [
+                            settings.systemInstruction,
+                            instructionContext?.skillCatalog,
+                            sessionSource.type === 'subagent' ? childSubagentInstruction : undefined
+                        ]
+                            .filter(Boolean)
+                            .join('\n\n')
+                    });
+                    const syncMcpWorldState = async (index) => {
+                        const snapshot = mcpRegistry.navigation();
+                        if (contextualWorldState.mcpSnapshot === snapshot)
+                            return;
+                        contextualWorldState = {
+                            ...contextualWorldState,
+                            mcpSnapshot: snapshot,
+                            entries: [
+                                ...contextualWorldState.entries,
+                                {
+                                    index,
+                                    kind: 'mcp',
+                                    content: snapshot ?? '<mcp_catalog>No deferred MCP tools remain.</mcp_catalog>'
+                                }
+                            ]
+                        };
+                        sessionRuntime.contextualWorldState = contextualWorldState;
+                        await persistContextualWorldState(store, sessionId, contextualWorldState);
+                    };
+                    if (mode !== 'compact')
+                        await syncMcpWorldState(agentInstructionInsertIndex);
+                    const initialSystemPrompt = mode === 'compact'
+                        ? buildExecutionSystemPrompt(executionTools, 'run')
+                        : buildExecutionSystemPrompt();
+                    let useManualCompactionFallback;
+                    if (mode === 'compact') {
+                        const compactSystemPrompt = initialSystemPrompt;
+                        const compactHistory = [...messages];
+                        const projectedHistory = normalizeMessagesForModel(insertContextualWorldState(compactHistory, contextualWorldState.entries), { supportsImages: false });
+                        const nativeMessages = buildNativeCompactionMessages(projectedHistory, {
+                            focus: input.prompt,
+                            highDensityCompaction: selectedModel.highDensityCompaction
+                        });
+                        const compactOverheadTokens = estimatedRequestTokens(compactSystemPrompt, buildCompactionMessages('', selectedModel.highDensityCompaction), 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: input.prompt,
+                            maxTokens: compactInputTokens
+                        }), selectedModel.highDensityCompaction);
+                        const useNative = shouldUseNativeCompaction({
+                            estimatedRequestTokens: estimatedRequestTokens(compactSystemPrompt, nativeMessages, executionTools),
+                            contextWindowTokens: selectedModel.contextWindowTokens,
+                            latestUsage: lastServerUsage,
+                            historyMessages: compactHistory,
+                            appendedMessages: 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());
+                                return true;
+                            };
+                        }
+                    }
+                    await store.append(sessionId, {
+                        type: 'execution.header',
+                        payload: {
+                            promptVersion: MAR_AGENT_PROMPT_VERSION,
+                            promptHash: createHash('sha256').update(initialSystemPrompt).digest('hex'),
+                            modelId: selectedModel.id,
+                            modelName: selectedModel.name,
+                            reasoningEffort,
+                            contextWindowTokens: selectedModel.contextWindowTokens,
+                            mode
+                        },
+                        executionId,
+                        turnId
+                    });
+                    let lastServerContextTokens = lastServerUsage?.contextInputTokens;
+                    const compactContext = async () => {
+                        const current = messages.at(-1);
+                        if (!current || messages.length < 2)
+                            return false;
+                        const retainCurrent = current.role === 'user' && current.contextKind !== 'environment';
+                        let compactSummary = '';
+                        const compactSystemPrompt = buildExecutionSystemPrompt(executionTools, 'run');
+                        const compactHistory = retainCurrent ? messages.slice(0, -1) : messages;
+                        const projectedHistory = normalizeMessagesForModel(insertContextualWorldState(compactHistory, contextualWorldState.entries), { supportsImages: false });
+                        const nativeCompactMessages = buildNativeCompactionMessages(projectedHistory, {
+                            highDensityCompaction: selectedModel.highDensityCompaction
+                        });
+                        const compactOverheadTokens = estimatedRequestTokens(compactSystemPrompt, buildCompactionMessages('', selectedModel.highDensityCompaction), executionTools);
+                        const compactInputTokens = Math.max(0, selectedModel.contextWindowTokens - compactOverheadTokens);
+                        if (compactInputTokens === 0)
+                            throw new MarAgentError('MAR_AGENT_CONTEXT_LIMIT', 'Compaction prompt exceeds the selected model context window.');
+                        let usingNativeMessages = shouldUseNativeCompaction({
+                            estimatedRequestTokens: estimatedRequestTokens(compactSystemPrompt, nativeCompactMessages, executionTools),
+                            contextWindowTokens: selectedModel.contextWindowTokens,
+                            latestUsage: lastServerUsage,
+                            historyMessages: compactHistory,
+                            appendedMessages: nativeCompactMessages.slice(projectedHistory.length)
+                        });
+                        const fallbackMessages = () => buildCompactionMessages(buildCompactionInput(compactHistory, {
+                            maxTokens: Math.max(1, compactInputTokens)
+                        }), selectedModel.highDensityCompaction);
+                        let compactMessages = usingNativeMessages ? nativeCompactMessages : fallbackMessages();
+                        const compactionId = randomUUID();
+                        await emit({ type: 'context.compacting', compactionId });
+                        let latestUsage;
+                        const compactionRetryState = { attempts: 0 };
+                        const operation = createCompactionOperation(compactionId);
+                        try {
+                            while (true) {
+                                compactSummary = '';
+                                latestUsage = undefined;
+                                try {
+                                    for await (const event of operation.start(selected, {
+                                        retryState: compactionRetryState,
+                                        system: compactSystemPrompt,
+                                        messages: compactMessages,
+                                        tools: executionTools,
+                                        toolChoice: 'none',
+                                        promptCacheKey: sessionId,
+                                        reasoningEffort: requestReasoningEffort ?? reasoningEffort,
+                                        onAttemptDiagnostic: recordModelAttempt('COMPACTION')
+                                    })) {
+                                        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) });
+                                        }
+                                        else if (event.type === 'client_tool.call')
+                                            throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Compaction returned a tool call while tools were disabled.');
+                                    }
+                                    break;
+                                }
+                                catch (error) {
+                                    if (await recoverModelStream(error, compactionRetryState, operation.signal)) {
+                                        continue;
+                                    }
+                                    if (isProviderContextOverflow(error) && usingNativeMessages) {
+                                        usingNativeMessages = false;
+                                        compactMessages = fallbackMessages();
+                                        compactionRetryState.attempts = 0;
+                                        continue;
+                                    }
+                                    if (isProviderContextOverflow(error))
+                                        throw new MarAgentError('MAR_AGENT_CONTEXT_LIMIT', 'The compaction request exceeds the model context window.', { cause: error });
+                                    throw error;
+                                }
+                            }
+                        }
+                        finally {
+                            await operation.dispose();
+                        }
+                        if (!compactSummary)
+                            throw new MarAgentError('MAR_AGENT_COMPACT_FAILED', 'Automatic compact failed.');
+                        rolloutBudget?.recordUsage(latestUsage);
+                        const replacementHistory = buildCompactedHistory(compactSummary, retainCurrent ? compactionUserMessages.slice(0, -1) : compactionUserMessages, compactUserTokenLimit, retainCurrent ? current.content : undefined);
+                        const compactRecord = await store.compact(sessionId, {
+                            summary: compactSummary,
+                            replacementHistory,
+                            automatic: true,
+                            environment: executionEnvironment,
+                            modelId: selectedModel.id,
+                            contextWindowTokens: selectedModel.contextWindowTokens,
+                            ...(latestUsage === undefined ? {} : { usage: latestUsage }),
+                            executionId,
+                            turnId
+                        });
+                        contextGc.reset();
+                        messages.splice(0, messages.length, environmentContextUpdate(executionEnvironment), ...compactedHistoryMessages(replacementHistory));
+                        restoreMcpDiscovery();
+                        projectedExecutionBudgetStage = undefined;
+                        recordedEnvironment = executionEnvironment;
+                        compactionUserMessages = replacementHistory
+                            .filter((message) => message.kind === 'user_input')
+                            .map((message) => message.content);
+                        agentInstructionInsertIndex = Math.max(0, messages.length - 1);
+                        currentResourceSnapshot = retainedSessionResourcesSnapshot(await loadRetainedSessionResources());
+                        contextualWorldState = resetContextualWorldState(compactRecord.recordId, agentInstructionInsertIndex, {
+                            instructionSnapshot: currentInstructionSnapshot,
+                            instructionContent: renderAgentInstructions(instructionEntries, true),
+                            resourceSnapshot: currentResourceSnapshot,
+                            previousMayContainResources: compactSummary.includes('# Retained Session resources')
+                        });
+                        sessionRuntime.contextualWorldState = contextualWorldState;
+                        await persistContextualWorldState(store, sessionId, contextualWorldState);
+                        lastServerContextTokens = undefined;
+                        lastServerUsage = undefined;
+                        requestReasoningEffort = reasoningEffort;
+                        effectiveReasoningEffort = reasoningEffort;
+                        await emit({ type: 'context.compacted', compactionId });
+                        return true;
+                    };
+                    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.');
+                    };
+                    executionLoop = new ExecutionLoop({
+                        mode,
+                        sourceType: sessionSource.type,
+                        signal: controller.signal,
+                        model: selectedModel,
+                        messages,
+                        toolImages: currentExecutionToolImages,
+                        rolloutBudget,
+                        publish: emit,
+                        appendContext: async (message) => {
+                            await store.append(sessionId, {
+                                type: 'model.context',
+                                payload: message,
+                                executionId,
+                                turnId
+                            });
+                        },
+                        prepareRound: async (pendingOutputContinuation) => {
+                            await appendMailboxMessages();
+                            appendExecutionBudgetEnvironment();
+                            executionTools = mcpRegistry.project(baseTools());
+                            if (mode !== 'compact')
+                                await syncMcpWorldState(messages.length);
+                            await ensureContextBudget();
+                            if (mode !== 'compact')
+                                await syncMcpWorldState(messages.length);
+                            appendExecutionBudgetEnvironment();
+                            if (mode !== 'compact') {
+                                executionEnvironment = { ...currentEnvironment, ...currentLocalTimeContext() };
+                                await recordEnvironment();
+                            }
+                            const toolsAllowed = mode !== 'compact' &&
+                                (!rolloutBudget?.active || rolloutBudget.stage !== 'exhausted');
+                            const roundTools = mode === 'compact' ? executionTools : toolsAllowed ? executionTools : [];
+                            const codeModeEnabled = roundTools.some((tool) => tool.name === 'code_exec');
+                            const residentTools = mcpRegistry.projectDirect(baseTools());
+                            const requestTools = (() => {
+                                if (selectedModel.protocol !== 'OPENAI_RESPONSES' ||
+                                    selectedModel.responsesEncoding === 'LITE')
+                                    return projectCodeModeTools(roundTools, residentTools);
+                                const directNames = new Set(residentTools.map((tool) => tool.name));
+                                // Discovery and caller policy are independent: keep nested declarations for active tools.
+                                return projectCodeModeTools(roundTools, residentTools).filter((tool) => directNames.has(tool.name));
+                            })();
+                            const systemPrompt = mode === 'compact'
+                                ? buildExecutionSystemPrompt(roundTools, 'run')
+                                : buildExecutionSystemPrompt(roundTools);
+                            const requestContextMessages = pendingOutputContinuation === undefined
+                                ? messages
+                                : [...messages, pendingOutputContinuation];
+                            const modelMessages = mode === 'compact'
+                                ? normalizeMessagesForModel(requestContextMessages, { supportsImages: false })
+                                : normalizeMessagesForModel(insertContextualWorldState(requestContextMessages, contextualWorldState.entries), {
+                                    supportsImages: selectedModel.inputCapabilities.includes('IMAGE')
+                                });
+                            const roundMcpExpectations = new Map(roundTools
+                                .filter((tool) => tool.name.startsWith('mcp__'))
+                                .map((tool) => [tool.name, mcpRegistry.expectedTool(tool.name)]));
+                            const toolContext = {
+                                host: host,
+                                todo,
+                                ...(subagents === undefined ? {} : { subagents }),
+                                mode,
+                                sessionId,
+                                executionId,
+                                signal: controller.signal,
+                                emit,
+                                skills: instructionContext?.skills ?? new Map()
+                            };
+                            const recentImages = () => currentExecutionImages(modelInputImages, currentExecutionToolImages);
+                            const toolScope = {
+                                context: toolContext,
+                                tools: roundTools,
+                                expectations: roundMcpExpectations,
+                                extensionToolNames: new Set((extensions.tools ?? []).map((tool) => tool.name)),
+                                schedule: sessionRuntime.scheduleTool,
+                                emit,
+                                searchMcpTools: (arguments_, searchSignal) => mcpRegistry.expose(arguments_, {
+                                    signal: searchSignal,
+                                    base: baseTools(),
+                                    window: selectedModel.contextWindowTokens,
+                                    system: systemPrompt
+                                }),
+                                recentImages,
+                                captureCodeContext: () => ({
+                                    ...toolContext,
+                                    ...(subagents ? { subagents: subagents.captureExecution() } : {}),
+                                    recentImages: recentImages()
+                                }),
+                                codeModeContext: async (call) => {
+                                    const stateSnapshot = call.name === 'code_exec' ? await store.readCodeModeState(sessionId) : [];
+                                    return {
+                                        retainSession: () => store.retainSessionLease(sessionId, sessionWriterOwner),
+                                        onSettled: async (result) => {
+                                            await store.append(sessionId, {
+                                                type: 'code.cell.completed',
+                                                payload: { ...result, callId: call.callId },
+                                                executionId,
+                                                turnId
+                                            });
+                                        },
+                                        supportsImages: selectedModel.inputCapabilities.includes('IMAGE'),
+                                        tools: roundTools.filter((tool) => allowsToolCaller(tool, 'programmatic')),
+                                        state: stateSnapshot,
+                                        commitState: (mutations) => store.commitCodeModeState(sessionId, mutations, {
+                                            executionId,
+                                            turnId,
+                                            expectedState: stateSnapshot
+                                        })
+                                    };
+                                }
+                            };
+                            return {
+                                request: {
+                                    system: systemPrompt,
+                                    messages: modelMessages.map((message) => projectCodeModeSearchResult(message, codeModeEnabled)),
+                                    tools: requestTools,
+                                    ...(mode === 'compact'
+                                        ? { toolChoice: 'none' }
+                                        : toolsAllowed
+                                            ? {}
+                                            : { allowTools: false }),
+                                    promptCacheKey: sessionId,
+                                    reasoningEffort,
+                                    ...(requestReasoningEffort === undefined ? {} : { requestReasoningEffort }),
+                                    ...(modelInputImages?.length ? { images: modelInputImages } : {}),
+                                    onAttemptDiagnostic: recordModelAttempt(mode === 'compact' ? 'COMPACTION' : 'EXECUTION')
+                                },
+                                toolScope
+                            };
+                        },
+                        startModel: async function* (request) {
+                            if (manualCompactionId !== undefined && !manualCompactionStarted) {
+                                manualCompactionStarted = true;
+                                manualCompaction = createCompactionOperation(manualCompactionId);
+                                await emit({ type: 'context.compacting', compactionId: manualCompactionId });
+                            }
+                            yield* manualCompaction
+                                ? manualCompaction.start(selected, request)
+                                : selected.start(request, controller.signal);
+                        },
+                        recoverySignal: () => manualCompaction?.signal ?? controller.signal,
+                        compactContext,
+                        compactionFallback: useManualCompactionFallback,
+                        observeContextTokens: (tokens) => {
+                            lastServerContextTokens = tokens;
+                        },
+                        observeUsage: (usage) => {
+                            if (usage !== undefined) {
+                                lastServerContextTokens = usage.contextInputTokens;
+                                lastServerUsage = { ...usage, historyMessages: [...messages] };
+                            }
+                        },
+                        checkpoint: async (round, latestUsage) => {
+                            if (mode !== 'compact' &&
+                                sessionSource.type !== 'subagent' &&
+                                latestUsage !== undefined) {
+                                // Only a committed GC checkpoint may replace active context and invalidate continuation.
+                                const committed = await contextGc.run({
+                                    store,
+                                    sessionId,
+                                    system: round.request.system,
+                                    tools: round.toolScope.tools,
+                                    modelId: selectedModel.id,
+                                    contextWindowTokens: selectedModel.contextWindowTokens,
+                                    usage: latestUsage,
+                                    modelProtocol: selectedModel.protocol,
+                                    responsesConfigurationUpdates: usesResponsesConfigurationUpdates(selectedModel),
+                                    workspace: logicalWorkspace,
+                                    platform: description.platform,
+                                    getActiveProcessIds: async () => {
+                                        const resources = await host
+                                            .listSessionResources?.(sessionId)
+                                            .catch(() => undefined);
+                                        return new Set((resources?.processes ?? [])
+                                            .filter((process) => process.status === 'running')
+                                            .map((process) => process.processId));
+                                    }
+                                });
+                                if (committed) {
+                                    selected.resetContinuation?.();
+                                    const refreshed = await restoreMessages(store, sessionId, committed.records, {
+                                        includeImages: true,
+                                        currentTurnId: turnId,
+                                        projection: committed.projection
+                                    });
+                                    messages.splice(0, messages.length, ...refreshed.messages);
+                                    restoreMcpDiscovery();
+                                    projectedExecutionBudgetStage = undefined;
+                                    recordedEnvironment = refreshed.environmentState;
+                                    compactionUserMessages = [...refreshed.userMessages];
+                                    agentInstructionInsertIndex =
+                                        refreshed.currentTurnUserIndex ?? Math.max(0, messages.length - 1);
+                                    if (agentInstructionInsertIndex &&
+                                        messages[agentInstructionInsertIndex - 1]?.contextKind === 'environment')
+                                        agentInstructionInsertIndex--;
+                                    currentResourceSnapshot = retainedSessionResourcesSnapshot(await loadRetainedSessionResources());
+                                    contextualWorldState = resetContextualWorldState(latestContextualWorldStateGeneration(committed.records), agentInstructionInsertIndex, {
+                                        instructionSnapshot: currentInstructionSnapshot,
+                                        instructionContent: renderAgentInstructions(instructionEntries, committed.records.some((record) => compactSummaryFromCheckpoint(record) !== undefined)),
+                                        resourceSnapshot: currentResourceSnapshot,
+                                        previousMayContainResources: compactHistoryMayContainRetainedResources(committed.records)
+                                    });
+                                    sessionRuntime.contextualWorldState = contextualWorldState;
+                                    await persistContextualWorldState(store, sessionId, contextualWorldState);
+                                }
+                            }
+                        },
+                        mailbox: {
+                            hasPending: () => mailbox.length > 0,
+                            append: appendMailboxMessages,
+                            close: () => {
+                                acceptsMailbox = false;
+                            }
+                        }
+                    });
+                    const completed = await executionLoop.run();
+                    finalAnswer = completed.finalAnswer;
+                    const compactSummary = mode === 'compact' ? finalAnswer.trim() : '';
+                    if (manualCompaction) {
+                        manualCompaction.signal.throwIfAborted();
+                        await manualCompaction.dispose();
+                    }
+                    if (mode === 'compact')
+                        await store.compact(sessionId, {
+                            summary: compactSummary,
+                            replacementHistory: buildCompactedHistory(compactSummary, compactionUserMessages, compactUserTokenLimit),
+                            modelId: selectedModel.id,
+                            contextWindowTokens: selectedModel.contextWindowTokens,
+                            ...(completed.usage === undefined ? {} : { usage: completed.usage }),
+                            executionId,
+                            turnId
+                        });
+                    if (mode === 'compact' && manualCompactionId !== undefined)
+                        await emit({ type: 'context.compacted', compactionId: manualCompactionId });
+                    await settleTitle();
+                    subagents?.endParentExecution(executionId);
+                    await emit({ type: 'execution.completed' });
+                    return {
+                        executionId,
+                        status: 'completed',
+                        finalAnswer: mode === 'compact' ? '' : finalAnswer
+                    };
+                }
+                catch (error) {
+                    finalAnswer = executionLoop?.finalAnswer ?? finalAnswer;
+                    acceptsMailbox = false;
+                    await settleTitle();
+                    if (controller.signal.aborted) {
+                        subagents?.endParentExecution(executionId);
+                        await emit({ type: 'execution.cancelled' });
+                        return {
+                            executionId,
+                            status: 'cancelled',
+                            finalAnswer: mode === 'compact' ? '' : finalAnswer
+                        };
+                    }
+                    const diagnostic = modelAttemptFailureDiagnostic(describeMarAgentError(error, 'MAR_AGENT_EXECUTION_FAILED'), exhaustedModelAttempt);
+                    subagents?.endParentExecution(executionId);
+                    await emit({ type: 'execution.failed', ...diagnostic });
+                    return {
+                        executionId,
+                        status: 'failed',
+                        finalAnswer: mode === 'compact' ? '' : finalAnswer,
+                        errorCode: diagnostic.code,
+                        errorMessage: diagnostic.message
+                    };
+                }
+                finally {
+                    acceptsMailbox = false;
+                    if (ownsRolloutBudget)
+                        rolloutBudget.discard();
+                    await manualCompaction?.dispose();
+                    await selectedTurn?.close().catch(() => undefined);
+                    if (titleAdapter !== undefined && titleAdapter !== selectedAdapter)
+                        executionScopedAdapters.add(titleAdapter);
+                    try {
+                        await closeModelAdapters(executionScopedAdapters);
+                    }
+                    catch {
+                        // Execution cleanup is best effort.
+                    }
+                    finally {
+                        for (const adapter of executionScopedAdapters)
+                            activeExecutionAdapters.delete(adapter);
+                    }
+                    subagents?.endParentExecution(executionId);
+                    await releaseSession?.();
+                    active.delete(`${sessionId}:${executionId}`);
+                    queue.close();
+                }
+            })();
+            const executionKey = `${sessionId}:${executionId}`;
+            executionResults.set(executionKey, result);
+            void result.then(() => executionResults.delete(executionKey), () => executionResults.delete(executionKey));
+            return {
+                executionId,
+                turnId,
+                [Symbol.asyncIterator]: () => queue[Symbol.asyncIterator](),
+                result: () => {
+                    queue.discardIfUnobserved();
+                    return result;
+                },
+                cancel: () => controller.abort(new MarAgentError('MAR_AGENT_CANCELLED', 'Execution was cancelled.')),
+                enqueueMessage: (message, delivery) => {
+                    if (!acceptsMailbox || controller.signal.aborted)
+                        return false;
+                    mailbox.push({ text: message, ...(delivery ? { delivery } : {}) });
+                    return true;
+                }
+            };
+        };
+        return {
+            id: sessionId,
+            run: (input) => execution('run', input),
+            plan: (input) => execution('plan', input),
+            compact: (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,
+                modelId: turn.modelId,
+                reasoningEffort: turn.reasoningEffort
+            }, {
+                publishHostEvents: false,
+                inputSource: 'parent_agent',
+                initialMailbox: turn.initialMailbox,
+                turnId: turn.turnId,
+                mcpExecutionScopeId: turn.mcpExecutionScopeId,
+                ...(turn.delivery ? { delivery: turn.delivery } : {}),
+                ...(turn.sharedRolloutBudget === undefined
+                    ? {}
+                    : { sharedRolloutBudget: turn.sharedRolloutBudget })
+            })
+        };
+    };
+    return openSession;
+}
+function modelAttemptFailureDiagnostic(diagnostic, summary) {
+    if (summary === undefined)
+        return diagnostic;
+    const prefix = `Model request failed after ${summary.attempts} attempts (${summary.retries} retries). `;
+    const availableCharacters = Math.max(0, 1_000 - [...prefix].length);
+    return {
+        code: diagnostic.code,
+        message: `${prefix}${[...diagnostic.message].slice(0, availableCharacters).join('')}`
+    };
+}