@averyyy/pi-coding-agent 0.86.1-piclient.1 → 0.87.0-piclient.1

package/dist/core/agent-session.js

@@ -18,22 +18,24 @@ import { contentText, getCurrentSystemMessage, normalizeContext, retryDelayMs }
 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 { resolvePath } from "../utils/paths.js";
 import { sleep } from "../utils/sleep.js";
 import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.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, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { convertToLlm } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { cancelPiServerOperations, compactPiServer, } from "./pi-server-client.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
+import { CURRENT_SESSION_VERSION, 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";
@@ -208,6 +210,15 @@ export class AgentSession {
     // Extension system
     _extensionRunner;
     _turnIndex = 0;
+    _entryIdsByMessage = new WeakMap();
+    _boundaryDispatchedMessages = new WeakSet();
+    _lastAssistantMessage;
+    _lastAssistantToolResults = [];
+    _lastActivityOutcome = "completed";
+    _isBeforeSettle = false;
+    _abortDuringBeforeSettle = false;
+    _isEmittingAgentSettled = false;
+    _deferredSettledActions = [];
     _resourceLoader;
     _customTools;
     _baseToolDefinitions = new Map();
@@ -265,6 +276,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,
@@ -382,8 +395,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;
@@ -396,16 +411,112 @@ export class AgentSession {
             };
         };
     }
+    async _compactBeforeNextAssistantResponse(context, signal) {
+        if (signal?.aborted)
+            return context;
+        const model = this.model;
+        const settings = this.settingsManager.getCompactionSettings(model);
+        const projection = this.sessionManager.buildSessionProjection();
+        if (!model ||
+            model.contextWindow <= 0 ||
+            !shouldCompact(estimateProjectedContextTokens(projection, this.sessionManager.getBranch()).tokens, model.contextWindow, settings)) {
+            return { ...context, messages: projection.messages };
+        }
+        await this._runAutoCompaction("threshold", false, undefined, undefined, signal);
+        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() {
         const previousPrepareNextTurnWithContext = this.agent.prepareNextTurnWithContext ??
             (this.agent.prepareNextTurn
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
-            const compactedContext = await this._compactBeforeNextProviderRequest(turn, signal);
-            const nextTurn = compactedContext ? { ...turn, context: compactedContext } : turn;
+            const projectedTurn = {
+                ...turn,
+                context: {
+                    ...turn.context,
+                    messages: this.sessionManager.buildSessionProjection().messages,
+                },
+            };
+            const compactedContext = await this._compactBeforeNextProviderRequest(projectedTurn, signal);
+            const context = signal?.aborted
+                ? projectedTurn.context
+                : compactedContext === undefined
+                    ? await this._compactBeforeNextAssistantResponse(projectedTurn.context, signal)
+                    : (compactedContext ?? projectedTurn.context);
+            const nextTurn = { ...turn, context };
             const previousSnapshot = await previousPrepareNextTurnWithContext?.(nextTurn, signal);
-            const nextContext = previousSnapshot?.context ?? nextTurn.context;
+            const nextContext = previousSnapshot?.context ?? context;
             const runOptions = this._runSystemPromptOptions ?? this._baseSystemPromptOptions;
             const options = normalizeBuildSystemPromptOptions({
                 ...runOptions,
@@ -433,6 +544,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) {
@@ -471,16 +660,27 @@ export class AgentSession {
     async _emitAgentSettled() {
         this._cacheWarmer?.onAgentSettled();
         this._isAgentRunActive = false;
+        this._isEmittingAgentSettled = true;
         try {
             await this._extensionRunner.emit({ type: "agent_settled" });
             this._emit({ type: "agent_settled" });
         }
         finally {
-            this._resolveIdleWaitIfIdle();
+            this._isEmittingAgentSettled = false;
+        }
+        const deferred = this._deferredSettledActions.splice(0);
+        if (deferred.length > 0) {
+            try {
+                for (const action of deferred)
+                    await action();
+            }
+            finally {
+                this._resolveIdleWaitIfIdle();
+            }
+            return;
         }
+        this._resolveIdleWaitIfIdle();
     }
-    // Track last assistant message for auto-compaction check
-    _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     _handleAgentEvent = async (event, _signal) => {
         // When a user message starts, check if it's from either queue and remove it BEFORE emitting
@@ -505,29 +705,30 @@ 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") {
+            let entryId;
             // Check if this is a custom message from extensions
             if (event.message.role === "custom") {
                 // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                entryId = this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
             }
             else if (event.message.role === "system" ||
                 event.message.role === "user" ||
                 event.message.role === "assistant" ||
                 event.message.role === "toolResult") {
                 // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
+                entryId = this.sessionManager.appendMessage(event.message);
             }
+            if (entryId)
+                this._entryIdsByMessage.set(event.message, entryId);
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // 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 (!this._isTerminalAssistantFailure(assistantMsg)) {
                     this._overflowRecoveryAttempted = false;
                 }
@@ -549,6 +750,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();
         }
     };
@@ -567,6 +769,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;
@@ -612,14 +855,42 @@ export class AgentSession {
         if (!this._isTerminalAssistantFailure(assistant)) {
             return;
         }
-        if (terminalMessageEntry.parentId) {
-            this.sessionManager.branch(terminalMessageEntry.parentId);
+        const terminalIndex = branch.findIndex((entry) => entry.id === terminalMessageEntry?.id);
+        const trailingEntries = terminalIndex >= 0 ? branch.slice(terminalIndex + 1) : [];
+        const trailingOmissionOnly = trailingEntries.every((entry) => entry.type === "context_edit" && entry.targetId === terminalMessageEntry?.id && entry.replacement === null);
+        if (trailingEntries.length === 0 || trailingOmissionOnly) {
+            // With no later durable metadata, moving the active leaf keeps the old
+            // failure out of the active branch while retaining it in full history.
+            if (terminalMessageEntry.parentId) {
+                this.sessionManager.branch(terminalMessageEntry.parentId);
+            }
+            else {
+                this.sessionManager.resetLeaf();
+            }
+            this._refreshFinalizedContext();
+            return;
         }
-        else {
-            this.sessionManager.resetLeaf();
+        // Preserve metadata after the failed attempt. The canonical projection can
+        // omit the attempt through an append-only edit; rewinding the raw leaf would
+        // also discard usage, boundary, or replacement entries persisted after it.
+        const projection = this.sessionManager.buildSessionProjection();
+        const projectedEntry = projection.entries.find((entry) => entry.sourceEntry.id === terminalMessageEntry.id);
+        if (!projectedEntry ||
+            !projectedEntry.messages.some((message) => message.role === "assistant" && this._isTerminalAssistantFailure(message))) {
+            this._refreshFinalizedContext();
+            return;
         }
-        const sessionContext = this.sessionManager.buildSessionContext();
-        this.agent.state.messages = sessionContext.messages;
+        let latestEdit;
+        for (let index = branch.length - 1; index >= 0; index--) {
+            const entry = branch[index];
+            if (entry.type === "context_edit" && entry.targetId === terminalMessageEntry.id) {
+                latestEdit = entry;
+                break;
+            }
+        }
+        if (latestEdit?.replacement !== null)
+            this.sessionManager.appendContextEdit(terminalMessageEntry.id, null);
+        this._refreshFinalizedContext();
     }
     _detachPiServerTerminalAssistantFailure() {
         this._detachTerminalAssistantFailure();
@@ -666,13 +937,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") {
@@ -788,6 +1055,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;
@@ -1030,12 +1301,14 @@ export class AgentSession {
         this._isAgentRunActive = true;
         try {
             await start();
-            while (await this._handlePostAgentRun()) {
-                // Esc cancels the current agent run. Keep messages queued during that
-                // cancellation for the single deferred continuation in abort().
-                if (this._isAborting || this._agentRunAbortRequested) {
-                    break;
+            while (!this._agentRunAbortRequested) {
+                const shouldContinue = await this._handlePostAgentRun();
+                if (!shouldContinue) {
+                    if (this._isAborting || this._agentRunAbortRequested || !(await this._runBeforeSettleBoundary()))
+                        break;
                 }
+                if (this._isAborting || this._agentRunAbortRequested)
+                    break;
                 try {
                     await this.agent.continue();
                 }
@@ -1141,22 +1414,23 @@ 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 (!message)
+            return this.agent.hasQueuedMessages();
         if (this._isAborting) {
-            if (isPiServerMode() && this._isTerminalAssistantFailure(msg)) {
+            if (isPiServerMode() && this._isTerminalAssistantFailure(message)) {
                 this._detachPiServerTerminalAssistantFailure();
             }
             return false;
         }
-        if (this._isRetryableError(msg) && (await this._prepareRetry(msg))) {
+        if (this._isRetryableError(message) && (await this._prepareRetry(message))) {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
             return !this._agentRunAbortRequested;
@@ -1168,25 +1442,49 @@ export class AgentSession {
         if (this._isAborting) {
             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;
         }
-        if (isPiServerMode() && this._isTerminalAssistantFailure(msg)) {
+        if (isPiServerMode() && this._isTerminalAssistantFailure(message)) {
             this._detachPiServerTerminalAssistantFailure();
         }
         // The agent loop drains both queues before emitting agent_end. Any messages
         // here were queued by agent_end extension handlers and need a continuation.
         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 };
@@ -1200,6 +1498,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
@@ -1210,6 +1527,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;
+        }
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let messages;
@@ -1288,7 +1609,7 @@ export class AgentSession {
                 this._prePromptAbortController = prePromptAbortController;
                 this._prePromptCompletionPromise = prePromptCompletion;
                 try {
-                    await this._checkCompaction(lastAssistant, false, prePromptAbortController.signal);
+                    await this._checkCompaction(lastAssistant, false, [], prePromptAbortController.signal);
                 }
                 finally {
                     if (this._prePromptAbortController === prePromptAbortController) {
@@ -1307,13 +1628,23 @@ export class AgentSession {
             if (isPiServerMode()) {
                 this._detachPiServerTerminalAssistantFailure();
             }
-            // Build messages array (custom message if any, then user message)
+            // 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 = [];
-            // Add user message
-            const userContent = [{ type: "text", text: expandedText }];
-            if (currentImages) {
-                userContent.push(...currentImages);
-            }
+            const userContent = [{ type: "text", text: userText }];
+            userContent.push(...normalized.images);
             messages.push({
                 role: "user",
                 content: userContent,
@@ -1324,16 +1655,6 @@ export class AgentSession {
                 messages.push(msg);
             }
             this._pendingNextTurnMessages = [];
-            // Emit before_agent_start extension event
-            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();
             for (const msg of result.messages) {
                 messages.push({
                     role: "custom",
@@ -1546,6 +1867,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) {
@@ -1560,8 +1885,8 @@ export class AgentSession {
         }
     }
     _appendCustomMessage(appMessage) {
-        this.agent.state.messages.push(appMessage);
         this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._refreshFinalizedContext();
         this._emit({ type: "message_start", message: appMessage });
         this._emit({ type: "message_end", message: appMessage });
     }
@@ -1666,6 +1991,8 @@ export class AgentSession {
         this.abortBash();
         this._prePromptAbortController?.abort();
         this._sessionNameAbortController?.abort();
+        if (this._isBeforeSettle)
+            this._abortDuringBeforeSettle = true;
         this.agent.abort();
         // _runAgentOperation owns the settled event and the idle waiter. Do not
         // start a queued continuation until that cleanup has completed.
@@ -2094,9 +2421,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) {
@@ -2186,7 +2512,7 @@ export class AgentSession {
      * @param assistantMessage The assistant message to check
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true, externalSignal) {
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true, toolResults = [], externalSignal) {
         if (externalSignal?.aborted)
             return false;
         const settings = this.settingsManager.getCompactionSettings(this.model);
@@ -2214,16 +2540,31 @@ export class AgentSession {
         // Case 1: Recoverable failure. Explicit/silent context overflow still uses context metadata.
         // 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.
-        // A successful response over the configured window should compact but must not retry: the
-        // assistant answer already completed and agent.continue() cannot continue from an assistant.
-        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";
             if (!willRetry) {
-                return externalSignal
-                    ? await this._runAutoCompaction("overflow", false, undefined, undefined, externalSignal)
-                    : await this._runAutoCompaction("overflow", false);
+                return await this._runAutoCompaction("overflow", false, undefined, undefined, externalSignal);
             }
             if (this._overflowRecoveryAttempted) {
                 const errorMessage = contextOverflow
@@ -2239,30 +2580,25 @@ export class AgentSession {
                 });
                 return false;
             }
+            // Persistently omit the selected final attempt before post-run recovery compaction.
             this._overflowRecoveryAttempted = true;
-            const terminalFailurePreparation = this._isTerminalAssistantFailure(assistantMessage)
-                ? prepareCompaction(this.sessionManager.getBranch(), settings)
-                : undefined;
-            // Remove the error message from agent state (it IS saved to session for history,
-            // but we don't want it in context for the retry)
-            if (this._isTerminalAssistantFailure(assistantMessage)) {
-                this._detachTerminalAssistantFailure();
-            }
-            else {
-                const messages = this.agent.state.messages;
-                if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-                    this.agent.state.messages = messages.slice(0, -1);
-                }
-            }
-            return await this._runAutoCompaction("overflow", willRetry, terminalFailurePreparation, undefined, externalSignal);
+            this._omitRecoveryAttempt(assistantMessage, toolResults);
+            if (isPiServerMode())
+                this._detachPiServerTerminalAssistantFailure();
+            return await this._runAutoCompaction("overflow", willRetry, undefined, undefined, externalSignal);
         }
         // Case 2: Threshold - context is getting large
         // For error messages or all-zero usage messages, estimate from the last valid response.
         // 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);
             // When a valid usage entry exists, verify it is post-compaction. Kept
@@ -2410,9 +2746,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);
             const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
             if (this._extensionRunner && savedCompactionEntry) {
                 await this._extensionRunner.emit({
@@ -2494,7 +2829,38 @@ export class AgentSession {
         const contextWindow = this.model?.contextWindow ?? 0;
         if (contextWindow <= 0)
             return false;
-        const projectedTokens = estimateContextTokens(turn.context.messages).tokens;
+        const branch = this.sessionManager.getBranch();
+        const projection = this.sessionManager.buildSessionProjection();
+        const toolResultEntryIndexes = turn.toolResults
+            .map((message) => this._findPersistedMessageEntryId(message))
+            .flatMap((id) => {
+            const index = id ? branch.findIndex((entry) => entry.id === id) : -1;
+            return index >= 0 ? [index] : [];
+        });
+        const lastToolResultIndex = Math.max(...toolResultEntryIndexes, -1);
+        if (lastToolResultIndex >= 0) {
+            for (const entry of branch.slice(lastToolResultIndex + 1)) {
+                if (entry.type === "custom_message")
+                    return false;
+                if (entry.type === "message" &&
+                    (entry.message.role === "user" ||
+                        entry.message.role === "custom" ||
+                        entry.message.role === "bashExecution")) {
+                    return false;
+                }
+                if (entry.type === "context_edit" && entry.replacement !== null) {
+                    const target = branch.find((candidate) => candidate.id === entry.targetId);
+                    if (target?.type === "custom_message" ||
+                        (target?.type === "message" &&
+                            (target.message.role === "user" ||
+                                target.message.role === "custom" ||
+                                target.message.role === "bashExecution"))) {
+                        return false;
+                    }
+                }
+            }
+        }
+        const projectedTokens = estimateProjectedContextTokens(projection, branch).tokens;
         return projectedTokens >= contextWindow - settings.reserveTokens;
     }
     _appendIntraTurnCompactionMarker() {
@@ -2530,13 +2896,13 @@ export class AgentSession {
         const preparation = prepareCompaction(branchWithMarker, settings, preparationOptions);
         if (!preparation) {
             this._restoreSessionLeaf(markerParentId);
-            return undefined;
+            return null;
         }
-        await this._runAutoCompaction("threshold", false, preparation, preparationOptions);
+        await this._runAutoCompaction("threshold", false, preparation, preparationOptions, signal);
         const currentCompactionId = getLatestCompactionEntry(this.sessionManager.getBranch())?.id;
         if (currentCompactionId === previousCompactionId) {
             this._restoreSessionLeaf(markerParentId);
-            return undefined;
+            return null;
         }
         return this._currentAgentContext(turn.context);
     }
@@ -2964,28 +3330,10 @@ export class AgentSession {
             delayMs,
             errorMessage: message.errorMessage || "Unknown error",
         });
-        if (isPiServerMode()) {
+        // Keep the failed attempt in raw history while durably omitting it from model projection.
+        this._omitRecoveryAttempt(message);
+        if (isPiServerMode())
             this._detachPiServerTerminalAssistantFailure();
-        }
-        else {
-            // 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);
-            }
-        }
-        const lastMessage = this.agent.state.messages[this.agent.state.messages.length - 1];
-        if (!lastMessage || lastMessage.role === "assistant") {
-            const attempt = this._retryAttempt;
-            this._retryAttempt = 0;
-            this._emit({
-                type: "auto_retry_end",
-                success: false,
-                attempt,
-                finalError: lastMessage ? "Cannot continue from message role: assistant" : "No messages to continue from",
-            });
-            return false;
-        }
         // Wait with exponential backoff (abortable)
         this._retryAbortController = new AbortController();
         try {
@@ -3084,10 +3432,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();
         }
     }
     /**
@@ -3114,12 +3460,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
@@ -3298,9 +3642,8 @@ export class AgentSession {
             if (label && !summaryText) {
                 this.sessionManager.appendLabelChange(targetId, label);
             }
-            // 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({
@@ -3410,30 +3753,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,