@astralyn/pi 0.87.0 → 0.87.2

package/dist/core/agent-session.js

@@ -58,9 +58,6 @@ export function parseSkillBlock(text) {
         userMessage: match[4]?.trim() || undefined,
     };
 }
-// ============================================================================
-// Types
-// ============================================================================
 function withoutDeletedHeaders(headers) {
     return headers
         ? Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] !== null))
@@ -89,6 +86,8 @@ export class AgentSession {
         this._pendingNextTurnMessages = [];
         /** Context-only custom messages queued during a run, flushed once the current turn's tool results are in. */
         this._pendingCustomMessages = [];
+        /** Background completions queued for steering, awaiting the persistence that confirms delivery. */
+        this._queuedBackgroundCompletions = new Map();
         // Compaction state
         this._compactionAbortController = undefined;
         this._autoCompactionAbortController = undefined;
@@ -122,6 +121,12 @@ export class AgentSession {
             // Preserve host delivery identity before extension message_end transforms.
             // Content/details may be replaced, but a persisted replacement is still an ack.
             const acknowledgeBackground = event.type === "message_end" ? this._backgroundHost.messageAcknowledgement(event.message) : undefined;
+            // A queued completion is tracked by identity too, for the same reason.
+            const queuedBackgroundCompletion = event.type === "message_start" || event.type === "message_end"
+                ? this._queuedBackgroundCompletions.get(event.message)
+                : undefined;
+            if (event.type === "message_start" && queuedBackgroundCompletion)
+                queuedBackgroundCompletion.drained = true;
             // When a user message starts, check if it's from either queue and remove it BEFORE emitting
             // This ensures the UI sees the updated queue state
             if (event.type === "message_start" && event.message.role === "user") {
@@ -149,8 +154,10 @@ export class AgentSession {
             this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
             // Handle session persistence
             if (event.type === "message_end") {
-                if (this._persistMessage(event.message))
+                if (this._persistMessage(event.message)) {
                     acknowledgeBackground?.();
+                    queuedBackgroundCompletion?.resolve();
+                }
                 if (event.message.role === "assistant") {
                     const assistantMsg = event.message;
                     this._lastAssistantMessage = assistantMsg;
@@ -178,6 +185,8 @@ export class AgentSession {
                 this._lastAssistantToolResults = event.toolResults;
                 this._flushPendingCustomMessages();
             }
+            if (event.type === "agent_end")
+                this._failDrainedBackgroundCompletions();
         };
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
@@ -185,16 +194,15 @@ export class AgentSession {
         this._backgroundHost = new BackgroundSession({
             manager: this.sessionManager,
             role: config.executionRole ?? "main",
-            canDeliver: () => this.isIdle &&
-                !this.agent.state.isStreaming &&
-                this.pendingMessageCount === 0 &&
-                !this.agent.hasQueuedMessages() &&
-                this.model !== undefined,
-            deliver: (message) => {
-                // Completion turns skip before_agent_start, but consume nextTurn context.
-                const asides = this._pendingNextTurnMessages.slice();
-                return this._runAgentPrompt(asides.length ? [message, ...asides] : message);
+            canDeliver: () => {
+                if (this.model === undefined || this.isCompacting)
+                    return false;
+                // A completion steered into an active run follows the interactive steering queue, which
+                // already preserves the order of queued user input. An idle delivery starts its own
+                // turn, so it still waits for the queues to drain.
+                return this.isStreaming || (this.pendingMessageCount === 0 && !this.agent.hasQueuedMessages());
             },
+            deliver: (message) => this._deliverBackgroundCompletion(message),
             onEntry: (entry) => this._emit({ type: "entry_appended", entry }),
             onError: (event, error) => this._extensionRunner?.emitError({ extensionPath: "<background>", event, error }),
         });
@@ -243,6 +251,19 @@ export class AgentSession {
     retryBackgroundNotifications() {
         this._backgroundHost.retry();
     }
+    /**
+     * Run a lifecycle operation with delivery paused across its asynchronous gaps.
+     * Lifecycle methods are thin shells over upstream bodies so those keep upstream's shape.
+     */
+    async _withBackgroundPaused(operation) {
+        const resumeBackground = this.pauseBackgroundNotifications();
+        try {
+            return await operation();
+        }
+        finally {
+            resumeBackground();
+        }
+    }
     get modelRuntime() {
         return this._modelRuntime;
     }
@@ -635,28 +656,36 @@ export class AgentSession {
         this._resolveIdleWait = undefined;
         resolve();
     }
+    /**
+     * Background completions stay paused until runs requested by settled handlers have started,
+     * so a deferred prompt never races a delivery for the same idle gap.
+     */
     async _emitAgentSettled() {
+        return this._withBackgroundPaused(() => this._emitAgentSettledBody());
+    }
+    async _emitAgentSettledBody() {
         this._cacheWarmer?.onAgentSettled();
-        // Background completions stay paused until runs requested by settled handlers have started,
-        // so a deferred prompt never races a delivery for the same idle gap.
-        const resumeBackground = this.pauseBackgroundNotifications();
         this._isAgentRunActive = false;
+        this._isEmittingAgentSettled = true;
         try {
-            this._isEmittingAgentSettled = true;
+            await this._extensionRunner.emit({ type: "agent_settled" });
+            this._emit({ type: "agent_settled" });
+        }
+        finally {
+            this._isEmittingAgentSettled = false;
+        }
+        const deferred = this._deferredSettledActions.splice(0);
+        if (deferred.length > 0) {
             try {
-                await this._extensionRunner.emit({ type: "agent_settled" });
-                this._emit({ type: "agent_settled" });
+                for (const action of deferred)
+                    await action();
             }
             finally {
-                this._isEmittingAgentSettled = false;
+                this._resolveIdleWaitIfIdle();
             }
-            for (const action of this._deferredSettledActions.splice(0))
-                await action();
-        }
-        finally {
-            this._resolveIdleWaitIfIdle();
-            resumeBackground();
+            return;
         }
+        this._resolveIdleWaitIfIdle();
     }
     /**
      * Persist model/custom messages and consume queued context only after the append succeeds.
@@ -881,6 +910,9 @@ export class AgentSession {
      */
     dispose() {
         this._backgroundHost.dispose();
+        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
+            queued.reject(new Error("the session was disposed"));
+        }
         try {
             this.abortRetry();
             this.abortCompaction();
@@ -1164,6 +1196,55 @@ export class AgentSession {
             await this._emitAgentSettled();
         }
     }
+    /**
+     * Deliver a background completion through the same queueing path as interactive input:
+     * steering into an active run lands the result right after the current tool batch, and an
+     * idle session starts its own turn. The promise settles only once the message is persisted,
+     * or once it can no longer be persisted, so the caller never releases its claim for a
+     * message the transcript does not contain.
+     */
+    _deliverBackgroundCompletion(message) {
+        if (!this.isStreaming) {
+            // Completion turns skip before_agent_start, but consume nextTurn context.
+            const asides = this._pendingNextTurnMessages.slice();
+            return this._runAgentPrompt(asides.length ? [message, ...asides] : message);
+        }
+        return new Promise((resolve, reject) => {
+            const queued = {
+                drained: false,
+                resolve: () => {
+                    if (this._queuedBackgroundCompletions.get(message) !== queued)
+                        return;
+                    this._queuedBackgroundCompletions.delete(message);
+                    resolve();
+                },
+                reject: (reason) => {
+                    if (this._queuedBackgroundCompletions.get(message) !== queued)
+                        return;
+                    this._queuedBackgroundCompletions.delete(message);
+                    reject(reason);
+                },
+            };
+            this._queuedBackgroundCompletions.set(message, queued);
+            try {
+                this.agent.steer(message);
+            }
+            catch (error) {
+                queued.reject(error);
+            }
+        });
+    }
+    /**
+     * Fail deliveries the owning run emitted but never persisted. A completion still sitting in
+     * the steering queue when its run ends stays claimed: the next run delivers it, so failing
+     * it here would persist the same message twice.
+     */
+    _failDrainedBackgroundCompletions() {
+        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
+            if (queued.drained)
+                queued.reject(new Error("the completion message was not persisted"));
+        }
+    }
     async _handlePostAgentRun() {
         const message = this._lastAssistantMessage;
         const toolResults = this._lastAssistantToolResults;
@@ -1274,134 +1355,132 @@ export class AgentSession {
         this.retryBackgroundNotifications();
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
-        // Observer commands may stay open indefinitely. Their lifecycle operations
-        // pause independently; only real model input owns the preflight pause.
-        if (expandPromptTemplates && text.startsWith("/")) {
-            try {
-                if (await this._tryExecuteExtensionCommand(text)) {
+        let messages;
+        let resumeBackground;
+        try {
+            // Handle extension commands first (execute immediately, even during streaming)
+            // Extension commands manage their own LLM interaction via pi.sendMessage()
+            if (expandPromptTemplates && text.startsWith("/")) {
+                const handled = await this._tryExecuteExtensionCommand(text);
+                if (handled) {
+                    // Extension command executed, no prompt to send
                     preflightResult?.(true);
                     return;
                 }
             }
-            catch (error) {
-                preflightResult?.(false);
-                throw error;
+            // Observer commands above may stay open indefinitely; only real model input owns
+            // the preflight pause, released once the user message is established.
+            resumeBackground = this.pauseBackgroundNotifications();
+            if (this._compactionAbortController !== undefined) {
+                throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
             }
-        }
-        const resumeBackground = this.pauseBackgroundNotifications();
-        try {
-            let messages;
-            try {
-                if (this._compactionAbortController !== undefined) {
-                    throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
-                }
-                // Emit input event for extension interception (before skill/template expansion)
-                const processedInput = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
-                if (!processedInput) {
-                    preflightResult?.(true);
-                    return;
-                }
-                const { text: currentText, images: currentImages } = processedInput;
-                // Expand skill commands (/skill:name args) and prompt templates (/template args)
-                let expandedText = currentText;
-                if (expandPromptTemplates) {
-                    expandedText = this._expandSkillCommand(expandedText);
-                    expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-                }
-                // If streaming, queue via steer() or followUp() based on option
-                if (this.isStreaming) {
-                    if (!options?.streamingBehavior) {
-                        throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
-                    }
-                    if (options.streamingBehavior === "followUp") {
-                        await this._queueFollowUp(expandedText, currentImages);
-                    }
-                    else {
-                        await this._queueSteer(expandedText, currentImages);
-                    }
-                    preflightResult?.(true);
-                    return;
+            // Emit input event for extension interception (before skill/template expansion)
+            const processedInput = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
+            if (!processedInput) {
+                preflightResult?.(true);
+                return;
+            }
+            const { text: currentText, images: currentImages } = processedInput;
+            // Expand skill commands (/skill:name args) and prompt templates (/template args)
+            let expandedText = currentText;
+            if (expandPromptTemplates) {
+                expandedText = this._expandSkillCommand(expandedText);
+                expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+            }
+            // If streaming, queue via steer() or followUp() based on option
+            if (this.isStreaming) {
+                if (!options?.streamingBehavior) {
+                    throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
                 }
-                // Flush any pending bash and custom messages before the new prompt
-                this._flushPendingBashMessages();
-                this._flushPendingCustomMessages();
-                // Validate model
-                if (!this.model) {
-                    throw new Error(formatNoModelSelectedMessage());
+                if (options.streamingBehavior === "followUp") {
+                    await this._queueFollowUp(expandedText, currentImages);
                 }
-                const hasConfiguredAuth = this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
-                    (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
-                if (!hasConfiguredAuth) {
-                    const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
-                    if (isOAuth) {
-                        throw new Error(`Authentication failed for "${this.model.provider}". ` +
-                            `Credentials may have expired or network is unavailable. ` +
-                            `Run '/login ${this.model.provider}' to re-authenticate.`);
-                    }
-                    throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
+                else {
+                    await this._queueSteer(expandedText, currentImages);
                 }
-                // Check if we need to compact before sending (catches aborted responses).
-                // The user's new prompt is sent below, so do not call agent.continue() here.
-                const lastAssistant = this._findLastAssistantMessage();
-                if (lastAssistant) {
-                    await this._checkCompaction(lastAssistant, false);
+                preflightResult?.(true);
+                return;
+            }
+            // Flush any pending bash and custom messages before the new prompt
+            this._flushPendingBashMessages();
+            this._flushPendingCustomMessages();
+            // Validate model
+            if (!this.model) {
+                throw new Error(formatNoModelSelectedMessage());
+            }
+            const hasConfiguredAuth = this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
+                (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
+            if (!hasConfiguredAuth) {
+                const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
+                if (isOAuth) {
+                    throw new Error(`Authentication failed for "${this.model.provider}". ` +
+                        `Credentials may have expired or network is unavailable. ` +
+                        `Run '/login ${this.model.provider}' to re-authenticate.`);
                 }
-                // Emit before_agent_start before normalizing images so extension-driven model
-                // selection determines the resize profile used for the request and history.
-                const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
-                const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptOptions);
-                // Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
-                // which updates the live loadout instead. An explicit edit wins; otherwise the live
-                // loadout is authoritative, so a setActiveTools() call is not undone here.
-                const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
-                    result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
-                if (!handlerEditedTools)
-                    result.systemPromptOptions.selectedTools = this.getActiveToolNames();
-                const normalized = await this._normalizePromptImages(currentImages);
-                const userText = normalized.hints.length > 0 ? `${expandedText}\n\n${normalized.hints.join("\n")}` : expandedText;
-                // Build messages only after hooks and image normalization have completed.
-                messages = [];
-                const userContent = [{ type: "text", text: userText }];
-                userContent.push(...normalized.images);
+                throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
+            }
+            // Check if we need to compact before sending (catches aborted responses).
+            // The user's new prompt is sent below, so do not call agent.continue() here.
+            const lastAssistant = this._findLastAssistantMessage();
+            if (lastAssistant) {
+                await this._checkCompaction(lastAssistant, false);
+            }
+            // Emit before_agent_start before normalizing images so extension-driven model
+            // selection determines the resize profile used for the request and history.
+            const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
+            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptOptions);
+            // Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
+            // which updates the live loadout instead. An explicit edit wins; otherwise the live
+            // loadout is authoritative, so a setActiveTools() call is not undone here.
+            const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
+                result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
+            if (!handlerEditedTools)
+                result.systemPromptOptions.selectedTools = this.getActiveToolNames();
+            const normalized = await this._normalizePromptImages(currentImages);
+            const userText = normalized.hints.length > 0 ? `${expandedText}\n\n${normalized.hints.join("\n")}` : expandedText;
+            // Build messages only after hooks and image normalization have completed.
+            messages = [];
+            const userContent = [{ type: "text", text: userText }];
+            userContent.push(...normalized.images);
+            messages.push({
+                role: "user",
+                content: userContent,
+                timestamp: Date.now(),
+            });
+            // Inject any pending "nextTurn" messages as context alongside the user message.
+            // They stay queued until _persistMessage() confirms the append.
+            for (const msg of this._pendingNextTurnMessages) {
+                messages.push(msg);
+            }
+            for (const msg of result.messages) {
                 messages.push({
-                    role: "user",
-                    content: userContent,
+                    role: "custom",
+                    customType: msg.customType,
+                    // Untyped extensions can pass null/missing content; normalize at ingestion.
+                    content: msg.content ?? [],
+                    display: msg.display,
+                    details: msg.details,
                     timestamp: Date.now(),
                 });
-                // Inject any pending "nextTurn" messages as context alongside the user message.
-                // They stay queued until _persistMessage() confirms the append.
-                for (const msg of this._pendingNextTurnMessages) {
-                    messages.push(msg);
-                }
-                for (const msg of result.messages) {
-                    messages.push({
-                        role: "custom",
-                        customType: msg.customType,
-                        // Untyped extensions can pass null/missing content; normalize at ingestion.
-                        content: msg.content ?? [],
-                        display: msg.display,
-                        details: msg.details,
-                        timestamp: Date.now(),
-                    });
-                }
-                const updateMessage = this._preparePromptAndToolLoadout(result.systemPromptOptions);
-                this._runSystemPromptOptions = result.systemPromptOptions;
-                if (updateMessage)
-                    messages.unshift(updateMessage);
-            }
-            catch (error) {
-                preflightResult?.(false);
-                throw error;
-            }
-            if (!messages) {
-                return;
             }
-            preflightResult?.(true);
-            await this._runAgentPrompt(messages);
+            const updateMessage = this._preparePromptAndToolLoadout(result.systemPromptOptions);
+            this._runSystemPromptOptions = result.systemPromptOptions;
+            if (updateMessage)
+                messages.unshift(updateMessage);
+        }
+        catch (error) {
+            preflightResult?.(false);
+            throw error;
         }
         finally {
-            resumeBackground();
+            // Delivery is timer-scheduled, so a completion cannot start before the run below does.
+            resumeBackground?.();
         }
+        if (!messages) {
+            return;
+        }
+        preflightResult?.(true);
+        await this._runAgentPrompt(messages);
     }
     /**
      * Try to execute an extension command. Returns true if command was found and executed.
@@ -1658,6 +1737,10 @@ export class AgentSession {
         this._steeringMessages = [];
         this._followUpMessages = [];
         this.agent.clearAllQueues();
+        // Clearing the queues drops queued completions; fail them so their claims retry.
+        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
+            queued.reject(new Error("the completion message was dequeued before delivery"));
+        }
         this._emitQueueUpdate();
         return { steering, followUp };
     }
@@ -1937,137 +2020,134 @@ export class AgentSession {
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
-        const resumeBackground = this.pauseBackgroundNotifications();
+        return this._withBackgroundPaused(() => this._compactBody(customInstructions));
+    }
+    async _compactBody(customInstructions) {
+        await this.abort();
+        this._compactionAbortController = new AbortController();
+        this._emit({ type: "compaction_start", reason: "manual" });
+        let fromExtension = false;
+        let cancelledByExtension = false;
         try {
-            await this.abort();
-            this._compactionAbortController = new AbortController();
-            this._emit({ type: "compaction_start", reason: "manual" });
-            let fromExtension = false;
-            let cancelledByExtension = false;
-            try {
-                const model = this.model;
-                if (!model) {
-                    throw new Error(formatNoModelSelectedMessage());
-                }
-                const settings = this.settingsManager.getCompactionSettings(model);
-                const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, this._compactionAbortController.signal);
-                const pathEntries = this.sessionManager.getBranch();
-                const preparation = prepareCompaction(pathEntries, settings);
-                if (!preparation) {
-                    // Check why we can't compact
-                    const lastEntry = pathEntries[pathEntries.length - 1];
-                    if (lastEntry?.type === "compaction") {
-                        throw new Error("Already compacted");
-                    }
-                    throw new Error("Nothing to compact (session too small)");
-                }
-                let extensionCompaction;
-                if (this._extensionRunner.hasHandlers("session_before_compact")) {
-                    const result = (await this._extensionRunner.emit({
-                        type: "session_before_compact",
-                        preparation,
-                        branchEntries: pathEntries,
-                        customInstructions,
-                        reason: "manual",
-                        willRetry: false,
-                        signal: this._compactionAbortController.signal,
-                    }));
-                    if (result?.cancel) {
-                        cancelledByExtension = true;
-                        throw new Error("Compaction cancelled");
-                    }
-                    if (result?.compaction) {
-                        extensionCompaction = result.compaction;
-                        fromExtension = true;
-                    }
-                }
-                let summary;
-                let firstKeptEntryId;
-                let tokensBefore;
-                let usage;
-                let details;
-                if (extensionCompaction) {
-                    // Extension provided compaction content
-                    summary = extensionCompaction.summary;
-                    firstKeptEntryId = extensionCompaction.firstKeptEntryId;
-                    tokensBefore = extensionCompaction.tokensBefore;
-                    usage = extensionCompaction.usage;
-                    details = extensionCompaction.details;
-                }
-                else {
-                    // Shared default summary generator, also used by automatic compaction.
-                    const result = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, env, "manual");
-                    summary = result.summary;
-                    firstKeptEntryId = result.firstKeptEntryId;
-                    tokensBefore = result.tokensBefore;
-                    usage = result.usage;
-                    details = result.details;
+            const model = this.model;
+            if (!model) {
+                throw new Error(formatNoModelSelectedMessage());
+            }
+            const settings = this.settingsManager.getCompactionSettings(model);
+            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, this._compactionAbortController.signal);
+            const pathEntries = this.sessionManager.getBranch();
+            const preparation = prepareCompaction(pathEntries, settings);
+            if (!preparation) {
+                // Check why we can't compact
+                const lastEntry = pathEntries[pathEntries.length - 1];
+                if (lastEntry?.type === "compaction") {
+                    throw new Error("Already compacted");
                 }
-                if (this._compactionAbortController.signal.aborted) {
+                throw new Error("Nothing to compact (session too small)");
+            }
+            let extensionCompaction;
+            if (this._extensionRunner.hasHandlers("session_before_compact")) {
+                const result = (await this._extensionRunner.emit({
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
+                    customInstructions,
+                    reason: "manual",
+                    willRetry: false,
+                    signal: this._compactionAbortController.signal,
+                }));
+                if (result?.cancel) {
+                    cancelledByExtension = true;
                     throw new Error("Compaction cancelled");
                 }
-                this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
-                const newEntries = this.sessionManager.getEntries();
-                this._refreshFinalizedContext();
-                const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
-                // Get the saved compaction entry for the extension event
-                const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
-                if (this._extensionRunner && savedCompactionEntry) {
-                    await this._extensionRunner.emit({
-                        type: "session_compact",
-                        compactionEntry: savedCompactionEntry,
-                        fromExtension,
-                        reason: "manual",
-                        willRetry: false,
-                    });
+                if (result?.compaction) {
+                    extensionCompaction = result.compaction;
+                    fromExtension = true;
                 }
-                const compactionResult = {
-                    summary,
-                    firstKeptEntryId,
-                    tokensBefore,
-                    estimatedTokensAfter,
-                    usage,
-                    details,
-                };
-                // compaction_end listeners may submit queued prompts, so expose idle state before notifying them.
-                this._clearManualCompactionState();
-                this._emit({
-                    type: "compaction_end",
-                    reason: "manual",
-                    result: compactionResult,
-                    aborted: false,
-                    willRetry: false,
-                });
-                return compactionResult;
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                const aborted = this._compactionAbortController?.signal.aborted === true || cancelledByExtension;
-                const errorMessage = aborted ? undefined : `Compaction failed: ${message}`;
-                this._clearManualCompactionState();
-                this._emit({
-                    type: "compaction_end",
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let usage;
+            let details;
+            if (extensionCompaction) {
+                // Extension provided compaction content
+                summary = extensionCompaction.summary;
+                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
+                tokensBefore = extensionCompaction.tokensBefore;
+                usage = extensionCompaction.usage;
+                details = extensionCompaction.details;
+            }
+            else {
+                // Shared default summary generator, also used by automatic compaction.
+                const result = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, env, "manual");
+                summary = result.summary;
+                firstKeptEntryId = result.firstKeptEntryId;
+                tokensBefore = result.tokensBefore;
+                usage = result.usage;
+                details = result.details;
+            }
+            if (this._compactionAbortController.signal.aborted) {
+                throw new Error("Compaction cancelled");
+            }
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
+            const newEntries = this.sessionManager.getEntries();
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
+            // Get the saved compaction entry for the extension event
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (this._extensionRunner && savedCompactionEntry) {
+                await this._extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
+                    fromExtension,
                     reason: "manual",
-                    result: undefined,
-                    aborted,
                     willRetry: false,
-                    errorMessage,
                 });
-                await this._emitSessionCompactFailed({
-                    reason: "manual",
-                    errorMessage,
-                    aborted,
-                    willRetry: false,
-                    fromExtension,
-                });
-                throw error;
-            }
-            finally {
-                this._clearManualCompactionState();
             }
+            const compactionResult = {
+                summary,
+                firstKeptEntryId,
+                tokensBefore,
+                estimatedTokensAfter,
+                usage,
+                details,
+            };
+            // compaction_end listeners may submit queued prompts, so expose idle state before notifying them.
+            this._clearManualCompactionState();
+            this._emit({
+                type: "compaction_end",
+                reason: "manual",
+                result: compactionResult,
+                aborted: false,
+                willRetry: false,
+            });
+            return compactionResult;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const aborted = this._compactionAbortController.signal.aborted || cancelledByExtension;
+            const errorMessage = aborted ? undefined : `Compaction failed: ${message}`;
+            this._clearManualCompactionState();
+            this._emit({
+                type: "compaction_end",
+                reason: "manual",
+                result: undefined,
+                aborted,
+                willRetry: false,
+                errorMessage,
+            });
+            await this._emitSessionCompactFailed({
+                reason: "manual",
+                errorMessage,
+                aborted,
+                willRetry: false,
+                fromExtension,
+            });
+            throw error;
         }
         finally {
-            resumeBackground();
+            this._clearManualCompactionState();
         }
     }
     /**
@@ -2230,140 +2310,137 @@ export class AgentSession {
      * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
-        const resumeBackground = this.pauseBackgroundNotifications();
+        return this._withBackgroundPaused(() => this._runAutoCompactionBody(reason, willRetry));
+    }
+    async _runAutoCompactionBody(reason, willRetry) {
+        const model = this.model;
+        const settings = this.settingsManager.getCompactionSettings(model);
+        let abortController;
+        let started = false;
+        let fromExtension = false;
+        let cancelledByExtension = false;
         try {
-            const model = this.model;
-            const settings = this.settingsManager.getCompactionSettings(model);
-            let abortController;
-            let started = false;
-            let fromExtension = false;
-            let cancelledByExtension = false;
-            try {
-                if (!model) {
-                    return false;
-                }
-                const pathEntries = this.sessionManager.getBranch();
-                const preparation = prepareCompaction(pathEntries, settings);
-                if (!preparation) {
-                    return false;
-                }
-                abortController = new AbortController();
-                this._autoCompactionAbortController = abortController;
-                started = true;
-                this._emit({ type: "compaction_start", reason });
-                abortController.signal.throwIfAborted();
-                const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, abortController.signal);
-                abortController.signal.throwIfAborted();
-                let extensionCompaction;
-                if (this._extensionRunner.hasHandlers("session_before_compact")) {
-                    const extensionResult = (await this._extensionRunner.emit({
-                        type: "session_before_compact",
-                        preparation,
-                        branchEntries: pathEntries,
-                        customInstructions: undefined,
-                        reason,
-                        willRetry,
-                        signal: abortController.signal,
-                    }));
-                    if (extensionResult?.cancel) {
-                        cancelledByExtension = true;
-                        throw new Error("Compaction cancelled");
-                    }
-                    if (extensionResult?.compaction) {
-                        extensionCompaction = extensionResult.compaction;
-                        fromExtension = true;
-                    }
-                }
-                abortController.signal.throwIfAborted();
-                let summary;
-                let firstKeptEntryId;
-                let tokensBefore;
-                let usage;
-                let details;
-                if (extensionCompaction) {
-                    // Extension provided compaction content
-                    summary = extensionCompaction.summary;
-                    firstKeptEntryId = extensionCompaction.firstKeptEntryId;
-                    tokensBefore = extensionCompaction.tokensBefore;
-                    usage = extensionCompaction.usage;
-                    details = extensionCompaction.details;
-                }
-                else {
-                    // Shared default summary generator, also used by manual compaction.
-                    const compactResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, undefined, abortController.signal, env, reason);
-                    summary = compactResult.summary;
-                    firstKeptEntryId = compactResult.firstKeptEntryId;
-                    tokensBefore = compactResult.tokensBefore;
-                    usage = compactResult.usage;
-                    details = compactResult.details;
-                }
-                abortController.signal.throwIfAborted();
-                this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
-                const newEntries = this.sessionManager.getEntries();
-                this._refreshFinalizedContext();
-                const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
-                // Get the saved compaction entry for the extension event
-                const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
-                if (this._extensionRunner && savedCompactionEntry) {
-                    await this._extensionRunner.emit({
-                        type: "session_compact",
-                        compactionEntry: savedCompactionEntry,
-                        fromExtension,
-                        reason,
-                        willRetry,
-                    });
-                }
-                const result = {
-                    summary,
-                    firstKeptEntryId,
-                    tokensBefore,
-                    estimatedTokensAfter,
-                    usage,
-                    details,
-                };
-                this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-                if (willRetry)
-                    return true;
-                // Auto-compaction can complete while follow-up/steering/custom messages are waiting.
-                // Continue once so queued messages are delivered.
-                return this.agent.hasQueuedMessages();
+            if (!model) {
+                return false;
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : "compaction failed";
-                const aborted = abortController?.signal.aborted === true || cancelledByExtension;
-                if (started) {
-                    const errorMessage = aborted
-                        ? undefined
-                        : reason === "overflow"
-                            ? `Context overflow recovery failed: ${message}`
-                            : `Auto-compaction failed: ${message}`;
-                    this._emit({
-                        type: "compaction_end",
-                        reason,
-                        result: undefined,
-                        aborted,
-                        willRetry: false,
-                        errorMessage,
-                    });
-                    await this._emitSessionCompactFailed({
-                        reason,
-                        errorMessage,
-                        aborted,
-                        willRetry: false,
-                        fromExtension,
-                    });
-                }
+            const pathEntries = this.sessionManager.getBranch();
+            const preparation = prepareCompaction(pathEntries, settings);
+            if (!preparation) {
                 return false;
             }
-            finally {
-                if (this._autoCompactionAbortController === abortController) {
-                    this._autoCompactionAbortController = undefined;
+            abortController = new AbortController();
+            this._autoCompactionAbortController = abortController;
+            started = true;
+            this._emit({ type: "compaction_start", reason });
+            abortController.signal.throwIfAborted();
+            const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, abortController.signal);
+            abortController.signal.throwIfAborted();
+            let extensionCompaction;
+            if (this._extensionRunner.hasHandlers("session_before_compact")) {
+                const extensionResult = (await this._extensionRunner.emit({
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
+                    customInstructions: undefined,
+                    reason,
+                    willRetry,
+                    signal: abortController.signal,
+                }));
+                if (extensionResult?.cancel) {
+                    cancelledByExtension = true;
+                    throw new Error("Compaction cancelled");
                 }
-                this._resolveIdleWaitIfIdle();
+                if (extensionResult?.compaction) {
+                    extensionCompaction = extensionResult.compaction;
+                    fromExtension = true;
+                }
+            }
+            abortController.signal.throwIfAborted();
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let usage;
+            let details;
+            if (extensionCompaction) {
+                // Extension provided compaction content
+                summary = extensionCompaction.summary;
+                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
+                tokensBefore = extensionCompaction.tokensBefore;
+                usage = extensionCompaction.usage;
+                details = extensionCompaction.details;
+            }
+            else {
+                // Shared default summary generator, also used by manual compaction.
+                const compactResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, undefined, abortController.signal, env, reason);
+                summary = compactResult.summary;
+                firstKeptEntryId = compactResult.firstKeptEntryId;
+                tokensBefore = compactResult.tokensBefore;
+                usage = compactResult.usage;
+                details = compactResult.details;
+            }
+            abortController.signal.throwIfAborted();
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
+            const newEntries = this.sessionManager.getEntries();
+            this._refreshFinalizedContext();
+            const estimatedTokensAfter = estimateMessagesTokens(this.sessionManager.buildSessionProjection().messages);
+            // Get the saved compaction entry for the extension event
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (this._extensionRunner && savedCompactionEntry) {
+                await this._extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
+                    fromExtension,
+                    reason,
+                    willRetry,
+                });
+            }
+            const result = {
+                summary,
+                firstKeptEntryId,
+                tokensBefore,
+                estimatedTokensAfter,
+                usage,
+                details,
+            };
+            this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
+            if (willRetry)
+                return true;
+            // Auto-compaction can complete while follow-up/steering/custom messages are waiting.
+            // Continue once so queued messages are delivered.
+            return this.agent.hasQueuedMessages();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "compaction failed";
+            const aborted = abortController?.signal.aborted === true || cancelledByExtension;
+            if (started) {
+                const errorMessage = aborted
+                    ? undefined
+                    : reason === "overflow"
+                        ? `Context overflow recovery failed: ${message}`
+                        : `Auto-compaction failed: ${message}`;
+                this._emit({
+                    type: "compaction_end",
+                    reason,
+                    result: undefined,
+                    aborted,
+                    willRetry: false,
+                    errorMessage,
+                });
+                await this._emitSessionCompactFailed({
+                    reason,
+                    errorMessage,
+                    aborted,
+                    willRetry: false,
+                    fromExtension,
+                });
             }
+            return false;
         }
         finally {
-            resumeBackground();
+            if (this._autoCompactionAbortController === abortController) {
+                this._autoCompactionAbortController = undefined;
+            }
+            this._resolveIdleWaitIfIdle();
         }
     }
     /**
@@ -2377,36 +2454,33 @@ export class AgentSession {
         return this.settingsManager.getCompactionEnabled();
     }
     async bindExtensions(bindings) {
-        const resumeBackground = this.pauseBackgroundNotifications();
-        try {
-            if (bindings.backgroundEnabled !== undefined) {
-                this._backgroundHost.setEnabled(bindings.backgroundEnabled);
-            }
-            if (bindings.uiContext !== undefined) {
-                this._extensionUIContext = bindings.uiContext;
-            }
-            if (bindings.mode !== undefined) {
-                this._extensionMode = bindings.mode;
-            }
-            if (bindings.commandContextActions !== undefined) {
-                this._extensionCommandContextActions = bindings.commandContextActions;
-            }
-            if (bindings.abortHandler !== undefined) {
-                this._extensionAbortHandler = bindings.abortHandler;
-            }
-            if (bindings.shutdownHandler !== undefined) {
-                this._extensionShutdownHandler = bindings.shutdownHandler;
-            }
-            if (bindings.onError !== undefined) {
-                this._extensionErrorListener = bindings.onError;
-            }
-            this._applyExtensionBindings(this._extensionRunner);
-            await this._extensionRunner.emit(this._sessionStartEvent);
-            await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
+        return this._withBackgroundPaused(() => this._bindExtensionsBody(bindings));
+    }
+    async _bindExtensionsBody(bindings) {
+        if (bindings.backgroundEnabled !== undefined) {
+            this._backgroundHost.setEnabled(bindings.backgroundEnabled);
         }
-        finally {
-            resumeBackground();
+        if (bindings.uiContext !== undefined) {
+            this._extensionUIContext = bindings.uiContext;
+        }
+        if (bindings.mode !== undefined) {
+            this._extensionMode = bindings.mode;
         }
+        if (bindings.commandContextActions !== undefined) {
+            this._extensionCommandContextActions = bindings.commandContextActions;
+        }
+        if (bindings.abortHandler !== undefined) {
+            this._extensionAbortHandler = bindings.abortHandler;
+        }
+        if (bindings.shutdownHandler !== undefined) {
+            this._extensionShutdownHandler = bindings.shutdownHandler;
+        }
+        if (bindings.onError !== undefined) {
+            this._extensionErrorListener = bindings.onError;
+        }
+        this._applyExtensionBindings(this._extensionRunner);
+        await this._extensionRunner.emit(this._sessionStartEvent);
+        await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
     }
     async extendResourcesFromExtensions(reason) {
         if (!this._extensionRunner.hasHandlers("resources_discover")) {
@@ -2698,37 +2772,34 @@ export class AgentSession {
         });
     }
     async reload(options) {
-        const resumeBackground = this.pauseBackgroundNotifications();
-        try {
-            const oldRunner = this._extensionRunner;
-            const previousFlagValues = oldRunner.getFlagValues();
-            this.background.close();
-            await Promise.all([this.background.shutdown(), this.abort()]);
-            await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
-            oldRunner.invalidate();
-            await this.settingsManager.reload();
-            this.syncQueueModesFromSettings();
-            resetApiProviders();
-            await this._resourceLoader.reload();
-            this._backgroundHost.replaceService();
-            this._buildRuntime({
-                activeToolNames: this.getActiveToolNames(),
-                flagValues: previousFlagValues,
-                includeAllExtensionTools: true,
-            });
-            const hasBindings = this.background.enabled ||
-                this._extensionUIContext ||
-                this._extensionCommandContextActions ||
-                this._extensionShutdownHandler ||
-                this._extensionErrorListener;
-            if (hasBindings) {
-                await options?.beforeSessionStart?.();
-                await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
-                await this.extendResourcesFromExtensions("reload");
-            }
-        }
-        finally {
-            resumeBackground();
+        return this._withBackgroundPaused(() => this._reloadBody(options));
+    }
+    async _reloadBody(options) {
+        const oldRunner = this._extensionRunner;
+        const previousFlagValues = oldRunner.getFlagValues();
+        this.background.close();
+        await Promise.all([this.background.shutdown(), this.abort()]);
+        await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
+        oldRunner.invalidate();
+        await this.settingsManager.reload();
+        this.syncQueueModesFromSettings();
+        resetApiProviders();
+        await this._resourceLoader.reload();
+        this._backgroundHost.replaceService();
+        this._buildRuntime({
+            activeToolNames: this.getActiveToolNames(),
+            flagValues: previousFlagValues,
+            includeAllExtensionTools: true,
+        });
+        const hasBindings = this.background.enabled ||
+            this._extensionUIContext ||
+            this._extensionCommandContextActions ||
+            this._extensionShutdownHandler ||
+            this._extensionErrorListener;
+        if (hasBindings) {
+            await options?.beforeSessionStart?.();
+            await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
+            await this.extendResourcesFromExtensions("reload");
         }
     }
     // =========================================================================
@@ -3272,7 +3343,7 @@ export class AgentSession {
         if (!model) {
             throw new Error("No model selected");
         }
-        const { model: requestModel, apiKey, headers, env, } = await this._getSummarizationRequestAuth(model, options.signal);
+        const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(model);
         return generateBugReportSummary({
             messages: this.messages,
             hint: options.hint,