@astralyn/pi 0.86.0 → 0.87.0

package/dist/core/agent-session.js

@@ -18,23 +18,25 @@ import { contentText, getCurrentSystemMessage, getSystemMessageText, retryDelayM
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
+import { processImage } from "../utils/image-process.js";
 import { sleep } from "../utils/sleep.js";
 import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { BackgroundSession } from "./background/session.js";
 import { executeBashWithOperations } from "./bash-executor.js";
 import { generateBugReportSummary } from "./bug-report.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, STALE_EXTENSION_CONTEXT_MESSAGE, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { convertToLlm } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { resolveModelStreamOptions } from "./model-stream-options.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { exportSessionToJsonl } from "./session-export.js";
-import { getLatestCompactionEntry } from "./session-manager.js";
+import { getLatestCompactionEntry, SessionManager, } from "./session-manager.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt, buildSystemPromptSections, diffSystemPromptSections, normalizeBuildSystemPromptOptions, } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
@@ -100,6 +102,14 @@ export class AgentSession {
         this._bashAbortControllers = new Set();
         this._pendingBashMessages = [];
         this._turnIndex = 0;
+        this._entryIdsByMessage = new WeakMap();
+        this._boundaryDispatchedMessages = new WeakSet();
+        this._lastAssistantToolResults = [];
+        this._lastActivityOutcome = "completed";
+        this._isBeforeSettle = false;
+        this._abortDuringBeforeSettle = false;
+        this._isEmittingAgentSettled = false;
+        this._deferredSettledActions = [];
         this._baseToolDefinitions = new Map();
         this._extensionMode = "print";
         // Tool registry for extension getTools/setTools
@@ -107,8 +117,6 @@ export class AgentSession {
         this._toolDefinitions = new Map();
         this._toolPromptSnippets = new Map();
         this._toolPromptGuidelines = new Map();
-        // Track last assistant message for auto-compaction check
-        this._lastAssistantMessage = undefined;
         /** Internal handler for agent events - shared by subscribe and reconnect */
         this._handleAgentEvent = async (event) => {
             // Preserve host delivery identity before extension message_end transforms.
@@ -136,18 +144,16 @@ export class AgentSession {
                     }
                 }
             }
-            // Emit to extensions first
+            // Emit to extensions first, then notify public listeners.
             await this._emitExtensionEvent(event);
-            // Notify all listeners
             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))
                     acknowledgeBackground?.();
-                // Track assistant message for auto-compaction (checked on agent_end)
                 if (event.message.role === "assistant") {
-                    this._lastAssistantMessage = event.message;
                     const assistantMsg = event.message;
+                    this._lastAssistantMessage = assistantMsg;
                     if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "length") {
                         this._overflowRecoveryAttempted = false;
                     }
@@ -169,6 +175,7 @@ export class AgentSession {
             // extension and listener dispatch above also picks up messages that turn_end
             // handlers queued.
             if (event.type === "turn_end") {
+                this._lastAssistantToolResults = event.toolResults;
                 this._flushPendingCustomMessages();
             }
         };
@@ -212,6 +219,8 @@ export class AgentSession {
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
         this._installAgentNextTurnRefresh();
+        this._installAgentRequestProjection();
+        this._installAgentBoundaryHooks();
         this._installAgentForcedPromptProjection();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
@@ -264,7 +273,8 @@ export class AgentSession {
             }),
         };
         const currentSystemPrompt = this.systemPrompt;
-        const messages = structuredClone(this.agent.state.messages);
+        // The canonical projection is what the next request converts; the inspection cache may lag it.
+        const messages = structuredClone(this.sessionManager.buildSessionProjection().messages);
         const convert = this.agent.convertToLlm;
         const transform = this.agent.transformContext;
         const prepared = this._captureModelContext
@@ -375,8 +385,10 @@ export class AgentSession {
                 : undefined;
             const content = hookResult?.content ?? result.content ?? [];
             // Runs after the extension hook so images injected or replaced by extensions are normalized too.
+            const resizeOptions = this.model?.inputLimits?.images?.resize;
             const normalizedContent = await normalizeToolResultImages(content, {
                 autoResizeImages: this.settingsManager.getImageAutoResize(),
+                ...(resizeOptions ? { resizeOptions } : {}),
             });
             if (!hookResult && normalizedContent === content) {
                 return undefined;
@@ -392,15 +404,83 @@ export class AgentSession {
     async _compactBeforeNextAssistantResponse(context) {
         const model = this.model;
         const settings = this.settingsManager.getCompactionSettings(model);
+        const projection = this.sessionManager.buildSessionProjection();
         if (!model ||
             model.contextWindow <= 0 ||
-            !shouldCompact(estimateContextTokens(context.messages).tokens, model.contextWindow, settings)) {
-            return context;
+            !shouldCompact(estimateProjectedContextTokens(projection, this.sessionManager.getBranch()).tokens, model.contextWindow, settings)) {
+            return { ...context, messages: projection.messages };
         }
         await this._runAutoCompaction("threshold", false);
-        return {
-            ...context,
-            messages: this.agent.state.messages.slice(),
+        return { ...context, messages: this.sessionManager.buildSessionProjection().messages };
+    }
+    _installAgentRequestProjection() {
+        const previousPrepareRequest = this.agent.prepareRequest;
+        this.agent.prepareRequest = async (request, signal) => {
+            const canonicalContext = {
+                ...request.context,
+                messages: this.sessionManager.buildSessionProjection().messages,
+                // Messages declare the provider-visible loadout; context.tools keeps executable implementations.
+                tools: this.agent.state.tools.slice(),
+            };
+            const previous = await previousPrepareRequest?.({
+                ...request,
+                context: canonicalContext,
+                model: this.agent.state.model,
+                thinkingLevel: this.agent.state.thinkingLevel,
+            }, signal);
+            return {
+                ...previous,
+                context: previous?.context ?? canonicalContext,
+                model: previous?.model ?? this.agent.state.model,
+                thinkingLevel: previous?.thinkingLevel ?? this.agent.state.thinkingLevel,
+            };
+        };
+    }
+    async _dispatchTurnEndBoundary(message, toolResults) {
+        this._lastActivityOutcome =
+            message.stopReason === "aborted" ? "aborted" : message.stopReason === "error" ? "error" : "completed";
+        const messageEntryId = this._findPersistedMessageEntryId(message);
+        if (!this._extensionRunner.hasHandlers("turn_end"))
+            return false;
+        if (!messageEntryId) {
+            this._extensionRunner.emitError({
+                extensionPath: "<boundary>",
+                event: "turn_end",
+                error: "turn_end could not resolve the persisted assistant entry ID",
+            });
+            return false;
+        }
+        const toolResultEntryIds = toolResults.flatMap((result) => {
+            const entryId = this._findPersistedMessageEntryId(result);
+            return entryId ? [entryId] : [];
+        });
+        const boundary = await this._extensionRunner.emitBoundary({
+            type: "turn_end",
+            turnIndex: this._turnIndex,
+            message,
+            toolResults,
+            messageEntryId,
+            toolResultEntryIds,
+            outcome: this._lastActivityOutcome,
+        }, (entries) => this._buildBoundaryContext(entries, "turn_end"));
+        this._commitBoundaryDrafts(boundary.entries);
+        if (boundary.continue && !this._buildBoundaryContext([], "turn_end").canContinue) {
+            this._reportInvalidBoundaryContinuation("turn_end");
+            return false;
+        }
+        return boundary.continue;
+    }
+    _installAgentBoundaryHooks() {
+        const previousFinishTurn = this.agent.finishTurn;
+        this.agent.finishTurn = async (turn, signal) => {
+            this._boundaryDispatchedMessages.add(turn.message);
+            const extensionContinue = await this._dispatchTurnEndBoundary(turn.message, turn.toolResults);
+            const previousDecision = await previousFinishTurn?.(turn, signal);
+            if (previousDecision?.action === "end")
+                return previousDecision;
+            if (extensionContinue || previousDecision?.action === "continue")
+                return { action: "continue" };
+            return undefined;
         };
     }
     _installAgentNextTurnRefresh() {
@@ -409,7 +489,10 @@ export class AgentSession {
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
-            const context = await this._compactBeforeNextAssistantResponse(turn.context);
+            const context = await this._compactBeforeNextAssistantResponse({
+                ...turn.context,
+                messages: this.sessionManager.buildSessionProjection().messages,
+            });
             const previousSnapshot = await previousPrepareNextTurnWithContext?.({ ...turn, context }, signal);
             const nextContext = previousSnapshot?.context ?? context;
             const runOptions = this._runSystemPromptOptions ?? this._baseSystemPromptOptions;
@@ -439,6 +522,84 @@ export class AgentSession {
     // =========================================================================
     // Event Subscription
     // =========================================================================
+    _refreshFinalizedContext() {
+        const projection = this.sessionManager.buildSessionProjection();
+        for (const entry of projection.entries) {
+            for (const message of entry.messages)
+                this._entryIdsByMessage.set(message, entry.sourceEntry.id);
+        }
+        this.agent.state.messages = projection.messages;
+    }
+    _applyBoundaryDrafts(manager, drafts) {
+        const appended = [];
+        for (const draft of drafts) {
+            let entryId;
+            switch (draft.type) {
+                case "custom":
+                    entryId = manager.appendCustomEntry(draft.customType, draft.data);
+                    break;
+                case "custom_message":
+                    entryId = manager.appendCustomMessageEntry(draft.customType, draft.content, draft.display, draft.details);
+                    break;
+                case "context_edit":
+                    entryId = manager.appendContextEdit(draft.targetId, draft.replacement);
+                    break;
+                case "compaction": {
+                    const tokensBefore = estimateProjectedContextTokens(manager.buildSessionProjection(), manager.getBranch()).tokens;
+                    entryId = manager.appendCompaction(draft.summary, draft.firstKeptEntryId, tokensBefore, draft.details, true, draft.usage);
+                    break;
+                }
+            }
+            const entry = manager.getEntry(entryId);
+            if (entry)
+                appended.push(entry);
+        }
+        return appended;
+    }
+    _createBoundaryPreviewManager(drafts) {
+        const header = this.sessionManager.getHeader();
+        if (!header)
+            throw new Error("Session header is missing");
+        const manager = SessionManager.inMemory(this._cwd, undefined, [header, ...this.sessionManager.getBranch()]);
+        this._applyBoundaryDrafts(manager, drafts);
+        return manager;
+    }
+    _getPendingBoundaryMessages() {
+        return [...this.agent.peekQueuedMessages(), ...this._pendingCustomMessages];
+    }
+    _buildBoundaryContext(drafts, boundary) {
+        const projection = this._createBoundaryPreviewManager(drafts).buildSessionProjection();
+        const pendingMessages = this._getPendingBoundaryMessages();
+        const llmMessages = convertToLlm(projection.messages);
+        const finalRole = llmMessages[llmMessages.length - 1]?.role;
+        const hasNonSystemContext = llmMessages.some((message) => message.role !== "system");
+        const contextCanContinue = hasNonSystemContext && finalRole !== "assistant";
+        const pendingCustomContext = this._pendingCustomMessages.length > 0;
+        return {
+            contextEntries: projection.entries,
+            contextMessages: projection.messages,
+            llmMessages,
+            pendingMessages,
+            canContinue: contextCanContinue ||
+                pendingCustomContext ||
+                (boundary === "turn_end"
+                    ? this.agent.hasQueuedMessages()
+                    : finalRole === "assistant" && this.agent.hasQueuedMessages()),
+        };
+    }
+    _commitBoundaryDrafts(drafts) {
+        const appended = this._applyBoundaryDrafts(this.sessionManager, drafts);
+        this._refreshFinalizedContext();
+        for (const entry of appended)
+            this._emit({ type: "entry_appended", entry });
+    }
+    _reportInvalidBoundaryContinuation(event) {
+        this._extensionRunner.emitError({
+            extensionPath: "<boundary>",
+            event,
+            error: `${event} requested continuation without runnable model context`,
+        });
+    }
     /** Emit an event to all listeners */
     _emit(event) {
         for (const l of this._eventListeners) {
@@ -476,21 +637,35 @@ export class AgentSession {
     }
     async _emitAgentSettled() {
         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;
         try {
-            await this._extensionRunner.emit({ type: "agent_settled" });
-            this._emit({ type: "agent_settled" });
+            this._isEmittingAgentSettled = true;
+            try {
+                await this._extensionRunner.emit({ type: "agent_settled" });
+                this._emit({ type: "agent_settled" });
+            }
+            finally {
+                this._isEmittingAgentSettled = false;
+            }
+            for (const action of this._deferredSettledActions.splice(0))
+                await action();
         }
         finally {
             this._resolveIdleWaitIfIdle();
             resumeBackground();
         }
     }
-    /** Persist model/custom messages and consume queued context only after the append succeeds. */
+    /**
+     * Persist model/custom messages and consume queued context only after the append succeeds.
+     * Returns the persisted entry ID, which boundary events and recovery omissions resolve later.
+     */
     _persistMessage(message) {
+        let entryId;
         if (message.role === "custom") {
-            this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+            entryId = this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
             const pendingIndex = this._pendingNextTurnMessages.indexOf(message);
             if (pendingIndex !== -1)
                 this._pendingNextTurnMessages.splice(pendingIndex, 1);
@@ -499,15 +674,16 @@ export class AgentSession {
             message.role === "user" ||
             message.role === "assistant" ||
             message.role === "toolResult") {
-            this.sessionManager.appendMessage(message);
+            entryId = this.sessionManager.appendMessage(message);
         }
         else {
             // Bash execution, compaction and branch summaries are persisted by their owners.
-            return false;
+            return undefined;
         }
+        this._entryIdsByMessage.set(message, entryId);
         if (message.role === "toolResult")
             this._backgroundHost.acknowledgeWaitResult(message.details);
-        return true;
+        return entryId;
     }
     _willRetryAfterAgentEnd(event) {
         if (this._agentRunAbortRequested)
@@ -524,6 +700,47 @@ export class AgentSession {
         }
         return false;
     }
+    _findPersistedMessageEntryId(message) {
+        const mapped = this._entryIdsByMessage.get(message);
+        if (mapped)
+            return mapped;
+        for (const entry of [...this.sessionManager.getBranch()].reverse()) {
+            if (entry.type === "message" && entry.message === message)
+                return entry.id;
+        }
+        const messageIndex = this.agent.state.messages.indexOf(message);
+        if (messageIndex < 0)
+            return undefined;
+        const projection = this.sessionManager.buildSessionProjection();
+        let projectedIndex = 0;
+        for (const entry of projection.entries) {
+            for (let i = 0; i < entry.messages.length; i++) {
+                if (projectedIndex === messageIndex) {
+                    this._entryIdsByMessage.set(message, entry.sourceEntry.id);
+                    return entry.sourceEntry.id;
+                }
+                projectedIndex++;
+            }
+        }
+        return undefined;
+    }
+    _omitRecoveryAttempt(message, toolResults = []) {
+        const targets = [message, ...toolResults];
+        const targetIds = targets.map((target) => this._findPersistedMessageEntryId(target));
+        const unresolvedProjectedTarget = targets.some((target, index) => targetIds[index] === undefined && this.agent.state.messages.includes(target));
+        if (unresolvedProjectedTarget) {
+            throw new Error("Cannot persist recovery omission because a projected message has no source entry");
+        }
+        for (const targetId of targetIds) {
+            if (!targetId)
+                continue;
+            const editId = this.sessionManager.appendContextEdit(targetId, null);
+            const entry = this.sessionManager.getEntry(editId);
+            if (entry)
+                this._emit({ type: "entry_appended", entry });
+        }
+        this._refreshFinalizedContext();
+    }
     /** Find the last assistant message in agent state (including aborted ones) */
     _findLastAssistantMessage() {
         const messages = this.agent.state.messages;
@@ -567,13 +784,9 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
         else if (event.type === "turn_end") {
-            const extensionEvent = {
-                type: "turn_end",
-                turnIndex: this._turnIndex,
-                message: event.message,
-                toolResults: event.toolResults,
-            };
-            await this._extensionRunner.emit(extensionEvent);
+            if (event.message.role === "assistant" && !this._boundaryDispatchedMessages.delete(event.message)) {
+                await this._dispatchTurnEndBoundary(event.message, event.toolResults);
+            }
             this._turnIndex++;
         }
         else if (event.type === "message_start") {
@@ -690,6 +903,10 @@ export class AgentSession {
     // =========================================================================
     // Read-only State Access
     // =========================================================================
+    /** Refresh the public finalized transcript from the canonical session projection. */
+    refreshContext() {
+        this._refreshFinalizedContext();
+    }
     /** Full agent state */
     get state() {
         return this.agent.state;
@@ -924,7 +1141,15 @@ export class AgentSession {
         this._isAgentRunActive = true;
         try {
             await this.agent.prompt(messages);
-            while (await this._handlePostAgentRun()) {
+            while (!this._agentRunAbortRequested) {
+                if (await this._handlePostAgentRun()) {
+                    if (this._agentRunAbortRequested)
+                        break;
+                    await this.agent.continue();
+                    continue;
+                }
+                if (this._agentRunAbortRequested || !(await this._runBeforeSettleBoundary()))
+                    break;
                 if (this._agentRunAbortRequested)
                     break;
                 await this.agent.continue();
@@ -940,16 +1165,17 @@ export class AgentSession {
         }
     }
     async _handlePostAgentRun() {
-        const msg = this._lastAssistantMessage;
+        const message = this._lastAssistantMessage;
+        const toolResults = this._lastAssistantToolResults;
         this._lastAssistantMessage = undefined;
+        this._lastAssistantToolResults = [];
         if (this._agentRunAbortRequested) {
             this._finishCancelledRetry();
             return false;
         }
-        if (!msg) {
-            return false;
-        }
-        if (this._isRetryableError(msg) && (await this._prepareRetry(msg))) {
+        if (!message)
+            return this.agent.hasQueuedMessages();
+        if (this._isRetryableError(message) && (await this._prepareRetry(message))) {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
             return !this._agentRunAbortRequested;
@@ -958,22 +1184,46 @@ export class AgentSession {
             this._finishCancelledRetry();
             return false;
         }
-        if (msg.stopReason === "error" && this._retryAttempt > 0) {
+        if (message.stopReason === "error" && this._retryAttempt > 0) {
             this._emit({
                 type: "auto_retry_end",
                 success: false,
                 attempt: this._retryAttempt,
-                finalError: msg.errorMessage,
+                finalError: message.errorMessage,
             });
             this._retryAttempt = 0;
         }
-        if (await this._checkCompaction(msg)) {
+        if (await this._checkCompaction(message, true, toolResults)) {
             return !this._agentRunAbortRequested;
         }
-        // The agent loop drains both queues before emitting agent_end. Any messages
-        // here were queued by agent_end extension handlers and need a continuation.
+        // The low-level loop drains both queues before agent_end. Messages queued by
+        // agent_end handlers require a fresh run before pre-settlement handlers fire.
         return !this._agentRunAbortRequested && this.agent.hasQueuedMessages();
     }
+    async _runBeforeSettleBoundary() {
+        if (!this._extensionRunner.hasHandlers("agent_before_settle"))
+            return this.agent.hasQueuedMessages();
+        this._isBeforeSettle = true;
+        this._abortDuringBeforeSettle = false;
+        try {
+            const result = await this._extensionRunner.emitBoundary({ type: "agent_before_settle", outcome: this._lastActivityOutcome }, (entries) => this._buildBoundaryContext(entries, "agent_before_settle"));
+            this._commitBoundaryDrafts(result.entries);
+            this._flushPendingCustomMessages();
+            const finalContext = this._buildBoundaryContext([], "agent_before_settle");
+            if (this._abortDuringBeforeSettle)
+                return false;
+            const shouldContinue = result.continue || this.agent.hasQueuedMessages();
+            if (shouldContinue && !finalContext.canContinue) {
+                if (result.continue)
+                    this._reportInvalidBoundaryContinuation("agent_before_settle");
+                return false;
+            }
+            return shouldContinue;
+        }
+        finally {
+            this._isBeforeSettle = false;
+        }
+    }
     async _runInputHandlers(text, images, source, streamingBehavior) {
         if (!this._extensionRunner.hasHandlers("input")) {
             return { text, images };
@@ -987,6 +1237,25 @@ export class AgentSession {
         }
         return { text, images };
     }
+    async _normalizePromptImages(images) {
+        if (!images)
+            return { images: [], hints: [] };
+        const normalizedImages = [];
+        const hints = [];
+        for (const image of images) {
+            const processed = await processImage(Buffer.from(image.data, "base64"), image.mimeType, {
+                autoResizeImages: this.settingsManager.getImageAutoResize(),
+                resizeOptions: this.model?.inputLimits?.images?.resize,
+            });
+            if (!processed.ok) {
+                hints.push(processed.message);
+                continue;
+            }
+            normalizedImages.push({ type: "image", data: processed.data, mimeType: processed.mimeType });
+            hints.push(...processed.hints);
+        }
+        return { images: normalizedImages, hints };
+    }
     /**
      * Send a prompt to the agent.
      * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
@@ -997,6 +1266,10 @@ export class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
+        if (this._isEmittingAgentSettled) {
+            this._deferredSettledActions.push(async () => await this.prompt(text, options));
+            return;
+        }
         // A user-initiated prompt is the recovery point for failed completion deliveries.
         this.retryBackgroundNotifications();
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
@@ -1073,23 +1346,8 @@ export class AgentSession {
                 if (lastAssistant) {
                     await this._checkCompaction(lastAssistant, false);
                 }
-                // Build messages array (custom message if any, then user message)
-                messages = [];
-                // Add user message
-                const userContent = [{ type: "text", text: expandedText }];
-                if (currentImages) {
-                    userContent.push(...currentImages);
-                }
-                messages.push({
-                    role: "user",
-                    content: userContent,
-                    timestamp: Date.now(),
-                });
-                // Inject any pending "nextTurn" messages as context alongside the user message
-                for (const msg of this._pendingNextTurnMessages) {
-                    messages.push(msg);
-                }
-                // Emit before_agent_start extension event
+                // 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(),
@@ -1099,6 +1357,22 @@ export class AgentSession {
                     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: "custom",
@@ -1251,11 +1525,7 @@ export class AgentSession {
         if (images) {
             content.push(...images);
         }
-        this.agent.followUp({
-            role: "user",
-            content,
-            timestamp: Date.now(),
-        });
+        this.agent.followUp({ role: "user", content, timestamp: Date.now() });
     }
     /**
      * Throw an error if the text is an extension command.
@@ -1303,6 +1573,10 @@ export class AgentSession {
             }
         }
         else if (options?.triggerTurn) {
+            if (this._isEmittingAgentSettled) {
+                this._deferredSettledActions.push(async () => await this._runAgentPrompt(appMessage));
+                return;
+            }
             await this._runAgentPrompt(appMessage);
         }
         else if (this.isStreaming) {
@@ -1317,8 +1591,8 @@ export class AgentSession {
         }
     }
     _appendCustomMessage(appMessage) {
-        this.agent.state.messages.push(appMessage);
         this._persistMessage(appMessage);
+        this._refreshFinalizedContext();
         this._backgroundHost.messageAcknowledgement(appMessage)?.();
         this._emit({ type: "message_start", message: appMessage });
         this._emit({ type: "message_end", message: appMessage });
@@ -1412,6 +1686,8 @@ export class AgentSession {
         this.abortRetry();
         this.abortCompaction();
         this.abortBranchSummary();
+        if (this._isBeforeSettle)
+            this._abortDuringBeforeSettle = true;
         this.agent.abort();
         await this.waitForIdle();
     }
@@ -1732,9 +2008,8 @@ export class AgentSession {
                 }
                 this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
                 const newEntries = this.sessionManager.getEntries();
-                const sessionContext = this.sessionManager.buildSessionContext();
-                this.agent.state.messages = sessionContext.messages;
-                const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+                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) {
@@ -1829,7 +2104,7 @@ export class AgentSession {
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true, toolResults = []) {
         const settings = this.settingsManager.getCompactionSettings(this.model);
         if (!settings.enabled)
             return false;
@@ -1853,8 +2128,27 @@ export class AgentSession {
         // Automatic cases 1 and 2: context overflow.
         // A length stop is recoverable when output ended below the model's original desired limit,
         // independent of the configured context size or any context-clamped provider request limit.
-        const contextOverflow = sameModel && isContextOverflow(assistantMessage, contextWindow);
-        const recoverableLength = sameModel && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
+        const currentProjection = this.sessionManager.buildSessionProjection();
+        const assistantEntryId = this._findPersistedMessageEntryId(assistantMessage);
+        const assistantIsProjected = assistantEntryId === undefined ||
+            currentProjection.entries.some((entry) => entry.sourceEntry.id === assistantEntryId &&
+                entry.messages.some((message) => message.role === "assistant"));
+        const branch = this.sessionManager.getBranch();
+        const assistantIndex = assistantEntryId ? branch.findIndex((entry) => entry.id === assistantEntryId) : -1;
+        const entriesAfterAssistant = assistantIndex >= 0 ? branch.slice(assistantIndex + 1) : [];
+        const hasPostAssistantContextEdit = entriesAfterAssistant.some((entry) => entry.type === "context_edit");
+        const latestAssistantEdit = entriesAfterAssistant
+            .filter((entry) => entry.type === "context_edit" && entry.targetId === assistantEntryId)
+            .at(-1);
+        const assistantRetainedForExplicitRecovery = assistantEntryId === undefined ||
+            (!entriesAfterAssistant.some((entry) => entry.type === "compaction") &&
+                latestAssistantEdit?.replacement !== null);
+        const assistantUsageMatchesProjection = assistantIsProjected && !hasPostAssistantContextEdit;
+        const explicitOverflow = assistantMessage.stopReason === "error" && isContextOverflow(assistantMessage);
+        const contextOverflow = sameModel &&
+            ((explicitOverflow && assistantRetainedForExplicitRecovery) ||
+                (assistantUsageMatchesProjection && isContextOverflow(assistantMessage, contextWindow)));
+        const recoverableLength = sameModel && assistantIsProjected && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
         if (contextOverflow || recoverableLength) {
             const willRetry = assistantMessage.stopReason !== "stop";
             // Case 2: the response completed successfully. Compact, but do not retry because
@@ -1883,13 +2177,9 @@ export class AgentSession {
                 });
                 return false;
             }
-            // Case 1: remove the failed or truncated message from agent state, compact, and
-            // retry once. The message remains in session history but is excluded from retry context.
+            // Persistently omit the selected final attempt before post-run recovery compaction.
             this._overflowRecoveryAttempted = true;
-            const messages = this.agent.state.messages;
-            if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-                this.agent.state.messages = messages.slice(0, -1);
-            }
+            this._omitRecoveryAttempt(assistantMessage, toolResults);
             return await this._runAutoCompaction("overflow", willRetry);
         }
         // Case 3: threshold compaction without retry.
@@ -1897,8 +2187,13 @@ export class AgentSession {
         // This ensures sessions that hit persistent API errors (e.g. 529) or malformed zero-usage
         // responses can still compact and do not reset context accounting.
         let contextTokens;
+        const projection = currentProjection;
+        const hasContextEdits = projection.entries.some((entry) => entry.sourceEntry.type === "context_edit");
         const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
-        if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
+        if (hasContextEdits) {
+            contextTokens = estimateProjectedContextTokens(projection, branch).tokens;
+        }
+        else if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
             const messages = this.agent.state.messages;
             const estimate = estimateContextTokens(messages);
             // Without provider usage, estimate.tokens is the pure message-size estimate.
@@ -2005,9 +2300,8 @@ export class AgentSession {
                 abortController.signal.throwIfAborted();
                 this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
                 const newEntries = this.sessionManager.getEntries();
-                const sessionContext = this.sessionManager.buildSessionContext();
-                this.agent.state.messages = sessionContext.messages;
-                const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);
+                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) {
@@ -2028,19 +2322,8 @@ export class AgentSession {
                     details,
                 };
                 this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-                if (willRetry) {
-                    const messages = this.agent.state.messages;
-                    const lastMsg = messages[messages.length - 1];
-                    // The overflow response was persisted on message_end before _checkCompaction() removed it
-                    // from agent state. Rebuilding state from the new compaction can restore that kept entry,
-                    // leaving an assistant as the final message. agent.continue() rejects that state, so remove
-                    // the retriable error or truncated-length response again before continuing the interrupted turn.
-                    if (lastMsg?.role === "assistant" &&
-                        (lastMsg.stopReason === "error" || lastMsg.stopReason === "length")) {
-                        this.agent.state.messages = messages.slice(0, -1);
-                    }
+                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();
@@ -2524,11 +2807,8 @@ export class AgentSession {
             delayMs,
             errorMessage: message.errorMessage || "Unknown error",
         });
-        // Remove error message from agent state (keep in session for history)
-        const messages = this.agent.state.messages;
-        if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-            this.agent.state.messages = messages.slice(0, -1);
-        }
+        // Keep the failed attempt in raw history while durably omitting it from model projection.
+        this._omitRecoveryAttempt(message);
         // Wait with exponential backoff (abortable)
         this._retryAbortController = new AbortController();
         try {
@@ -2620,10 +2900,8 @@ export class AgentSession {
             this._pendingBashMessages.push(bashMessage);
         }
         else {
-            // Add to agent state immediately
-            this.agent.state.messages.push(bashMessage);
-            // Save to session
             this.sessionManager.appendMessage(bashMessage);
+            this._refreshFinalizedContext();
         }
     }
     /**
@@ -2650,12 +2928,10 @@ export class AgentSession {
         if (this._pendingBashMessages.length === 0)
             return;
         for (const bashMessage of this._pendingBashMessages) {
-            // Add to agent state
-            this.agent.state.messages.push(bashMessage);
-            // Save to session
             this.sessionManager.appendMessage(bashMessage);
         }
         this._pendingBashMessages = [];
+        this._refreshFinalizedContext();
     }
     // =========================================================================
     // Session Management
@@ -2832,9 +3108,8 @@ export class AgentSession {
                 this.sessionManager.appendLabelChange(targetId, label);
             }
             this._backgroundHost.restoreHistory();
-            // Update agent state
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
+            // Update finalized context from the canonical session projection.
+            this._refreshFinalizedContext();
             this._restoreToolsFromTranscript();
             // Emit session_tree event
             await this._extensionRunner.emit({
@@ -2934,30 +3209,24 @@ export class AgentSession {
         // After compaction, the last assistant usage reflects pre-compaction context size.
         // We can only trust usage from an assistant that responded after the latest compaction.
         // If no such assistant exists, context token count is unknown until the next LLM response.
-        const branchEntries = this.sessionManager.getBranch();
-        const latestCompaction = getLatestCompactionEntry(branchEntries);
+        const projection = this.sessionManager.buildSessionProjection();
+        const branch = this.sessionManager.getBranch();
+        const latestCompaction = getLatestCompactionEntry(branch);
         if (latestCompaction) {
-            // Check if there's a valid assistant usage after the compaction boundary
-            const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
-            let hasPostCompactionUsage = false;
-            for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
-                const entry = branchEntries[i];
-                if (entry.type === "message" && entry.message.role === "assistant") {
-                    const assistant = entry.message;
-                    if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
-                        const contextTokens = calculateContextTokens(assistant.usage);
-                        if (contextTokens > 0) {
-                            hasPostCompactionUsage = true;
-                            break;
-                        }
-                    }
-                }
-            }
-            if (!hasPostCompactionUsage) {
+            const projectedAssistants = new Set(projection.entries.flatMap((entry) => entry.messages.some((message) => message.role === "assistant" &&
+                message.stopReason !== "aborted" &&
+                message.stopReason !== "error" &&
+                calculateContextTokens(message.usage) > 0)
+                ? [entry.sourceEntry.id]
+                : []));
+            const compactionIndex = branch.findIndex((entry) => entry.id === latestCompaction.id);
+            const hasPostCompactionUsage = branch
+                .slice(compactionIndex + 1)
+                .some((entry) => projectedAssistants.has(entry.id));
+            if (!hasPostCompactionUsage)
                 return { tokens: null, contextWindow, percent: null };
-            }
         }
-        const estimate = estimateContextTokens(this.messages);
+        const estimate = estimateProjectedContextTokens(projection, branch);
         const percent = (estimate.tokens / contextWindow) * 100;
         return {
             tokens: estimate.tokens,