@code-yeongyu/senpi 2026.7.17 → 2026.7.20-2

package/dist/core/agent-session.js

@@ -16,7 +16,8 @@ import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { prepareAgentToolCall } from "@earendil-works/pi-agent-core";
-import { cleanupSessionResources, isContextOverflow, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
+import { cleanupSessionResources, isClassifierRefusal, isContextOverflow, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
+import { getAgentDir } from "../config.js";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
@@ -34,6 +35,10 @@ import { filterContextExcludedMessages } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { getModelNarrowingPatterns, resolveModelScope } from "./model-resolver.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
+import { RetryFallbackController } from "./retry-fallback/controller.js";
+import { SelectorCooldowns } from "./retry-fallback/cooldown.js";
+import { createFallbackLogger } from "./retry-fallback/log.js";
+import { validateFallbackChains } from "./retry-fallback/validate.js";
 import { buildSessionContext, CURRENT_SESSION_VERSION, getLatestCompactionEntry, } from "./session-manager.js";
 import { generateSessionTitle, shouldSkipSessionTitle } from "./session-title-generator.js";
 import { SessionWorkBarrier } from "./session-work-barrier.js";
@@ -65,13 +70,39 @@ function withoutDeletedHeaders(headers) {
         ? Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] !== null))
         : undefined;
 }
+/**
+ * Human-readable rejection message paired with a `CompactionRejectionCause`.
+ *
+ * Kept exhaustive over the union so the compiler flags any new cause that would
+ * otherwise reintroduce silent failures at the `compaction_end` UI seam.
+ */
+function describeCompactionRejection(cause) {
+    switch (cause) {
+        case "would-overflow":
+            return "Compaction rejected: the produced summary would still overflow the model context window. Reduce context (e.g. /new, drop attachments) or switch to a larger-context model.";
+        case "cancelled-by-extension":
+            return "Compaction rejected: cancelled by an extension.";
+        case "circuit-breaker":
+            return "Compaction rejected: the compaction circuit breaker is open after repeated failures. Wait for the cooldown and retry.";
+        case "per-turn-cap":
+            return "Compaction rejected: per-turn compaction cap reached for this turn.";
+    }
+}
 class CompactionRejectedError extends Error {
     constructor(rejectionCause) {
-        super(rejectionCause === "cancelled-by-extension" ? "Compaction cancelled" : "Compaction rejected");
+        super(rejectionCause === "cancelled-by-extension"
+            ? "Compaction cancelled"
+            : describeCompactionRejection(rejectionCause));
         this.name = "CompactionRejectedError";
         this.rejectionCause = rejectionCause;
     }
 }
+class RequiredCompactionError extends Error {
+    constructor() {
+        super("Context remains above the compaction threshold because compaction did not complete");
+        this.name = "RequiredCompactionError";
+    }
+}
 class MissingModelAccessError extends Error {
     constructor() {
         super("AgentSession requires modelRuntime or modelRegistry");
@@ -127,6 +158,7 @@ export class AgentSession {
         this._retryPromise = undefined;
         this._retryResolve = undefined;
         this._userAbortPromise = undefined;
+        this._suppressQueuedContinuationAfterUserAbort = false;
         // Bash execution state
         this._bashAbortController = undefined;
         this._pendingBashMessages = [];
@@ -158,6 +190,11 @@ export class AgentSession {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
+        const noModelFallback = config.resourceLoader.getExtensions().runtime.flagValues.get("no-model-fallback") === true ||
+            process.env.SENPI_NO_FALLBACK === "1";
+        if (noModelFallback) {
+            this.settingsManager.applyOverrides({ retry: { modelFallback: false } });
+        }
         this._scopedModels = config.scopedModels ?? [];
         this._favoriteModels = config.favoriteModels ?? [];
         this._resourceLoader = config.resourceLoader;
@@ -169,6 +206,30 @@ export class AgentSession {
         }
         this._modelRuntime = modelRuntime;
         this._modelRegistry = config.modelRegistry ?? new ModelRegistry(modelRuntime);
+        const fallbackLogger = createFallbackLogger(config.agentDir ?? getAgentDir());
+        this._fallbackValidationWarnings = validateFallbackChains(this.settingsManager.getRawFallbackChains(), this._modelRegistry);
+        for (const warning of this._fallbackValidationWarnings) {
+            fallbackLogger.warn("validation_warning", { warning });
+        }
+        this._retryFallback = new RetryFallbackController({
+            getSettings: () => this.settingsManager.getRetryFallbackSettings(),
+            registry: this._modelRegistry,
+            cooldowns: new SelectorCooldowns(config.fallbackNow ?? (() => Date.now())),
+            logger: fallbackLogger,
+            switchModel: async (model, thinking, reason) => {
+                await this._switchActiveModel(model, {
+                    persistDefault: false,
+                    appendSessionEntry: true,
+                    entryReason: reason,
+                    emitModelSelect: reason === "fallback-revert",
+                    invalidateCompaction: false,
+                    ephemeralThinkingLevel: thinking,
+                });
+            },
+            emit: (event) => this._emit(event),
+            getCurrentSelector: () => (this.model ? { model: this.model, thinkingLevel: this.thinkingLevel } : undefined),
+            isAuthAvailable: (provider) => this._modelRuntime.hasConfiguredAuth(provider),
+        });
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
@@ -179,7 +240,7 @@ export class AgentSession {
         const initialModel = this.agent.state.model;
         if (initialModel) {
             const scopedMatch = this._scopedModels.find((sm) => modelsAreEqual(sm.model, initialModel));
-            this._currentServiceTier = scopedMatch?.serviceTier;
+            this._currentServiceTier = this._resolveServiceTier(initialModel, scopedMatch?.serviceTier);
         }
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
@@ -309,8 +370,27 @@ export class AgentSession {
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
-            const previousSnapshot = await previousPrepareNextTurnWithContext?.(turn, signal);
-            const previousContext = previousSnapshot?.context ?? turn.context;
+            let messages = turn.context.messages;
+            if (turn.toolResults.length > 0) {
+                await this._agentEventQueue;
+                const compacted = await this._checkCompaction(turn.message, true, "threshold");
+                if (compacted) {
+                    messages = this.agent.state.messages.slice();
+                }
+                else {
+                    const settings = this.settingsManager.getCompactionSettings();
+                    const contextTokens = estimateContextTokens(filterContextExcludedMessages(this.sessionManager.buildSessionContext().messages)).tokens;
+                    if (settings.enabled && this.model && shouldCompact(contextTokens, this.model.contextWindow, settings)) {
+                        throw new RequiredCompactionError();
+                    }
+                }
+            }
+            const postCompactionTurn = {
+                ...turn,
+                context: { ...turn.context, messages },
+            };
+            const previousSnapshot = await previousPrepareNextTurnWithContext?.(postCompactionTurn, signal);
+            const previousContext = previousSnapshot?.context ?? postCompactionTurn.context;
             return {
                 ...previousSnapshot,
                 context: {
@@ -359,7 +439,9 @@ export class AgentSession {
     _modelSelectionChangesContext(previousModel, nextModel) {
         if (!modelsAreEqual(previousModel, nextModel))
             return true;
-        return previousModel?.contextWindow !== nextModel.contextWindow;
+        if (previousModel?.contextWindow !== nextModel.contextWindow)
+            return true;
+        return previousModel?.api !== nextModel.api;
     }
     _invalidateCompactionForModelSelection() {
         this.abortCompaction();
@@ -416,7 +498,8 @@ export class AgentSession {
             return;
         }
         const lastAssistant = this._findLastAssistantInMessages(event.messages);
-        if (!lastAssistant || !this._isRetryableError(lastAssistant)) {
+        if (!lastAssistant ||
+            (!this._isRetryableError(lastAssistant) && !this._isHardErrorFallbackEligible(lastAssistant))) {
             return;
         }
         this._retryPromise = new Promise((resolve) => {
@@ -466,12 +549,22 @@ export class AgentSession {
             return false;
         }
         const lastAssistant = this._lastAssistantMessage ?? this._findLastAssistantInMessages(messages);
-        if (!lastAssistant || !this._isRetryableError(lastAssistant)) {
+        if (!lastAssistant) {
             return false;
         }
-        if (this._retryAttempt + 1 > settings.maxRetries) {
+        const retryableError = this._isRetryableError(lastAssistant);
+        if (!retryableError && this._isHardErrorFallbackEligible(lastAssistant)) {
+            return true;
+        }
+        if (!retryableError) {
             return false;
         }
+        if (isClassifierRefusal(lastAssistant)) {
+            return this._retryAttempt + 1 <= settings.maxRetries && this._retryFallback.canTryFallback();
+        }
+        if (this._retryAttempt + 1 > settings.maxRetries) {
+            return this._retryFallback.canTryFallback();
+        }
         const errorMessage = lastAssistant.errorMessage || "Unknown error";
         const providerDelayMs = this._getProviderRetryDelayMs(errorMessage);
         if (providerDelayMs === undefined) {
@@ -484,6 +577,7 @@ export class AgentSession {
         // This ensures the UI sees the updated queue state
         if (event.type === "message_start" && event.message.role === "user") {
             this._overflowRecoveryAttempted = false;
+            this._retryFallback.resetTurn();
             const messageText = this._getUserMessageText(event.message);
             if (messageText) {
                 // Check steering queue first
@@ -532,6 +626,14 @@ export class AgentSession {
                 // Reset retry counter immediately on successful assistant response
                 // This prevents accumulation across multiple LLM calls within a turn
                 if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
+                    const fallback = this._retryFallback.activeState;
+                    if (fallback) {
+                        this._emit({
+                            type: "retry_fallback_succeeded",
+                            model: this.model ? `${this.model.provider}/${this.model.id}` : "",
+                            chainKey: fallback.chainKey,
+                        });
+                    }
                     this._emit({
                         type: "auto_retry_end",
                         success: true,
@@ -543,16 +645,27 @@ export class AgentSession {
         }
         // Check auto-retry and auto-compaction after agent completes
         let launchedContinuation = false;
-        const allowsQueuedContinuation = event.type === "agent_end" ? this._agentEndAllowsQueuedContinuation(event.messages) : false;
+        const userAbortSuppressedQueuedContinuation = event.type === "agent_end" && this._suppressQueuedContinuationAfterUserAbort;
+        if (userAbortSuppressedQueuedContinuation) {
+            this._suppressQueuedContinuationAfterUserAbort = false;
+        }
+        const allowsQueuedContinuation = event.type === "agent_end" && !userAbortSuppressedQueuedContinuation
+            ? this._agentEndAllowsQueuedContinuation(event.messages)
+            : false;
         if (event.type === "agent_end" && this._lastAssistantMessage) {
             const msg = this._lastAssistantMessage;
             this._lastAssistantMessage = undefined;
-            // Check for retryable errors first (overloaded, rate limit, server errors)
-            if (this._isRetryableError(msg)) {
-                const didRetry = await this._handleRetryableError(msg);
-                if (didRetry)
-                    return; // Retry was initiated, don't proceed to compaction
+            // Retry transient failures normally and eligible hard errors only through a fallback.
+            const retryableError = this._isRetryableError(msg);
+            let didRetry = false;
+            if (retryableError) {
+                didRetry = await this._handleRetryableError(msg);
+            }
+            else if (this._isHardErrorFallbackEligible(msg)) {
+                didRetry = await this._handleRetryableError(msg, { hardErrorFallback: true });
             }
+            if (didRetry)
+                return; // Retry was initiated, don't proceed to compaction
             this._resolveRetry();
             launchedContinuation = await this._checkCompaction(msg);
         }
@@ -596,6 +709,10 @@ export class AgentSession {
         }
         return undefined;
     }
+    _isAssistantFromBeforeLatestCompaction(assistantMessage) {
+        const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());
+        return compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();
+    }
     _replaceMessageInPlace(target, replacement) {
         // Agent-core stores the finalized message object in its state before emitting message_end.
         // SessionManager persistence happens later in _processAgentEvent() with event.message.
@@ -774,6 +891,17 @@ export class AgentSession {
     get serviceTier() {
         return this._currentServiceTier;
     }
+    /**
+     * Explicit scoped/favorite tiers win; otherwise fall back to the model's
+     * configured serviceTier from models.json/extension compatibility config.
+     */
+    _resolveServiceTier(model, explicit) {
+        if (explicit)
+            return explicit;
+        if (!model)
+            return undefined;
+        return this._modelRuntime.getCompatibilityRequestConfig(model).serviceTier;
+    }
     /** Whether the session is currently processing an agent run or post-run continuation. */
     get isStreaming() {
         return this._isAgentRunActive;
@@ -996,6 +1124,8 @@ export class AgentSession {
         }
         const loadedSkills = this._resourceLoader.getSkills().skills;
         const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
+        const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
+        const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
         this._baseSystemPromptOptions = {
             cwd: this._cwd,
             skills: loadedSkills,
@@ -1004,7 +1134,10 @@ export class AgentSession {
             toolSnippets,
             promptGuidelines,
         };
-        return buildDynamicSystemPrompt(this._baseSystemPromptOptions);
+        const basePrompt = loaderSystemPrompt ?? buildDynamicSystemPrompt(this._baseSystemPromptOptions);
+        return loaderAppendSystemPrompt.length > 0
+            ? `${basePrompt}\n\n${loaderAppendSystemPrompt.join("\n\n")}`
+            : basePrompt;
     }
     /**
      * Send a prompt to the agent.
@@ -1035,6 +1168,10 @@ export class AgentSession {
             await this._waitForSettledSessionWork();
             throwIfCancelled();
         }
+        // Turn boundary: restore the primary model if the fallback cooldown expired.
+        if (!this.isStreaming) {
+            await this._maybeRestoreFallbackPrimary();
+        }
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         const promptDisposition = options?.promptDisposition;
@@ -1112,7 +1249,14 @@ export class AgentSession {
             // The user's new prompt is sent below, so do not call agent.continue() here.
             const lastAssistant = this._findLastAssistantMessage();
             if (lastAssistant) {
-                await this._checkCompaction(lastAssistant, false, "pre_prompt");
+                const compacted = await this._checkCompaction(lastAssistant, false, "pre_prompt");
+                if (!compacted && !this._isAssistantFromBeforeLatestCompaction(lastAssistant)) {
+                    const settings = this.settingsManager.getCompactionSettings();
+                    const contextTokens = estimateContextTokens(filterContextExcludedMessages(this.sessionManager.buildSessionContext().messages)).tokens;
+                    if (settings.enabled && this.model && shouldCompact(contextTokens, this.model.contextWindow, settings)) {
+                        throw new RequiredCompactionError();
+                    }
+                }
             }
             // Build messages array (custom message if any, then user message)
             messages = [];
@@ -1507,6 +1651,9 @@ export class AgentSession {
             await this._userAbortPromise;
             return;
         }
+        if (this.isStreaming) {
+            this._suppressQueuedContinuationAfterUserAbort = true;
+        }
         const abortPromise = (async () => {
             this.agent.abort();
             await this.waitForIdle();
@@ -1574,20 +1721,57 @@ export class AgentSession {
         if (!(await this._modelRuntime.checkAuth(model.provider))) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
+        // A manual model change abandons any active fallback window; if a fallback
+        // retry sleep is still pending, cancel it so no surprise continuation fires.
+        const hadActiveFallback = this._retryFallback.activeState !== undefined;
+        this._retryFallback.clearForManualModelChange(model);
+        if (hadActiveFallback && this._retryAbortController) {
+            this.abortRetry();
+        }
+        return await this._switchActiveModel(model, {
+            persistDefault: true,
+            appendSessionEntry: true,
+            emitModelSelect: true,
+            invalidateCompaction: true,
+        });
+    }
+    async _maybeRestoreFallbackPrimary() {
+        try {
+            await this._retryFallback.maybeRestorePrimary(this.settingsManager.getRetryFallbackSettings().revertPolicy);
+        }
+        catch (error) {
+            this._retryFallback.clear();
+            console.error("fallback revert failed; cleared fallback state", error);
+        }
+    }
+    async _switchActiveModel(model, opts) {
         const previousModel = this.model;
-        const invalidatesCompaction = this._modelSelectionChangesContext(previousModel, model);
-        if (invalidatesCompaction) {
+        if (opts.invalidateCompaction && this._modelSelectionChangesContext(previousModel, model)) {
             this._invalidateCompactionForModelSelection();
         }
-        const thinkingLevel = this._getThinkingLevelForModelSwitch();
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(opts.ephemeralThinkingLevel);
         this.agent.state.model = model;
-        this.sessionManager.appendModelChange(model.provider, model.id);
-        this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        if (opts.appendSessionEntry) {
+            this.sessionManager.appendModelChange(model.provider, model.id, opts.entryReason, previousModel?.provider, previousModel?.id);
+        }
+        if (opts.persistDefault) {
+            this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        }
         const scopedMatch = this._scopedModels.find((sm) => modelsAreEqual(sm.model, model));
-        this._currentServiceTier = scopedMatch?.serviceTier;
-        this.setThinkingLevel(thinkingLevel);
+        this._currentServiceTier = this._resolveServiceTier(model, scopedMatch?.serviceTier);
+        if (opts.ephemeralThinkingLevel !== undefined) {
+            this._applyEphemeralThinkingLevel(thinkingLevel);
+        }
+        else {
+            this.setThinkingLevel(thinkingLevel);
+        }
+        if (!opts.emitModelSelect)
+            return undefined;
         return await this._emitModelSelect(model, previousModel, "set");
     }
+    _applyEphemeralThinkingLevel(level) {
+        this.agent.state.thinkingLevel = level;
+    }
     /**
      * Cycle to next/previous model.
      * Uses favorite models, constrained by any global model narrowing.
@@ -1619,11 +1803,12 @@ export class AgentSession {
         if (invalidatesCompaction) {
             this._invalidateCompactionForModelSelection();
         }
+        this._retryFallback.clearForManualModelChange(next.model);
         const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
         this.agent.state.model = next.model;
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
         this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
-        this._currentServiceTier = next.serviceTier;
+        this._currentServiceTier = this._resolveServiceTier(next.model, next.serviceTier);
         // Apply thinking level.
         // - Explicit favorite model thinking level overrides current session level
         // - Undefined favorite model thinking level inherits the current session preference
@@ -1650,6 +1835,9 @@ export class AgentSession {
         // Only persist if actually changing
         const previousLevel = this.agent.state.thinkingLevel;
         const isChanging = effectiveLevel !== previousLevel;
+        if (isChanging) {
+            this._retryFallback.noteManualThinkingLevel();
+        }
         this.agent.state.thinkingLevel = effectiveLevel;
         if (isChanging) {
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
@@ -1901,7 +2089,7 @@ export class AgentSession {
                         signal,
                     }));
                     if (extensionResult?.cancel) {
-                        return await this._rejectCompaction(request, requestId, "cancelled-by-extension", true);
+                        return await this._rejectCompaction(request, requestId, extensionResult.rejectionCause ?? "cancelled-by-extension", true, extensionResult.reason);
                     }
                     if (extensionResult?.compaction) {
                         compactionResult = extensionResult.compaction;
@@ -1910,7 +2098,7 @@ export class AgentSession {
                 }
                 if (!compactionResult) {
                     const { apiKey, headers, extraBody, env } = await this._getCompactionRequestAuth(this.model);
-                    compactionResult = await compact(preparation, this.model, apiKey, headers, request.customInstructions, signal, extraBody, this.thinkingLevel, this.agent.streamFn, env);
+                    compactionResult = await compact(preparation, this.model, apiKey, headers, request.customInstructions, signal, extraBody, this.thinkingLevel, this.agent.streamFn, env, this.agent.transformContext);
                 }
             }
             if (signal.aborted) {
@@ -1973,11 +2161,22 @@ export class AgentSession {
             fromHook: fromExtension,
         };
         const simulatedMessages = buildSessionContext([...pathEntries, simulatedCompactionEntry], simulatedCompactionEntry.id).messages;
-        const contextTokens = estimateContextTokens(filterContextExcludedMessages(simulatedMessages)).tokens;
+        const contextTokens = estimateMessagesTokens(filterContextExcludedMessages(simulatedMessages));
         const settings = this.settingsManager.getCompactionSettings();
         return contextTokens > this.model.contextWindow - settings.reserveTokens;
     }
-    async _rejectCompaction(request, requestId, rejectionCause, aborted) {
+    async _rejectCompaction(request, requestId, rejectionCause, aborted, extensionReason) {
+        // Per plan Section 1: rejection must never be silent. The compaction_end event
+        // carries a non-empty human-readable errorMessage (unless the user aborted, where
+        // the aborted branch already renders "Compaction cancelled"). session_compact is
+        // also emitted with accepted:false so the compaction extension's circuit-breaker
+        // bookkeeping stops being dead code; other builtin session_compact handlers guard
+        // on event.accepted.
+        const trimmedExtensionReason = extensionReason?.trim();
+        const detailedMessage = trimmedExtensionReason
+            ? `Compaction rejected: ${trimmedExtensionReason}`
+            : describeCompactionRejection(rejectionCause);
+        const errorMessage = aborted && !trimmedExtensionReason ? undefined : detailedMessage;
         this._emit({
             type: "compaction_end",
             reason: request.reason,
@@ -1987,6 +2186,16 @@ export class AgentSession {
             requestId,
             accepted: false,
             rejectionCause,
+            errorMessage,
+        });
+        await this._extensionRunner.emit({
+            type: "session_compact",
+            reason: request.reason,
+            requestId,
+            accepted: false,
+            rejectionCause,
+            fromExtension: false,
+            willRetry: false,
         });
         return { accepted: false, requestId, rejectionCause };
     }
@@ -2014,7 +2223,7 @@ export class AgentSession {
      * @param assistantMessage The assistant message to check
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true, requestReason) {
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true, inlineReason) {
         const settings = this.settingsManager.getCompactionSettings();
         if (!settings.enabled)
             return false;
@@ -2032,8 +2241,7 @@ export class AgentSession {
         // compaction boundary. This prevents a stale pre-compaction usage/error
         // from retriggering compaction on the first prompt after compaction.
         const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());
-        const assistantIsFromBeforeCompaction = compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();
-        if (assistantIsFromBeforeCompaction) {
+        if (this._isAssistantFromBeforeLatestCompaction(assistantMessage)) {
             return false;
         }
         // Case 1: Overflow - LLM returned context overflow error.
@@ -2058,7 +2266,7 @@ export class AgentSession {
                     willRetry: false,
                     errorMessage,
                 });
-                if (requestReason === "pre_prompt") {
+                if (inlineReason === "pre_prompt") {
                     throw new Error(errorMessage);
                 }
                 return false;
@@ -2071,42 +2279,47 @@ export class AgentSession {
                 this.agent.state.messages = messages.slice(0, -1);
                 this._incrementMessageRevision();
             }
-            if (requestReason) {
-                await this._runPrePromptCompaction(assistantMessage, skipAbortedCheck, "overflow", willRetry);
+            if (inlineReason) {
+                return await this._runPrePromptCompaction(assistantMessage, skipAbortedCheck, "overflow", willRetry);
             }
             else {
                 return await this._runAutoCompaction("overflow", willRetry);
             }
-            return false;
         }
         // Case 2: Threshold - context is getting large
         // For error messages or all-zero usage messages, estimate from the last valid response.
         // This ensures sessions that hit persistent API errors (e.g. 529) or malformed zero-usage
         // responses can still compact and do not reset context accounting.
         let contextTokens;
-        const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
-        if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
-            const messages = filterContextExcludedMessages(this.agent.state.messages);
-            const estimate = estimateContextTokens(messages);
-            if (estimate.lastUsageIndex === null)
-                return false; // No usage data at all
-            // Verify the usage source is post-compaction. Kept pre-compaction messages
-            // have stale usage reflecting the old (larger) context and would falsely
-            // trigger compaction right after one just finished.
-            const usageMsg = messages[estimate.lastUsageIndex];
-            if (compactionEntry &&
-                usageMsg.role === "assistant" &&
-                usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
-                return false;
-            }
-            contextTokens = estimate.tokens;
+        if (inlineReason) {
+            const messages = filterContextExcludedMessages(this.sessionManager.buildSessionContext().messages);
+            contextTokens = estimateContextTokens(messages).tokens;
         }
         else {
-            contextTokens = directContextTokens;
+            const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
+            if (assistantMessage.stopReason !== "error" && directContextTokens !== 0) {
+                contextTokens = directContextTokens;
+            }
+            else {
+                const messages = filterContextExcludedMessages(this.agent.state.messages);
+                const estimate = estimateContextTokens(messages);
+                if (estimate.lastUsageIndex === null)
+                    return false; // No usage data at all
+                // Verify the usage source is post-compaction. Kept pre-compaction messages
+                // have stale usage reflecting the old (larger) context and would falsely
+                // trigger compaction right after one just finished.
+                const usageMsg = messages[estimate.lastUsageIndex];
+                if (compactionEntry &&
+                    usageMsg.role === "assistant" &&
+                    usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
+                    return false;
+                }
+                contextTokens = estimate.tokens;
+            }
         }
         if (shouldCompact(contextTokens, contextWindow, settings)) {
-            if (requestReason) {
-                await this._runPrePromptCompaction(assistantMessage, skipAbortedCheck);
+            if (inlineReason) {
+                return await this._runPrePromptCompaction(assistantMessage, skipAbortedCheck, inlineReason);
             }
             else {
                 return await this._runAutoCompaction("threshold", false);
@@ -2127,6 +2340,7 @@ export class AgentSession {
             if (!execution.accepted && isContextOverflow(lastAssistantMessage, this.model?.contextWindow ?? 0)) {
                 this._overflowRecoveryAttempted = false;
             }
+            return execution.accepted;
         }
         catch (error) {
             if (isContextOverflow(lastAssistantMessage, this.model?.contextWindow ?? 0)) {
@@ -2142,6 +2356,7 @@ export class AgentSession {
                 willRetry,
                 errorMessage: aborted ? undefined : `Pre-prompt compaction failed: ${errorMessage}`,
             });
+            return false;
         }
         finally {
             this._compactionAbortController = undefined;
@@ -2464,6 +2679,37 @@ export class AgentSession {
             },
             getContextUsage: () => this.getContextUsage(),
             getCompactionSettings: () => this.settingsManager.getCompactionSettings(),
+            sessionSettings: {
+                getRetryFallbackSettings: () => this.settingsManager.getRetryFallbackSettings(),
+                setFallbackChain: async (key, entries) => {
+                    this.settingsManager.setFallbackChain(key, [...entries]);
+                    await this.settingsManager.flush();
+                },
+                removeFallbackChain: async (key) => {
+                    this.settingsManager.removeFallbackChain(key);
+                    await this.settingsManager.flush();
+                },
+                setModelFallbackEnabled: async (enabled) => {
+                    this.settingsManager.setModelFallbackEnabled(enabled);
+                    await this.settingsManager.flush();
+                },
+                setFallbackRevertPolicy: async (policy) => {
+                    this.settingsManager.setFallbackRevertPolicy(policy);
+                    await this.settingsManager.flush();
+                },
+                reload: () => this.settingsManager.reload(),
+                getFallbackStatus: () => {
+                    const active = this._retryFallback.activeState;
+                    if (!active)
+                        return undefined;
+                    return {
+                        active: true,
+                        currentModel: this.model ? `${this.model.provider}/${this.model.id}` : undefined,
+                        originalSelector: active.originalSelector,
+                        pinned: active.pinned,
+                    };
+                },
+            },
             compact: (options) => {
                 void (async () => {
                     this._disconnectFromAgent();
@@ -2525,12 +2771,20 @@ export class AgentSession {
                 this._modelRuntime.registerProvider(name, config);
                 this._refreshCurrentModelFromRegistry();
             },
+            registerNativeProvider: (provider) => {
+                this._modelRuntime.registerNativeProvider(provider);
+                this._refreshCurrentModelFromRegistry();
+            },
             unregisterProvider: (name) => {
                 this._modelRuntime.unregisterProvider(name);
                 this._refreshCurrentModelFromRegistry();
             },
         });
     }
+    /** Fallback-chain configuration warnings calculated when this session started. */
+    get fallbackValidationWarnings() {
+        return this._fallbackValidationWarnings;
+    }
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
         const previousActiveToolNames = this.getActiveToolNames();
@@ -2678,16 +2932,25 @@ export class AgentSession {
      * Context overflow errors are NOT retryable (handled by compaction instead).
      */
     _isRetryableError(message) {
-        if (!message.errorMessage)
-            return false;
         // Context overflow is handled by compaction, not retry.
         if (isContextOverflow(message, this.model?.contextWindow ?? 0))
             return false;
+        if (isClassifierRefusal(message))
+            return true;
+        if (!message.errorMessage)
+            return false;
         if (message.stopReason === "aborted") {
             return /timed? out|timeout/i.test(message.errorMessage);
         }
         return isRetryableAssistantError(message);
     }
+    _isHardErrorFallbackEligible(message) {
+        return (message.stopReason === "error" &&
+            !isContextOverflow(message, this.model?.contextWindow ?? 0) &&
+            !isClassifierRefusal(message) &&
+            !message.content.some((content) => content.type === "toolCall") &&
+            this._retryFallback.canTryFallback());
+    }
     _getProviderRetryDelayMs(errorMessage) {
         const retryAfterMsMatch = errorMessage.match(/\bretry[-_ ]?after[-_ ]?ms\s*[:=]\s*(\d+(?:\.\d+)?)/i);
         if (retryAfterMsMatch) {
@@ -2720,7 +2983,7 @@ export class AgentSession {
      * Handle retryable errors with exponential backoff.
      * @returns true if retry was initiated, false if max retries exceeded or disabled
      */
-    async _handleRetryableError(message) {
+    async _handleRetryableError(message, options = {}) {
         const settings = this.settingsManager.getRetrySettings();
         if (!settings.enabled) {
             this._resolveRetry();
@@ -2733,21 +2996,71 @@ export class AgentSession {
                 this._retryResolve = resolve;
             });
         }
-        this._retryAttempt++;
-        if (this._retryAttempt > settings.maxRetries) {
-            // Max retries exceeded, emit final failure and reset
-            this._emit({
-                type: "auto_retry_end",
-                success: false,
-                attempt: this._retryAttempt - 1,
-                finalError: message.errorMessage,
-            });
-            this._retryAttempt = 0;
-            this._resolveRetry(); // Resolve so waitForRetry() completes
-            return false;
-        }
         const errorMessage = message.errorMessage || "Unknown error";
-        const providerDelayMs = this._getProviderRetryDelayMs(errorMessage);
+        const isRefusal = isClassifierRefusal(message);
+        const hardErrorFallback = options.hardErrorFallback === true;
+        let switchedFallback = false;
+        if (hardErrorFallback) {
+            // A non-retryable provider failure must never replay on the same model.
+            switchedFallback = await this._retryFallback.tryFallback("hard-error", { errorMessage });
+            if (!switchedFallback) {
+                this._resolveRetry();
+                return false;
+            }
+            // The fallback starts fresh; the failed model's transient attempts do not carry over.
+            this._retryAttempt = 1;
+        }
+        else if (isRefusal) {
+            // Refusals are only retried through a new chain candidate. They never use
+            // same-model retries or the transient over-budget fallback escape hatch.
+            if (this._retryAttempt + 1 > settings.maxRetries) {
+                this._resolveRetry();
+                return false;
+            }
+            switchedFallback = await this._retryFallback.tryFallback("refusal", {});
+            if (!switchedFallback) {
+                const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
+                if (exhaustedChainKey) {
+                    this._emit({ type: "retry_fallback_exhausted", chainKey: exhaustedChainKey, lastError: errorMessage });
+                }
+                this._resolveRetry();
+                return false;
+            }
+            this._retryAttempt++;
+        }
+        else {
+            this._retryAttempt++;
+            if (this._retryAttempt > settings.maxRetries) {
+                switchedFallback = await this._retryFallback.tryFallback("transient", {
+                    errorMessage,
+                    retryAfterMs: this._getProviderRetryDelayMs(errorMessage),
+                });
+                if (switchedFallback) {
+                    // The new model receives a fresh retry budget; the failed model does not.
+                    this._retryAttempt = 1;
+                }
+                else {
+                    const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
+                    if (exhaustedChainKey) {
+                        this._emit({
+                            type: "retry_fallback_exhausted",
+                            chainKey: exhaustedChainKey,
+                            lastError: errorMessage,
+                        });
+                    }
+                    this._emit({
+                        type: "auto_retry_end",
+                        success: false,
+                        attempt: this._retryAttempt - 1,
+                        finalError: message.errorMessage,
+                    });
+                    this._retryAttempt = 0;
+                    this._resolveRetry();
+                    return false;
+                }
+            }
+        }
+        const providerDelayMs = isRefusal || hardErrorFallback ? undefined : this._getProviderRetryDelayMs(errorMessage);
         const maxRetryDelayMs = this.settingsManager.getProviderRetrySettings().maxRetryDelayMs;
         if (providerDelayMs !== undefined && providerDelayMs > maxRetryDelayMs) {
             this._emit({
@@ -2760,7 +3073,13 @@ export class AgentSession {
             this._resolveRetry();
             return false;
         }
-        const delayMs = providerDelayMs ?? settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        if (!switchedFallback) {
+            switchedFallback = await this._retryFallback.tryFallback("transient", {
+                errorMessage,
+                retryAfterMs: providerDelayMs,
+            });
+        }
+        const delayMs = switchedFallback ? 0 : (providerDelayMs ?? settings.baseDelayMs * 2 ** (this._retryAttempt - 1));
         // Prepare before auto_retry_start so an immediate Esc can cancel the retry sleep.
         this._retryAbortController = new AbortController();
         this._emit({
@@ -2796,6 +3115,9 @@ export class AgentSession {
             return false;
         }
         this._retryAbortController = undefined;
+        // Turn boundary: a suppression that expired during the backoff sleep lets
+        // the retry continue on the restored primary instead of the fallback model.
+        await this._maybeRestoreFallbackPrimary();
         // Retry via continue() - use setTimeout to break out of event handler chain
         setTimeout(() => {
             this.agent.continue().catch(() => {