@astralyn/pi 0.86.1 → 0.87.1

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";
@@ -56,9 +58,6 @@ export function parseSkillBlock(text) {
         userMessage: match[4]?.trim() || undefined,
     };
 }
-// ============================================================================
-// Types
-// ============================================================================
 function withoutDeletedHeaders(headers) {
     return headers
         ? Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] !== null))
@@ -87,6 +86,8 @@ export class AgentSession {
         this._pendingNextTurnMessages = [];
         /** Context-only custom messages queued during a run, flushed once the current turn's tool results are in. */
         this._pendingCustomMessages = [];
+        /** Background completions queued for steering, awaiting the persistence that confirms delivery. */
+        this._queuedBackgroundCompletions = new Map();
         // Compaction state
         this._compactionAbortController = undefined;
         this._autoCompactionAbortController = undefined;
@@ -100,6 +101,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,13 +116,17 @@ 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.
             // Content/details may be replaced, but a persisted replacement is still an ack.
             const acknowledgeBackground = event.type === "message_end" ? this._backgroundHost.messageAcknowledgement(event.message) : undefined;
+            // A queued completion is tracked by identity too, for the same reason.
+            const queuedBackgroundCompletion = event.type === "message_start" || event.type === "message_end"
+                ? this._queuedBackgroundCompletions.get(event.message)
+                : undefined;
+            if (event.type === "message_start" && queuedBackgroundCompletion)
+                queuedBackgroundCompletion.drained = true;
             // When a user message starts, check if it's from either queue and remove it BEFORE emitting
             // This ensures the UI sees the updated queue state
             if (event.type === "message_start" && event.message.role === "user") {
@@ -136,18 +149,18 @@ 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))
+                if (this._persistMessage(event.message)) {
                     acknowledgeBackground?.();
-                // Track assistant message for auto-compaction (checked on agent_end)
+                    queuedBackgroundCompletion?.resolve();
+                }
                 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,8 +182,11 @@ 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();
             }
+            if (event.type === "agent_end")
+                this._failDrainedBackgroundCompletions();
         };
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
@@ -178,16 +194,15 @@ export class AgentSession {
         this._backgroundHost = new BackgroundSession({
             manager: this.sessionManager,
             role: config.executionRole ?? "main",
-            canDeliver: () => this.isIdle &&
-                !this.agent.state.isStreaming &&
-                this.pendingMessageCount === 0 &&
-                !this.agent.hasQueuedMessages() &&
-                this.model !== undefined,
-            deliver: (message) => {
-                // Completion turns skip before_agent_start, but consume nextTurn context.
-                const asides = this._pendingNextTurnMessages.slice();
-                return this._runAgentPrompt(asides.length ? [message, ...asides] : message);
+            canDeliver: () => {
+                if (this.model === undefined || this.isCompacting)
+                    return false;
+                // A completion steered into an active run follows the interactive steering queue, which
+                // already preserves the order of queued user input. An idle delivery starts its own
+                // turn, so it still waits for the queues to drain.
+                return this.isStreaming || (this.pendingMessageCount === 0 && !this.agent.hasQueuedMessages());
             },
+            deliver: (message) => this._deliverBackgroundCompletion(message),
             onEntry: (entry) => this._emit({ type: "entry_appended", entry }),
             onError: (event, error) => this._extensionRunner?.emitError({ extensionPath: "<background>", event, error }),
         });
@@ -212,6 +227,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 +281,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 +393,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 +412,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 +497,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 +530,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 +645,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 +682,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 +708,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 +792,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") {
@@ -668,6 +889,9 @@ export class AgentSession {
      */
     dispose() {
         this._backgroundHost.dispose();
+        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
+            queued.reject(new Error("the session was disposed"));
+        }
         try {
             this.abortRetry();
             this.abortCompaction();
@@ -690,6 +914,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 +1152,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();
@@ -939,17 +1175,67 @@ export class AgentSession {
             await this._emitAgentSettled();
         }
     }
+    /**
+     * Deliver a background completion through the same queueing path as interactive input:
+     * steering into an active run lands the result right after the current tool batch, and an
+     * idle session starts its own turn. The promise settles only once the message is persisted,
+     * or once it can no longer be persisted, so the caller never releases its claim for a
+     * message the transcript does not contain.
+     */
+    _deliverBackgroundCompletion(message) {
+        if (!this.isStreaming) {
+            // Completion turns skip before_agent_start, but consume nextTurn context.
+            const asides = this._pendingNextTurnMessages.slice();
+            return this._runAgentPrompt(asides.length ? [message, ...asides] : message);
+        }
+        return new Promise((resolve, reject) => {
+            const queued = {
+                drained: false,
+                resolve: () => {
+                    if (this._queuedBackgroundCompletions.get(message) !== queued)
+                        return;
+                    this._queuedBackgroundCompletions.delete(message);
+                    resolve();
+                },
+                reject: (reason) => {
+                    if (this._queuedBackgroundCompletions.get(message) !== queued)
+                        return;
+                    this._queuedBackgroundCompletions.delete(message);
+                    reject(reason);
+                },
+            };
+            this._queuedBackgroundCompletions.set(message, queued);
+            try {
+                this.agent.steer(message);
+            }
+            catch (error) {
+                queued.reject(error);
+            }
+        });
+    }
+    /**
+     * Fail deliveries the owning run emitted but never persisted. A completion still sitting in
+     * the steering queue when its run ends stays claimed: the next run delivers it, so failing
+     * it here would persist the same message twice.
+     */
+    _failDrainedBackgroundCompletions() {
+        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
+            if (queued.drained)
+                queued.reject(new Error("the completion message was not persisted"));
+        }
+    }
     async _handlePostAgentRun() {
-        const 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 +1244,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 +1297,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 +1326,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 +1406,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 +1417,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",
@@ -1123,6 +1457,10 @@ export class AgentSession {
                 return;
             }
             preflightResult?.(true);
+            // The user's message is now established, so a completion may join this run through the
+            // steering queue instead of waiting for the turn to end. Everything above still holds
+            // the pause, so no delivery can race input hooks, model validation or compaction.
+            resumeBackground();
             await this._runAgentPrompt(messages);
         }
         finally {
@@ -1251,11 +1589,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 +1637,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 +1655,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 });
@@ -1384,6 +1722,10 @@ export class AgentSession {
         this._steeringMessages = [];
         this._followUpMessages = [];
         this.agent.clearAllQueues();
+        // Clearing the queues drops queued completions; fail them so their claims retry.
+        for (const queued of [...this._queuedBackgroundCompletions.values()]) {
+            queued.reject(new Error("the completion message was dequeued before delivery"));
+        }
         this._emitQueueUpdate();
         return { steering, followUp };
     }
@@ -1412,6 +1754,8 @@ export class AgentSession {
         this.abortRetry();
         this.abortCompaction();
         this.abortBranchSummary();
+        if (this._isBeforeSettle)
+            this._abortDuringBeforeSettle = true;
         this.agent.abort();
         await this.waitForIdle();
     }
@@ -1732,9 +2076,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 +2172,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 +2196,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 +2245,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 +2255,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 +2368,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 +2390,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 +2875,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 +2968,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 +2996,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 +3176,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 +3277,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,