@code-yeongyu/senpi 2026.8.18 → 2026.8.19

package/dist/core/agent-session.js

@@ -15,6 +15,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { prepareAgentToolCall } from "@earendil-works/pi-agent-core";
 import { contentText, SERVER_FALLBACK_ABORTED_DIAGNOSTIC } from "@earendil-works/pi-ai";
 import { cleanupSessionResources, isClassifierRefusal, isContextOverflow, isProviderStreamStallError, isProviderTimeoutError, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
@@ -35,6 +36,7 @@ import { CompactionLifecycleCoordinator } from "./compaction/lifecycle.js";
 import { isWarmSummaryAnchorValid } from "./compaction/warm-anchor.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { buildDynamicSystemPrompt } from "./dynamic-prompt/index.js";
+import { areExperimentalFeaturesEnabled } from "./experimental.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { CODEX_RESPONSES_API } from "./extensions/builtin/service-tier.js";
@@ -467,7 +469,10 @@ export class AgentSession {
         // points at the file to open; "default" means no scope configured any.
         const fallbackChainsSource = this.settingsManager.getFallbackChainsScope() ?? "default";
         for (const warning of this._fallbackValidationWarnings) {
-            fallbackLogger.warn("validation_warning", { warning, source: fallbackChainsSource });
+            fallbackLogger.warn("validation_warning", {
+                warning,
+                source: fallbackChainsSource,
+            });
         }
         this._selectorCooldowns = new SelectorCooldowns(config.fallbackNow ?? (() => Date.now()));
         this._fallbackNow = config.fallbackNow ?? (() => Date.now());
@@ -500,7 +505,10 @@ export class AgentSession {
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
         this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
-        this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
+        this._sessionStartEvent = config.sessionStartEvent ?? {
+            type: "session_start",
+            reason: "startup",
+        };
         this._autoTitleSessions = config.autoTitleSessions ?? false;
         const initialModel = this.agent.state.model;
         if (initialModel) {
@@ -756,7 +764,10 @@ export class AgentSession {
                 // this invocation: one replay is the bounded admission path.
                 const postLateCompactionTurn = {
                     ...turn,
-                    context: { ...turn.context, messages: this.agent.state.messages.slice() },
+                    context: {
+                        ...turn.context,
+                        messages: this.agent.state.messages.slice(),
+                    },
                 };
                 const postLateCompactionSnapshot = await previousPrepareNextTurnWithContext?.(postLateCompactionTurn, signal);
                 previousSnapshot = {
@@ -776,6 +787,7 @@ export class AgentSession {
                 },
                 model: this.agent.state.model,
                 thinkingLevel: this.agent.state.thinkingLevel,
+                thinkingSelection: this.agent.state.thinkingSelection ?? null,
                 abortServerSideFallback: this.settingsManager.getAbortServerSideFallback() && this._retryFallback.hasConfiguredChain(),
             };
         };
@@ -790,6 +802,14 @@ export class AgentSession {
             l(event);
         }
     }
+    async _emitSessionCompactFailed(event) {
+        if (this._extensionRunner.hasHandlers("session_compact_failed")) {
+            await this._extensionRunner.emit({
+                type: "session_compact_failed",
+                ...event,
+            });
+        }
+    }
     /** Mirror stuck-prone lifecycle transitions into logs/session.log (content-free). */
     _logSessionEvent(event) {
         if (event.type === "compaction_start") {
@@ -874,7 +894,10 @@ export class AgentSession {
                 : isProviderTimeoutError(message)
                     ? "timeout"
                     : "error";
-            this._sessionLogger.warn("provider_error", { kind, error: message.errorMessage });
+            this._sessionLogger.warn("provider_error", {
+                kind,
+                error: message.errorMessage,
+            });
         }
     }
     _estimateCompactionLogTokens(source) {
@@ -992,7 +1015,10 @@ export class AgentSession {
             const requiredCompactionError = this._requiredCompactionAdmissionError;
             this._requiredCompactionAdmissionError = undefined;
             if (requiredCompactionError) {
-                this._sessionLogger.warn("prompt_rejected", { stage: "admission", error: "RequiredCompactionError" });
+                this._sessionLogger.warn("prompt_rejected", {
+                    stage: "admission",
+                    error: "RequiredCompactionError",
+                });
                 throw requiredCompactionError;
             }
         }
@@ -1084,6 +1110,17 @@ export class AgentSession {
         }
         return reason;
     }
+    /**
+     * Threshold checks measure the larger of the provider-reported context and
+     * the plain local-transcript estimate. Providers whose usage tracks a
+     * server-side summarized conversation (native Cursor checkpoints) can report
+     * a context far smaller than the transcript this client replays every turn,
+     * and that small figure must not hide a transcript already past the window.
+     */
+    _resolveThresholdContextTokens(directContextTokens) {
+        const messages = filterContextExcludedMessages(this.agent.state.messages);
+        return Math.max(directContextTokens, estimateMessagesTokens(messages));
+    }
     _getAutoCompactionReason(message) {
         const settings = this.settingsManager.getCompactionSettings();
         if (!settings.enabled || message.stopReason === "aborted") {
@@ -1104,7 +1141,7 @@ export class AgentSession {
         let contextTokens;
         const directContextTokens = message.usage ? calculateContextTokens(message.usage) : 0;
         if (message.stopReason !== "error" && directContextTokens !== 0) {
-            contextTokens = directContextTokens;
+            contextTokens = this._resolveThresholdContextTokens(directContextTokens);
         }
         else {
             const messages = filterContextExcludedMessages(this.agent.state.messages);
@@ -1351,7 +1388,9 @@ export class AgentSession {
                     retryOutcome = await this._handleRetryableError(msg);
                 }
                 else if (hardErrorFallbackEligible) {
-                    retryOutcome = await this._handleRetryableError(msg, { hardErrorFallback: true });
+                    retryOutcome = await this._handleRetryableError(msg, {
+                        hardErrorFallback: true,
+                    });
                 }
             }
             if (retryOutcome === "continued") {
@@ -1372,7 +1411,12 @@ export class AgentSession {
                 const attempt = this._retryAttempt;
                 this._retryAttempt = 0;
                 this._resetHintTierState();
-                this._emit({ type: "auto_retry_end", success: false, attempt, finalError: msg.errorMessage });
+                this._emit({
+                    type: "auto_retry_end",
+                    success: false,
+                    attempt,
+                    finalError: msg.errorMessage,
+                });
             }
             this._resolveRetry();
             retryContinuationBlocked ||= retryOutcome === "blocked";
@@ -1482,7 +1526,13 @@ export class AgentSession {
                 try {
                     const result = await this._modelRuntime.completeSimple(demotedModel, {
                         systemPrompt: "Reply with OK.",
-                        messages: [{ role: "user", content: [{ type: "text", text: "OK" }], timestamp: now }],
+                        messages: [
+                            {
+                                role: "user",
+                                content: [{ type: "text", text: "OK" }],
+                                timestamp: now,
+                            },
+                        ],
                     }, { maxTokens: 1, signal });
                     return result.stopReason !== "error" && result.stopReason !== "aborted";
                 }
@@ -1753,6 +1803,10 @@ export class AgentSession {
     get thinkingLevel() {
         return this.agent.state.thinkingLevel;
     }
+    /** Explicit selector provenance, absent for SDK-defaulted effective levels. */
+    get thinkingSelection() {
+        return this.agent.state.thinkingSelection;
+    }
     get serviceTier() {
         return this._currentServiceTier;
     }
@@ -1808,7 +1862,11 @@ export class AgentSession {
         const fastMode = this.isFastModeActive();
         if (previousTier === this._currentServiceTier && previousFastMode === fastMode)
             return;
-        this._emit({ type: "service_tier_changed", tier: this.effectiveServiceTier, fastMode });
+        this._emit({
+            type: "service_tier_changed",
+            tier: this.effectiveServiceTier,
+            fastMode,
+        });
     }
     /**
      * Explicit scoped/favorite tiers win; otherwise fall back to the model's
@@ -1908,7 +1966,12 @@ export class AgentSession {
         }
         catch (err) {
             result = {
-                content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+                content: [
+                    {
+                        type: "text",
+                        text: err instanceof Error ? err.message : String(err),
+                    },
+                ],
                 details: { isError: true },
             };
             isError = true;
@@ -2050,6 +2113,7 @@ export class AgentSession {
             favoriteModels.push({
                 model,
                 thinkingLevel: favorite.thinkingLevel,
+                thinkingSelection: favorite.thinkingSelection,
                 serviceTier: favorite.serviceTier,
             });
         }
@@ -2188,8 +2252,20 @@ export class AgentSession {
         const canQueueWhileStreaming = (this.isStreaming || this._promptStartPending) &&
             !this.isCompacting &&
             options?.streamingBehavior !== undefined;
+        // Auto-compaction claims only _autoCompactionAbortController, which the
+        // admission guard above deliberately ignores so background compaction never
+        // rejects typed input. Without a queue route that message matched no branch
+        // below and fell through neither queued nor started (field bug: input typed
+        // while the TUI showed "Compacting context..." was accepted and dropped).
+        // Manual compaction keeps its fail-closed admission path untouched.
+        const canQueueDuringAutoCompaction = this._autoCompactionAbortController !== undefined &&
+            this._compactionAbortController === undefined &&
+            !this.isStreaming &&
+            !this._promptStartPending &&
+            options?.streamingBehavior !== undefined;
         if (shouldWaitForSessionWork &&
             !canQueueWhileStreaming &&
+            !canQueueDuringAutoCompaction &&
             (!this.isStreaming || this.isCompacting || this._sessionWorkBarrier.hasActiveWork)) {
             await this._waitForSettledSessionWork();
             throwIfCancelled();
@@ -2217,13 +2293,20 @@ export class AgentSession {
         const emitPendingCommandInvocation = () => {
             if (!pendingCommandInvocation)
                 return;
-            this._emit({ type: "command_invocation", command: pendingCommandInvocation });
+            this._emit({
+                type: "command_invocation",
+                command: pendingCommandInvocation,
+            });
             pendingCommandInvocation = undefined;
         };
         const emitInputDisposition = async (disposition) => {
             if (inputId === undefined)
                 return;
-            await this._extensionRunner.emit({ type: "input_disposition", inputId, disposition });
+            await this._extensionRunner.emit({
+                type: "input_disposition",
+                inputId,
+                disposition,
+            });
         };
         try {
             // Emit input event for extension interception (before skill/template expansion)
@@ -2299,6 +2382,26 @@ export class AgentSession {
                 preflightResult?.(true);
                 return;
             }
+            // Auto-compaction owns the session without claiming the admission controller,
+            // so a queueable submission reaches here with no branch above matching and
+            // would fall through neither queued nor started. Queue it instead of starting
+            // a turn against a context that is still being compacted.
+            if (canQueueDuringAutoCompaction && !this.isStreaming) {
+                if (options?.thinkingLevel !== undefined) {
+                    throw new Error("Cannot set thinkingLevel on a queued prompt; set it after the current turn completes.");
+                }
+                if (options?.streamingBehavior === "followUp") {
+                    await this._queueFollowUp(expandedText, currentImages);
+                }
+                else {
+                    await this._queueSteer(expandedText, currentImages);
+                }
+                emitPendingCommandInvocation();
+                await emitInputDisposition("queued");
+                promptDisposition?.("queued");
+                preflightResult?.(true);
+                return;
+            }
             // The queue-while-streaming bypass above skipped the settled-work wait. If
             // the run ended while input was being expanded, serialize with remaining
             // session work before sending a fresh prompt, and re-queue if a scheduled
@@ -2698,13 +2801,20 @@ export class AgentSession {
     async _queueSteer(text, images, enqueueOrder) {
         this._steeringMessages.push(text);
         this._recordQueuedInput(text, "steer", enqueueOrder);
-        this._sessionLogger.debug("queue_enqueue", { mode: "steer", count: this._steeringMessages.length });
+        this._sessionLogger.debug("queue_enqueue", {
+            mode: "steer",
+            count: this._steeringMessages.length,
+        });
         this._emitQueueUpdate();
         const content = [{ type: "text", text }];
         if (images) {
             content.push(...images);
         }
-        const message = { role: "user", content, timestamp: Date.now() };
+        const message = {
+            role: "user",
+            content,
+            timestamp: Date.now(),
+        };
         if (this._promptStartPending && this._skipNextPostCompactionAssistantCheck) {
             this._postCompactionDeferredSteeringMessages.push(message);
             return;
@@ -2717,13 +2827,20 @@ export class AgentSession {
     async _queueFollowUp(text, images, enqueueOrder) {
         this._followUpMessages.push(text);
         this._recordQueuedInput(text, "followUp", enqueueOrder);
-        this._sessionLogger.debug("queue_enqueue", { mode: "followUp", count: this._followUpMessages.length });
+        this._sessionLogger.debug("queue_enqueue", {
+            mode: "followUp",
+            count: this._followUpMessages.length,
+        });
         this._emitQueueUpdate();
         const content = [{ type: "text", text }];
         if (images) {
             content.push(...images);
         }
-        const message = { role: "user", content, timestamp: Date.now() };
+        const message = {
+            role: "user",
+            content,
+            timestamp: Date.now(),
+        };
         if (this._promptStartPending && this._skipNextPostCompactionAssistantCheck) {
             this._postCompactionDeferredFollowUpMessages.push(message);
             return;
@@ -2777,7 +2894,11 @@ export class AgentSession {
         const waitForExistingSessionWork = options?.triggerTurn === true &&
             options.deliverAs !== "nextTurn" &&
             !this.isStreaming &&
-            this._sessionWorkBarrier.hasActiveWork;
+            this._sessionWorkBarrier.hasActiveWork &&
+            // The session-start binding itself holds the barrier while it emits
+            // session_start; a triggerTurn message queued from that emission (e.g. a
+            // goal continuation) must not wait on the very work that is delivering it.
+            this._extensionBindingPromptReadiness === undefined;
         const pendingCompactionAdmission = this._pendingCompactionAdmission;
         const activeCompactionGeneration = this._compactionLifecycle.state.status === "running" ? this._compactionLifecycle.state.generation : undefined;
         let finishSessionWork;
@@ -2964,7 +3085,10 @@ export class AgentSession {
         this.agent.clearAllQueues();
         this._emitQueueUpdate();
         const cleared = { steering, followUp };
-        Object.defineProperty(cleared, "ordered", { value: ordered, enumerable: false });
+        Object.defineProperty(cleared, "ordered", {
+            value: ordered,
+            enumerable: false,
+        });
         return cleared;
     }
     /** Number of pending messages (includes both steering and follow-up) */
@@ -3099,7 +3223,7 @@ export class AgentSession {
         if (opts.invalidateCompaction && this._modelSelectionChangesContext(previousModel, model)) {
             this._invalidateCompactionForModelSelection();
         }
-        const thinkingLevel = this._getThinkingLevelForModelSwitch(model, opts.ephemeralThinkingLevel);
+        const thinking = this._getThinkingForModelSwitch(model, opts.ephemeralThinkingLevel);
         this.agent.state.model = model;
         this.agent.abortServerSideFallback =
             this.settingsManager.getAbortServerSideFallback() && this._retryFallback.hasConfiguredChain();
@@ -3114,10 +3238,10 @@ export class AgentSession {
         const previousFastMode = this.isFastModeActive();
         this._currentServiceTier = this._resolveServiceTier(model, scopedMatch?.serviceTier);
         if (opts.ephemeralThinkingLevel !== undefined) {
-            this._applyEphemeralThinkingLevel(thinkingLevel);
+            this._applyEphemeralThinkingLevel(thinking.level);
         }
         else {
-            this.setSessionThinkingLevel(thinkingLevel);
+            this._setThinkingLevel(thinking.level, false, thinking.selection);
         }
         this._emitHighReasoningWarningIfNeeded();
         // Post-switch: the level reported here is the one actually in force (clamped, or restored
@@ -3136,6 +3260,7 @@ export class AgentSession {
     _applyEphemeralThinkingLevel(level) {
         const previousLevel = this.agent.state.thinkingLevel;
         this.agent.state.thinkingLevel = level;
+        this.agent.state.thinkingSelection = undefined;
         if (previousLevel !== level) {
             this._emit({ type: "thinking_level_changed", level });
         }
@@ -3173,18 +3298,15 @@ export class AgentSession {
         }
         this._probeBackScheduler.cancel("manual-model-change");
         this._retryFallback.clearForManualModelChange(next.model);
-        const thinkingLevel = this._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);
+        const thinking = this._getThinkingForModelSwitch(next.model, next.thinkingLevel, next.thinkingSelection);
         this.agent.state.model = next.model;
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
         this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
         const previousTier = this._currentServiceTier;
         const previousFastMode = this.isFastModeActive();
         this._currentServiceTier = this._resolveServiceTier(next.model, next.serviceTier);
-        // Apply thinking level.
-        // - Explicit favorite model thinking level overrides the effective session level
-        // - Undefined favorite model thinking level restores the remembered user preference
-        // setSessionThinkingLevel clamps without replacing that preference.
-        this.setSessionThinkingLevel(thinkingLevel);
+        // Apply thinking level and provenance from the favorite projection or remembered preference.
+        this._setThinkingLevel(thinking.level, false, thinking.selection);
         // Post-switch, same contract as _switchActiveModel: the level in force AFTER the cycle.
         this._emit({
             type: "model_changed",
@@ -3194,7 +3316,11 @@ export class AgentSession {
         });
         this._emitServiceTierChangeIfNeeded(previousTier, previousFastMode);
         const systemPromptChange = await this._emitModelSelect(next.model, currentModel, "cycle");
-        const cycleResult = { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
+        const cycleResult = {
+            model: next.model,
+            thinkingLevel: this.thinkingLevel,
+            isScoped: true,
+        };
         if (systemPromptChange) {
             cycleResult.systemPromptChange = systemPromptChange;
         }
@@ -3209,33 +3335,39 @@ export class AgentSession {
      * Persistent calls refresh per-model memory; session entries and events are emitted only on change.
      */
     setThinkingLevel(level) {
-        this._setThinkingLevel(level, true);
+        this._setThinkingLevel(level, true, { level, source: "explicit" });
     }
     /**
      * Set the thinking level for this session without changing the global default.
      * The effective level is still persisted in this session's history.
      */
     setSessionThinkingLevel(level) {
-        this._setThinkingLevel(level, false);
+        this._setThinkingLevel(level, false, { level, source: "explicit" });
     }
-    _setThinkingLevel(level, updateGlobalDefault) {
+    _setThinkingLevel(level, updateGlobalDefault, selection) {
         const availableLevels = this.getAvailableThinkingLevels();
         const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
         // Only persist if actually changing
         const previousLevel = this.agent.state.thinkingLevel;
+        const previousSelection = this.agent.state.thinkingSelection;
+        const effectiveSelection = selection ? { ...selection, level: effectiveLevel } : undefined;
+        const selectionChanged = previousSelection?.level !== effectiveSelection?.level ||
+            previousSelection?.source !== effectiveSelection?.source ||
+            previousSelection?.legacyVariantId !== effectiveSelection?.legacyVariantId;
         const isChanging = effectiveLevel !== previousLevel;
-        if (isChanging) {
+        if (isChanging || selectionChanged) {
             this._retryFallback.noteManualThinkingLevel();
         }
         this.agent.state.thinkingLevel = effectiveLevel;
+        this.agent.state.thinkingSelection = effectiveSelection;
         if (updateGlobalDefault) {
             const model = this.model;
             if (model) {
                 this.settingsManager.setModelThinkingLevel(model.provider, model.id, effectiveLevel);
             }
         }
-        if (isChanging) {
-            this.sessionManager.appendThinkingLevelChange(effectiveLevel);
+        if (isChanging || selectionChanged) {
+            this.sessionManager.appendThinkingLevelChange(effectiveLevel, effectiveSelection);
             if (updateGlobalDefault && (this.supportsThinking() || effectiveLevel !== "off")) {
                 this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
             }
@@ -3305,12 +3437,31 @@ export class AgentSession {
     supportsThinking() {
         return !!this.model?.reasoning;
     }
-    _getThinkingLevelForModelSwitch(model, explicitLevel) {
-        const requestedLevel = explicitLevel ??
-            this.settingsManager.getModelThinkingLevel(model.provider, model.id) ??
-            this.settingsManager.getDefaultThinkingLevel() ??
-            DEFAULT_THINKING_LEVEL;
-        return this._clampThinkingLevel(requestedLevel, getSupportedThinkingLevels(model));
+    _getThinkingForModelSwitch(model, explicitLevel, explicitSelection) {
+        let requestedLevel = explicitLevel;
+        let selection = explicitSelection;
+        if (requestedLevel !== undefined && !selection)
+            selection = { level: requestedLevel, source: "explicit" };
+        if (requestedLevel === undefined) {
+            const remembered = this.settingsManager.getModelThinkingLevel(model.provider, model.id);
+            if (remembered !== undefined) {
+                requestedLevel = remembered;
+                selection = { level: remembered, source: "explicit" };
+            }
+        }
+        if (requestedLevel === undefined) {
+            const configuredDefault = this.settingsManager.getDefaultThinkingLevel();
+            if (configuredDefault !== undefined) {
+                requestedLevel = configuredDefault;
+                selection = { level: configuredDefault, source: "explicit" };
+            }
+        }
+        requestedLevel ??= DEFAULT_THINKING_LEVEL;
+        const level = this._clampThinkingLevel(requestedLevel, getSupportedThinkingLevels(model));
+        return {
+            level,
+            selection: selection ? { ...selection, level } : undefined,
+        };
     }
     _clampThinkingLevel(level, availableLevels) {
         const available = new Set(availableLevels);
@@ -3456,9 +3607,66 @@ export class AgentSession {
             }
         }
     }
+    /** Generate the built-in summary while preserving fork routing identity and transforms. */
+    async _runDefaultCompaction(preparation, requestModel, apiKey, headers, extraBody, customInstructions, signal, env, reason) {
+        let cacheFriendly;
+        if (areExperimentalFeaturesEnabled()) {
+            const systemPrompt = this.agent.state.systemPrompt;
+            const tools = this.agent.state.tools.slice();
+            const buildSourceContext = (messages) => this.agent.buildProviderContext({ systemPrompt, messages: messages.slice(), tools: tools.slice() }, signal);
+            const fullContext = await buildSourceContext(this.agent.state.messages);
+            const isExactPrefix = (candidate) => candidate.messages.length > 0 &&
+                candidate.messages.length <= fullContext.messages.length &&
+                isDeepStrictEqual(candidate.messages, fullContext.messages.slice(0, candidate.messages.length));
+            let sourceContext;
+            if (preparation.messagesToSummarize.length > 0 && preparation.sourceMessages) {
+                const candidate = await buildSourceContext(preparation.sourceMessages);
+                if (isExactPrefix(candidate))
+                    sourceContext = candidate;
+            }
+            let turnPrefixSourceContext;
+            if (preparation.isSplitTurn &&
+                preparation.turnPrefixMessages.length > 0 &&
+                preparation.turnPrefixSourceMessages) {
+                const candidate = await buildSourceContext(preparation.turnPrefixSourceMessages);
+                const providerTurnPrefix = await this.agent.convertToLlm(preparation.turnPrefixMessages.slice());
+                if (isExactPrefix(candidate) &&
+                    providerTurnPrefix.length > 0 &&
+                    providerTurnPrefix.length <= candidate.messages.length &&
+                    isDeepStrictEqual(candidate.messages.slice(-providerTurnPrefix.length), providerTurnPrefix)) {
+                    turnPrefixSourceContext = candidate;
+                }
+            }
+            if (sourceContext || turnPrefixSourceContext) {
+                cacheFriendly = {
+                    sourceContext,
+                    turnPrefixSourceContext,
+                    requestOptions: {
+                        sessionId: this.agent.sessionId,
+                        onPayload: this.agent.onPayload,
+                        onResponse: this.agent.onResponse,
+                        transport: this.agent.transport,
+                        thinkingBudgets: this.agent.thinkingBudgets,
+                        maxRetryDelayMs: this.agent.maxRetryDelayMs,
+                    },
+                };
+            }
+        }
+        return compact(preparation, requestModel, apiKey, headers, customInstructions, signal, extraBody, this.thinkingLevel, this.agent.streamFunction, env, this.agent.transformContext, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), this.sessionManager.getSessionId(), cacheFriendly);
+    }
     /**
      * Manually compact the session context.
-     * Aborts current agent operation first.
+     *
+     * This is the manual entry point used by `/compact`, RPC, and extensions. It is
+     * separate from automatic threshold/overflow compaction, which enters through
+     * `_checkCompaction()` and `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * Aborts the current agent operation first. Manual compaction never retries or
+     * continues the interrupted agent turn.
+     *
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
@@ -3499,6 +3707,7 @@ export class AgentSession {
             }
             const message = error instanceof Error ? error.message : String(error);
             const aborted = isCompactionExecutionAborted(error);
+            const errorMessage = aborted ? undefined : `Compaction failed: ${message}`;
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -3506,7 +3715,14 @@ export class AgentSession {
                 aborted,
                 willRetry: false,
                 requestId,
-                errorMessage: aborted ? undefined : `Compaction failed: ${message}`,
+                errorMessage,
+            });
+            await this._emitSessionCompactFailed({
+                reason: "manual",
+                errorMessage,
+                aborted,
+                willRetry: false,
+                fromExtension: false,
             });
             throw error;
         }
@@ -3539,7 +3755,11 @@ export class AgentSession {
             : randomUUID();
         if (ownsController) {
             this._claimCompactionController(new AbortController(), "compaction");
-            this._emit({ type: "compaction_start", reason: options.reason, requestId });
+            this._emit({
+                type: "compaction_start",
+                reason: options.reason,
+                requestId,
+            });
         }
         const controller = this._compactionAbortController;
         if (!controller)
@@ -3642,7 +3862,6 @@ export class AgentSession {
         const model = this.model;
         if (!model)
             throw new Error(formatNoModelSelectedMessage());
-        const thinkingLevel = this.thinkingLevel;
         const controller = request.controller;
         // Async auth and provider preparation may yield to a newer route. A stale
         // controller must never promote itself into a lifecycle generation.
@@ -3709,7 +3928,7 @@ export class AgentSession {
                 }
                 if (!compactionResult) {
                     const { model: requestModel, apiKey, headers, extraBody, env, } = await this._getCompactionRequestAuth(model);
-                    compactionResult = await compact(preparation, requestModel, apiKey, headers, request.customInstructions, signal, extraBody, thinkingLevel, this.agent.streamFunction, env, this.agent.transformContext, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason: request.reason }), this.sessionManager.getSessionId());
+                    compactionResult = await this._runDefaultCompaction(preparation, requestModel, apiKey, headers, extraBody, request.customInstructions, signal, env, request.reason);
                 }
             }
             if (signal.aborted) {
@@ -3798,7 +4017,13 @@ export class AgentSession {
                 fromExtension,
                 willRetry: request.willRetry,
             });
-            return { accepted: true, requestId, result: compactionResult, compactionEntry: savedEntry, fromExtension };
+            return {
+                accepted: true,
+                requestId,
+                result: compactionResult,
+                compactionEntry: savedEntry,
+                fromExtension,
+            };
         }
         catch (error) {
             if (error instanceof CompactionExecutionError) {
@@ -3933,8 +4158,8 @@ export class AgentSession {
         this._branchSummaryAbortController?.abort();
     }
     /**
-     * Check if compaction is needed and run it.
-     * Called after agent_end and before prompt submission.
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
      *
      * Two cases:
      * 1. Overflow: LLM returned context overflow error, remove error message from agent state, compact, auto-retry
@@ -3942,6 +4167,7 @@ export class AgentSession {
      *
      * @param assistantMessage The assistant message to check
      * @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 _enforceCompactionBeforeProvider(assistantMessage, skipAbortedCheck, inlineReason, retryAfterCompaction = false) {
         const blockedAdmission = this._blockedPostCompactionAssistant;
@@ -3987,9 +4213,12 @@ export class AgentSession {
      * reapply their already-assembled one-shot additions after it succeeds.
      */
     async _enforceFinalProviderAdmission(messages) {
-        // Normal user-only prompts keep the established provider-overflow recovery
-        // path. This final gate closes the separate gap introduced by turn-local
-        // custom additions, which the normal pre-prompt check cannot observe.
+        // User-only prompts are deliberately admitted without this gate: prompt
+        // admission must never brick on a rejected or cooled-down compaction
+        // (issues #531/#886), so oversized user prompts rely on threshold
+        // compaction — which also samples the local transcript estimate — and on
+        // provider-overflow recovery. This gate closes the separate gap opened by
+        // turn-local custom additions, which the pre-prompt check cannot observe.
         if (!messages.some((message) => message.role === "custom"))
             return;
         const model = this.model;
@@ -4064,6 +4293,8 @@ export class AgentSession {
         if (isOverflow) {
             this._flushPostCompactionDeferredMessages();
             const willRetry = retryAfterCompaction || assistantMessage.stopReason !== "stop";
+            // Case 2: the response completed successfully. Compact, but do not retry because
+            // agent.continue() cannot continue from a completed assistant response.
             if (!willRetry) {
                 const compacted = await this._runAutoCompaction("overflow", false);
                 if (!compacted &&
@@ -4092,6 +4323,8 @@ 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.
             this._overflowRecoveryAttempted = true;
             // 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)
@@ -4131,7 +4364,7 @@ export class AgentSession {
         else {
             const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
             if (assistantMessage.stopReason !== "error" && directContextTokens !== 0) {
-                contextTokens = directContextTokens;
+                contextTokens = this._resolveThresholdContextTokens(directContextTokens);
             }
             else {
                 const messages = filterContextExcludedMessages(this.agent.state.messages);
@@ -4357,7 +4590,14 @@ export class AgentSession {
             .catch(() => undefined);
     }
     /**
-     * Internal: Run auto-compaction with events.
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts` after preparation and extension
+     * interception.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
      */
     async _runAutoCompaction(reason, willRetry) {
         const finishCompactionWork = this._sessionWorkBarrier.begin();
@@ -4458,6 +4698,11 @@ export class AgentSession {
                 this._overflowRecoveryAttempted = false;
             const errorMessage = error instanceof Error ? error.message : "compaction failed";
             const aborted = isCompactionExecutionAborted(error);
+            const formattedErrorMessage = aborted
+                ? undefined
+                : reason === "overflow"
+                    ? `Context overflow recovery failed: ${errorMessage}`
+                    : `Auto-compaction failed: ${errorMessage}`;
             this._emit({
                 type: "compaction_end",
                 reason,
@@ -4465,11 +4710,14 @@ export class AgentSession {
                 aborted,
                 willRetry: false,
                 requestId,
-                errorMessage: aborted
-                    ? undefined
-                    : reason === "overflow"
-                        ? `Context overflow recovery failed: ${errorMessage}`
-                        : `Auto-compaction failed: ${errorMessage}`,
+                errorMessage: formattedErrorMessage,
+            });
+            await this._emitSessionCompactFailed({
+                reason,
+                errorMessage: formattedErrorMessage,
+                aborted,
+                willRetry: false,
+                fromExtension: false,
             });
             return false;
         }
@@ -4761,7 +5009,11 @@ export class AgentSession {
                         await this._abortActiveAgentAndRetry("system");
                         this._disconnectFromAgent();
                         disconnected = true;
-                        this._emit({ type: "compaction_start", reason: "extension", requestId });
+                        this._emit({
+                            type: "compaction_start",
+                            reason: "extension",
+                            requestId,
+                        });
                         const execution = await this._executeCompaction({
                             controller,
                             owner: "compaction",
@@ -4881,7 +5133,9 @@ export class AgentSession {
             ...registeredTools.filter(isConfiguredBuiltinTool),
             ...this._customTools.map((definition) => ({
                 definition,
-                sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
+                sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, {
+                    source: "sdk",
+                }),
             })),
         ].filter((tool) => isAllowedTool(tool.definition.name));
         const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
@@ -4890,7 +5144,9 @@ export class AgentSession {
             name,
             {
                 definition,
-                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
+                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, {
+                    source: "builtin",
+                }),
             },
         ]));
         for (const tool of allCustomTools) {
@@ -5018,7 +5274,10 @@ export class AgentSession {
             if (entry)
                 previousActiveToolRegistrationIds.set(name, deriveExtensionRegistrationId(entry.sourceInfo, name));
         }
-        await emitSessionShutdownEvent(oldExtensionRunner, { type: "session_shutdown", reason: "reload" });
+        await emitSessionShutdownEvent(oldExtensionRunner, {
+            type: "session_shutdown",
+            reason: "reload",
+        });
         time("shutdown", "reload");
         await this.settingsManager.reload();
         this.syncQueueModesFromSettings();
@@ -5030,14 +5289,18 @@ export class AgentSession {
         // swallows availability errors, so a failed scan must fall back to the runtime and
         // keep the previous refresh-and-surface-the-error behavior.
         const refreshedModels = this._modelRuntime.hasFreshAvailabilitySnapshot()
-            ? { getAvailable: async () => this._modelRuntime.getAvailableSnapshot() }
+            ? {
+                getAvailable: async () => this._modelRuntime.getAvailableSnapshot(),
+            }
             : this._modelRuntime;
         this.setScopedModels(await resolveModelScope(getModelNarrowingPatterns({
             legacyEnabledPatterns: this.settingsManager.getEnabledModels(),
         }), refreshedModels));
         this.setFavoriteModels(await resolveModelScope(this.settingsManager.getFavoriteModels() ?? [], refreshedModels));
         time("models", "reload");
-        await this._resourceLoader.reload({ settingsAlreadyReloadedFor: this.settingsManager });
+        await this._resourceLoader.reload({
+            settingsAlreadyReloadedFor: this.settingsManager,
+        });
         time("resources", "reload");
         try {
             this._buildRuntime({
@@ -5055,7 +5318,11 @@ export class AgentSession {
             const removed = oldExtensionIdentities.filter((extension) => !newExtensionResolvedPaths.has(extension.resolvedPath));
             try {
                 if (removed.length > 0) {
-                    await oldExtensionRunner.emit({ type: "session_extensions_removed", reason: "reload", removed });
+                    await oldExtensionRunner.emit({
+                        type: "session_extensions_removed",
+                        reason: "reload",
+                        removed,
+                    });
                 }
             }
             finally {
@@ -5070,7 +5337,10 @@ export class AgentSession {
         if (hasBindings) {
             await options?.beforeSessionStart?.();
             this.syncPromptCacheSafeWaitEnv();
-            await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
+            await this._extensionRunner.emit({
+                type: "session_start",
+                reason: "reload",
+            });
             await this.extendResourcesFromExtensions("reload");
         }
         time("lifecycle", "reload");
@@ -5087,7 +5357,9 @@ export class AgentSession {
         if (!this._extensionRunner.hasHandlers("session_before_reload")) {
             return { cancelled: false };
         }
-        const result = await this._extensionRunner.emit({ type: "session_before_reload" });
+        const result = await this._extensionRunner.emit({
+            type: "session_before_reload",
+        });
         if (result?.cancel !== true) {
             return { cancelled: false };
         }
@@ -5174,9 +5446,18 @@ export class AgentSession {
         const finishTurn = (attempt, finalError) => {
             const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
             if (exhaustedChainKey) {
-                this._emit({ type: "retry_fallback_exhausted", chainKey: exhaustedChainKey, lastError: errorMessage });
+                this._emit({
+                    type: "retry_fallback_exhausted",
+                    chainKey: exhaustedChainKey,
+                    lastError: errorMessage,
+                });
             }
-            this._emit({ type: "auto_retry_end", success: false, attempt, finalError });
+            this._emit({
+                type: "auto_retry_end",
+                success: false,
+                attempt,
+                finalError,
+            });
             this._retryAttempt = 0;
             this._resetHintTierState();
             this._resolveRetry();
@@ -5222,7 +5503,9 @@ export class AgentSession {
             // Billing-class failures never recover on this account, so the fallback
             // switch pins as the session model instead of reverting after the cooldown.
             const reason = isBillingErrorMessage(errorMessage) ? "billing" : "hard-error";
-            switchedFallback = await this._retryFallback.tryFallback(reason, { errorMessage });
+            switchedFallback = await this._retryFallback.tryFallback(reason, {
+                errorMessage,
+            });
             if (!switchedFallback) {
                 this._resolveRetry();
                 return "not-handled";
@@ -5251,7 +5534,11 @@ export class AgentSession {
             if (!switchedFallback) {
                 const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                 if (exhaustedChainKey) {
-                    this._emit({ type: "retry_fallback_exhausted", chainKey: exhaustedChainKey, lastError: errorMessage });
+                    this._emit({
+                        type: "retry_fallback_exhausted",
+                        chainKey: exhaustedChainKey,
+                        lastError: errorMessage,
+                    });
                 }
                 if (this._retryAttempt > 0) {
                     this._emit({
@@ -5617,7 +5904,11 @@ export class AgentSession {
             const result = await executeBashWithOperations(resolvedCommand, this.sessionManager.getCwd(), options?.operations ?? createLocalBashOperations({ shellPath }), {
                 onChunk: (delta) => {
                     onChunk?.(delta);
-                    this._emit({ type: "bash_execution_update", id: options?.id, delta });
+                    this._emit({
+                        type: "bash_execution_update",
+                        id: options?.id,
+                        delta,
+                    });
                 },
                 signal: abortController.signal,
             });
@@ -5697,7 +5988,10 @@ export class AgentSession {
      */
     setSessionName(name) {
         this.sessionManager.appendSessionInfo(name);
-        const event = { type: "session_info_changed", name: this.sessionManager.getSessionName() };
+        const event = {
+            type: "session_info_changed",
+            name: this.sessionManager.getSessionName(),
+        };
         this._emit(event);
         void this._extensionRunner.emit(event);
     }
@@ -5798,7 +6092,9 @@ export class AgentSession {
                     reserveTokens: branchSummarySettings.reserveTokens,
                     streamFn: this.agent.streamFunction,
                     retry: this.settingsManager.getRetrySettings(),
-                    callbacks: this._summarizationRetryCallbacks({ source: "branchSummary" }),
+                    callbacks: this._summarizationRetryCallbacks({
+                        source: "branchSummary",
+                    }),
                 });
                 if (result.aborted) {
                     return { cancelled: true, aborted: true };
@@ -6005,7 +6301,11 @@ export class AgentSession {
             }
             if (!hasPostCompactionUsage) {
                 const tokens = messages.reduce((sum, message) => sum + estimateTokens(message), 0);
-                return { tokens, contextWindow, percent: (tokens / contextWindow) * 100 };
+                return {
+                    tokens,
+                    contextWindow,
+                    percent: (tokens / contextWindow) * 100,
+                };
             }
         }
         const estimate = estimateContextTokens(messages);