open-multi-agent-kit 0.95.2 → 0.96.1

package/dist/core/agent-session.js

@@ -16,7 +16,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join as joinPath } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { getVisionRouteModel, isVisionRouteModel } from "omk-agent-core";
+import { getVisionRouteModel } from "omk-agent-core";
 import { clampThinkingLevel, cleanupSessionResources, deriveContextPromptCacheKey, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "omk-ai";
 import { APP_NAME, VERSION } from "../config.js";
 import { theme } from "../modes/interactive/theme/theme.js";
@@ -32,6 +32,7 @@ import { getCompactionHeadroomThreshold } from "./compaction/compaction.js";
 import { createCompactionHysteresisConfig, createCompactionHysteresisState, stepCompactionHysteresis, } from "./compaction/hysteresis.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, generateBranchSummary, prepareCompaction, resolveCompactionModel, } from "./compaction/index.js";
 import { compactionEmitWillRetry } from "./compaction/resume-policy.js";
+import { isSessionModelOverflow, shouldSkipCompactionCheck } from "./compaction-gate.js";
 import { estimateToolResultReserve, } from "./context-budget-reserved-tokens.js";
 import { createDiskContextBudgetCacheProviderV2, DiskContextBudgetCacheProviderV2, } from "./context-budget-v2-cache-disk.js";
 import { applyContextCacheInvalidation, createContextCacheInvalidationSnapshot, } from "./context-budget-v2-cache-invalidation.js";
@@ -50,6 +51,8 @@ import { buildRuntimeProvenance } from "./runtime-provenance.js";
 import { TurnMetricsSink } from "./turn-metrics.js";
 /** Values that disable a session-level feature through its environment variable. */
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "disable", "disabled"]);
+const MAX_OVERFLOW_RECOVERY_ATTEMPTS = 2;
+const OVERFLOW_RECOVERY_EMERGENCY_TOKENS = 4_096;
 function isDisabledEnvValue(value) {
     return value !== undefined && DISABLED_ENV_VALUES.has(value.trim().toLowerCase());
 }
@@ -68,9 +71,13 @@ function firstTextContent(result) {
     return undefined;
 }
 import { redactCredentialShapedContent } from "./compaction/transaction.js";
+import { selectContextFilesForModel } from "./model-prompt-policy.js";
 import { findExactModelReferenceMatch } from "./model-resolver.js";
+import { computePromptTokenBudget } from "./prompt-budget.js";
+import { classifyPromptCacheTransition } from "./prompt-cache.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { isContentSafetyStopMessage, isStickySafetyModel, isTransientProviderErrorMessage, pickFailoverCandidate, resolveProviderResilience, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { isQuotaExhaustionMessage, isStickySafetyModel, pickFailoverCandidate, resolveProviderResilience, shouldEjectStickySafetyModel, shouldHonorSafetyFailover, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { computeRetryDelayMs, failoverModelKey, isFailoverTriggerError, isRetryableAssistantError, nextRetryAttempt, retryBudgetForAssistantError, } from "./provider-retry.js";
 import { getBiasStepsForCell, parseRouterBiasSnapshot } from "./reasoning-router-bias.js";
 import { classifyTaskV4, deriveRouterFeedbackFeaturesV4, resolveThinkingLevelV4WithUncertainty, TASK_CLASS_THINKING_LEVELS_V4, } from "./reasoning-router-v4.js";
 import { redactSensitiveText, redactSensitiveTextForced } from "./redaction.js";
@@ -82,6 +89,7 @@ import { SessionBashService } from "./session-bash-service.js";
 import { SessionCompactionService } from "./session-compaction-service.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
 import { acquireSessionOwnerLeaseSync } from "./session-owner-lease.js";
+import { assembleSessionSystemPrompt } from "./session-system-prompt.js";
 import { classifySessionTermination, } from "./session-termination.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPromptPlan } from "./system-prompt.js";
@@ -302,7 +310,7 @@ export class AgentSession {
     // Compaction state
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
-    _overflowRecoveryAttempted = false;
+    _overflowRecoveryAttempts = 0;
     _thresholdCompactionEmergency = false;
     _compactionHysteresisState = createCompactionHysteresisState();
     // Branch summarization state
@@ -313,6 +321,8 @@ export class AgentSession {
     // v10.3-Ω: models that already refused/failed this turn — failover must advance,
     // not re-pick the same candidate (claude-opus-5 → grok → grok → grok loop fix).
     _refusedModels = new Set();
+    /** True when `--model` / `--provider` pinned this process to one model. */
+    _modelPinned;
     // Bash execution state
     _bashService;
     _compactionService;
@@ -381,6 +391,7 @@ export class AgentSession {
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
         this._scopedModels = config.scopedModels ?? [];
+        this._modelPinned = config.modelPinned === true;
         this._resourceLoader = config.resourceLoader;
         this._customTools = config.customTools ?? [];
         this._cwd = config.cwd;
@@ -585,12 +596,15 @@ export class AgentSession {
         if (/stop_reason\s*=\s*(refusal|sensitive)|content\/safety stop|safety stop|provider\.refusal|kind=provider_refusal/i.test(text)) {
             return { area: "provider", code: "refusal" };
         }
+        // Quota/billing exhaustion is checked BEFORE the generic 401/403 auth
+        // patterns: "403 ... usage limit for this billing cycle" is transient per
+        // cycle and must fail over, not terminate the turn as an auth error.
+        if (isQuotaExhaustionMessage(text) || /rate.?limit|too many requests|429/i.test(text)) {
+            return { area: "provider", code: "rate_limit" };
+        }
         if (/auth|unauthori[sz]ed|forbidden|invalid.?api.?key|no api key|401|403|\/login/i.test(text)) {
             return { area: "provider", code: "auth" };
         }
-        if (/rate.?limit|too many requests|429|quota|available balance|billing/i.test(text)) {
-            return { area: "provider", code: "rate_limit" };
-        }
         // Kimi/K3 + OpenAI-compat: orphan tool results after dropped error assistants.
         // Sanitize-and-retry (transform-messages drops orphans), not a hard tool fatal.
         if (/tool_call_id\s+is\s+not\s+found|tool_call_id\s+not\s+found|unknown\s+tool_call_id/i.test(text)) {
@@ -609,6 +623,9 @@ export class AgentSession {
         if (!this.model || /no model|model selected|model is required/i.test(message)) {
             return { area: "configuration", code: "invalid" };
         }
+        if (isQuotaExhaustionMessage(message)) {
+            return { area: "provider", code: "rate_limit" };
+        }
         if (/auth|api key|unauthori[sz]ed|forbidden|401|403|\/login/i.test(message)) {
             return { area: "provider", code: "auth" };
         }
@@ -966,7 +983,7 @@ export class AgentSession {
         // When a user message starts, check if it's from either queue and remove it BEFORE emitting
         // This ensures the UI sees the updated queue state
         if (event.type === "message_start" && event.message.role === "user") {
-            this._overflowRecoveryAttempted = false;
+            this._overflowRecoveryAttempts = 0;
             const messageText = this._getUserMessageText(event.message);
             if (messageText) {
                 // Check steering queue first
@@ -1017,7 +1034,7 @@ export class AgentSession {
                 this._lastAssistantMessage = finalizedEvent.message;
                 const assistantMsg = finalizedEvent.message;
                 if (assistantMsg.stopReason !== "error") {
-                    this._overflowRecoveryAttempted = false;
+                    this._overflowRecoveryAttempts = 0;
                 }
                 // Reset retry counter immediately on successful assistant response
                 // This prevents accumulation across multiple LLM calls within a turn
@@ -1035,13 +1052,14 @@ export class AgentSession {
     };
     _willRetryAfterAgentEnd(event) {
         const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled || this._retryAttempt >= settings.maxRetries) {
+        if (!settings.enabled)
             return false;
-        }
         for (let i = event.messages.length - 1; i >= 0; i--) {
             const message = event.messages[i];
             if (message.role === "assistant") {
-                return this._isRetryableError(message);
+                const assistant = message;
+                const maxRetries = retryBudgetForAssistantError(assistant, settings.maxRetries);
+                return this._retryAttempt < maxRetries && this._isRetryableError(assistant);
             }
         }
         return false;
@@ -1546,7 +1564,7 @@ export class AgentSession {
         }
         return undefined;
     }
-    _getContextBudgetOptions(queryContext = this._extractCurrentQuery()) {
+    _getContextBudgetOptions(queryContext = this._extractCurrentQuery(), model = this.model) {
         const contextGovernorOverride = process.env.OMK_CONTEXT_GOVERNOR;
         if (contextGovernorOverride === "0") {
             return undefined;
@@ -1554,56 +1572,24 @@ export class AgentSession {
         if (contextGovernorOverride !== "1" && !this.settingsManager.getContextBudgetEnabled()) {
             return undefined;
         }
-        const contextWindow = this.model?.contextWindow ?? 0;
-        // --- maxPromptTokens ---
-        // Priority 1: explicit env override (user knows best)
-        const envMaxPrompt = parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_MAX_PROMPT_TOKENS");
-        let maxPromptTokens;
-        let responseReserveTokens;
-        if (envMaxPrompt !== undefined) {
-            // User override — use as-is for prompt, derive response reserve normally
-            maxPromptTokens = envMaxPrompt;
-            responseReserveTokens =
-                parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ??
-                    this._computeResponseReserve(contextWindow);
-        }
-        else if (contextWindow > 0) {
-            // Dynamic: derive from model contextWindow
-            const envPromptRatio = parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_PROMPT_RATIO");
-            const envResponseRatio = parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RATIO");
-            responseReserveTokens =
-                parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ??
-                    this._computeResponseReserve(contextWindow, envResponseRatio);
-            const safetyMargin = Math.floor(contextWindow * SAFETY_MARGIN_RATIO);
-            if (envPromptRatio !== undefined && envPromptRatio > 0 && envPromptRatio < 1) {
-                maxPromptTokens = Math.floor(contextWindow * envPromptRatio);
-            }
-            else {
-                // Default: contextWindow minus reserves and safety margin
-                maxPromptTokens = contextWindow - responseReserveTokens - safetyMargin;
-            }
-        }
-        else {
-            // No model info — legacy fallback
-            maxPromptTokens = LEGACY_MAX_PROMPT_TOKENS;
-            responseReserveTokens =
-                parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ?? LEGACY_RESPONSE_RESERVE_TOKENS;
-        }
+        const contextWindow = model?.contextWindow ?? 0;
+        const budget = computePromptTokenBudget({
+            contextWindow,
+            modelMaxTokens: model?.maxTokens,
+            envMaxPromptTokens: parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_MAX_PROMPT_TOKENS"),
+            envResponseReserveTokens: parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS"),
+            envPromptRatio: parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_PROMPT_RATIO"),
+            envResponseRatio: parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RATIO"),
+        });
+        const maxPromptTokens = budget.maxPromptTokens;
+        const responseReserveTokens = budget.responseReserveTokens;
         const cacheProvider = this._contextBudgetCacheProvider ?? this._createContextBudgetCacheProvider();
         cacheProvider.setInvalidationSnapshot?.(this._contextCacheInvalidationSnapshot);
         this._contextBudgetCacheProvider = cacheProvider;
-        // Enforce floor
-        if (maxPromptTokens < MIN_PROMPT_TOKENS) {
-            maxPromptTokens = MIN_PROMPT_TOKENS;
-        }
-        // Ensure responseReserve does not exceed maxPromptTokens
-        if (responseReserveTokens >= maxPromptTokens) {
-            responseReserveTokens = Math.max(Math.floor(maxPromptTokens / 4), LEGACY_RESPONSE_RESERVE_TOKENS);
-        }
         return {
             maxPromptTokens,
             responseReserveTokens,
-            modelId: this.model?.id ?? "unknown",
+            modelId: model?.id ?? "unknown",
             tokenizerMode: parseTokenizerModeEnv(process.env.OMK_CONTEXT_GOVERNOR_TOKENIZER),
             activeSkillNames: parseCommaSeparatedEnv(process.env.OMK_CONTEXT_GOVERNOR_ACTIVE_SKILLS),
             queryContext,
@@ -1614,15 +1600,6 @@ export class AgentSession {
      * Compute responseReserveTokens from contextWindow.
      * Prefers the model's own maxTokens when available, otherwise uses a ratio.
      */
-    _computeResponseReserve(contextWindow, overrideRatio) {
-        // Prefer model's maxTokens (actual output limit) if available and reasonable
-        const modelMaxTokens = this.model?.maxTokens;
-        if (modelMaxTokens !== undefined && modelMaxTokens > 0 && modelMaxTokens < contextWindow) {
-            return modelMaxTokens;
-        }
-        const ratio = overrideRatio ?? RESPONSE_RESERVE_RATIO;
-        return Math.max(Math.floor(contextWindow * ratio), LEGACY_RESPONSE_RESERVE_TOKENS);
-    }
     _recordPromptCachePlan(reason) {
         const boundary = this.agent.state.systemPromptCacheBoundary;
         const scope = this.model ? `${this.model.provider}/${this.model.id}` : "unknown";
@@ -1633,60 +1610,40 @@ export class AgentSession {
             messages: [],
             tools: this.agent.state.tools,
         }, scope);
-        if (!nextKey) {
+        const transition = classifyPromptCacheTransition(this._promptCacheKey, nextKey);
+        if (transition.kind === "bypass") {
             this._promptCacheBoundaryBypasses += 1;
             this._promptCacheStablePrefixCharacters = 0;
-            if (this._promptCacheKey !== undefined) {
+            if (transition.recordBreak) {
                 this._promptCacheLastBreakReason = reason;
             }
             this._promptCacheKey = undefined;
             return;
         }
-        if (this._promptCacheKey !== undefined && this._promptCacheKey !== nextKey) {
+        if (transition.kind === "changed") {
             this._promptCacheKeyChanges += 1;
             this._promptCacheLastBreakReason = reason;
         }
         this._promptCacheKey = nextKey;
         this._promptCacheStablePrefixCharacters = boundary ?? 0;
     }
-    _rebuildSystemPrompt(toolNames) {
-        const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
-        const toolSnippets = {};
-        const promptGuidelines = [];
-        for (const name of validToolNames) {
-            const snippet = this._toolPromptSnippets.get(name);
-            if (snippet) {
-                toolSnippets[name] = snippet;
-            }
-            const toolGuidelines = this._toolPromptGuidelines.get(name);
-            if (toolGuidelines) {
-                promptGuidelines.push(...toolGuidelines);
-            }
-        }
-        const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
-        const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
-        const grokAppend = grokPlaybookAppendForProvider(this.model?.provider);
-        const appendParts = [...loaderAppendSystemPrompt];
-        if (grokAppend) {
-            appendParts.push(grokAppend);
-        }
-        const appendSystemPrompt = appendParts.length > 0 ? appendParts.join("\n\n") : undefined;
-        const loadedSkills = this._resourceLoader.getSkills().skills;
-        const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
-        this._baseSystemPromptOptions = {
+    _rebuildSystemPrompt(toolNames, model = this.model) {
+        const assembled = assembleSessionSystemPrompt({
             cwd: this._cwd,
-            skills: loadedSkills,
-            contextFiles: loadedContextFiles,
-            customPrompt: loaderSystemPrompt,
-            appendSystemPrompt,
-            selectedTools: validToolNames,
-            toolSnippets,
-            promptGuidelines,
-            contextBudget: this._getContextBudgetOptions(),
-        };
-        const built = buildSystemPromptPlan(this._baseSystemPromptOptions);
-        this._baseSystemPromptCacheBoundary = built.cacheBoundary;
-        return built.prompt;
+            toolNames,
+            hasTool: (name) => this._toolRegistry.has(name),
+            toolPromptSnippets: this._toolPromptSnippets,
+            toolPromptGuidelines: this._toolPromptGuidelines,
+            customPrompt: this._resourceLoader.getSystemPrompt(),
+            appendSystemPrompt: this._resourceLoader.getAppendSystemPrompt(),
+            providerAppend: grokPlaybookAppendForProvider(model?.provider),
+            skills: this._resourceLoader.getSkills().skills,
+            contextFiles: selectContextFilesForModel(this._resourceLoader.getAgentsFiles().agentsFiles, model),
+            contextBudget: this._getContextBudgetOptions(undefined, model),
+        });
+        this._baseSystemPromptOptions = assembled.options;
+        this._baseSystemPromptCacheBoundary = assembled.cacheBoundary;
+        return assembled.prompt;
     }
     // =========================================================================
     // Prompting
@@ -2226,16 +2183,25 @@ export class AgentSession {
         if (!this._modelRegistry.hasConfiguredAuth(model)) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
-        // Root-level: block sticky safety models (Fable) unless explicitly allowed in settings.
+        // Root-level: block sticky safety models (Fable) unless the user pinned `--model`.
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        if (resilience.blockStickySafetyModels && isStickySafetyModel(model.id, model.provider)) {
+        if (shouldEjectStickySafetyModel({
+            blockStickySafetyModels: resilience.blockStickySafetyModels,
+            modelPinned: this._modelPinned,
+        }) &&
+            isStickySafetyModel(model.id, model.provider)) {
             throw new Error(stickySafetyBlockMessage(model.id, model.provider));
         }
         // Grok OAuth: block selecting Imagine models as the session chat model.
         assertTextChatModelForCompletion(model.id, model.provider);
         const previousModel = this.model;
         const thinkingLevel = this._getThinkingLevelForModelSwitch();
+        const nextSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames(), model);
         this.agent.state.model = model;
+        this._baseSystemPrompt = nextSystemPrompt;
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
+        this.agent.state.systemPromptCacheBoundary = this._baseSystemPromptCacheBoundary;
+        this.agent.state.systemPromptCacheBoundaryBypass = false;
         this.sessionManager.appendModelChange(model.provider, model.id);
         this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
         // Re-clamp thinking level for new model's capabilities
@@ -2949,46 +2915,41 @@ export class AgentSession {
      */
     async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
         const settings = this.settingsManager.getCompactionSettings();
-        if (!settings.enabled)
-            return false;
-        // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
-        if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
-            return false;
-        const contextWindow = this.model?.contextWindow ?? 0;
-        // Skip overflow check if the message came from a different model.
-        // This handles the case where user switched from a smaller-context model (e.g. opus)
-        // to a larger-context model (e.g. codex) - the overflow error from the old model
-        // shouldn't trigger compaction for the new model.
-        const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;
-        // Image-bearing turns are auto-routed to a vision-capable model (gpt-5.6-luna)
-        // while the session model stays text-only (deepseek). An overflow from that
-        // routed model must still count as the session's own overflow: compaction is
-        // the fix, and the raw context_length_exceeded error must never reach the user.
-        const visionRouteOverflow = this.model != null &&
-            !(this.model.input ?? []).includes("image") &&
-            isVisionRouteModel({ provider: assistantMessage.provider, id: assistantMessage.model });
-        // Skip compaction checks if this assistant message is older than the latest
-        // compaction boundary. This prevents a stale pre-compaction usage/error
-        // from retriggering compaction on the first prompt after compaction.
+        // Stale pre-compaction usage/errors must not retrigger compaction on the
+        // first prompt after one finished.
         const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());
-        const assistantIsFromBeforeCompaction = compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();
-        if (assistantIsFromBeforeCompaction) {
+        if (shouldSkipCompactionCheck({
+            enabled: settings.enabled,
+            skipAbortedCheck,
+            stopReason: assistantMessage.stopReason,
+            messageTimestamp: assistantMessage.timestamp,
+            latestCompactionTimestamp: compactionEntry ? new Date(compactionEntry.timestamp).getTime() : undefined,
+        })) {
             return false;
         }
-        // Case 1: Overflow - LLM returned context overflow error
-        if ((sameModel || visionRouteOverflow) && isContextOverflow(assistantMessage, contextWindow)) {
-            if (this._overflowRecoveryAttempted) {
+        const contextWindow = this.model?.contextWindow ?? 0;
+        // Case 1: Overflow - LLM returned context overflow error. Only counts when
+        // the failing message belongs to the session model — or to the auto-routed
+        // vision model while the session model is text-only.
+        if (isSessionModelOverflow({
+            message: assistantMessage,
+            contextWindow,
+            sessionProvider: this.model?.provider,
+            sessionModelId: this.model?.id,
+            sessionInputs: this.model?.input,
+        })) {
+            if (this._overflowRecoveryAttempts >= MAX_OVERFLOW_RECOVERY_ATTEMPTS) {
                 this._emit({
                     type: "compaction_end",
                     reason: "overflow",
                     result: undefined,
                     aborted: false,
                     willRetry: false,
-                    errorMessage: "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.",
+                    errorMessage: "Context overflow recovery failed after two staged compact-and-retry attempts. Reduce the latest input or switch to a model with a larger effective context window.",
                 });
                 return false;
             }
-            this._overflowRecoveryAttempted = true;
+            this._overflowRecoveryAttempts++;
             // 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)
             const messages = this.agent.state.messages;
@@ -3026,11 +2987,24 @@ export class AgentSession {
         }
         return false;
     }
+    _overflowCompactionSettings(settings, attempt) {
+        if (attempt < MAX_OVERFLOW_RECOVERY_ATTEMPTS)
+            return settings;
+        return {
+            ...settings,
+            reserveTokens: Math.min(settings.reserveTokens, OVERFLOW_RECOVERY_EMERGENCY_TOKENS),
+            reservedOutputTokens: Math.min(settings.reservedOutputTokens ?? settings.reserveTokens, OVERFLOW_RECOVERY_EMERGENCY_TOKENS),
+            keepRecentTokens: Math.min(settings.keepRecentTokens, OVERFLOW_RECOVERY_EMERGENCY_TOKENS),
+        };
+    }
     /**
      * Internal: Run auto-compaction with events.
      */
     async _runAutoCompaction(reason, willRetry, emergency = reason === "overflow" || this._thresholdCompactionEmergency) {
-        const settings = this.settingsManager.getCompactionSettings();
+        const configuredSettings = this.settingsManager.getCompactionSettings();
+        const settings = reason === "overflow"
+            ? this._overflowCompactionSettings(configuredSettings, this._overflowRecoveryAttempts)
+            : configuredSettings;
         this._emit({ type: "compaction_start", reason });
         this._autoCompactionAbortController = new AbortController();
         try {
@@ -3666,25 +3640,12 @@ export class AgentSession {
     // =========================================================================
     // Auto-Retry
     // =========================================================================
-    _isNonRetryableProviderLimitError(errorMessage) {
-        return /GoUsageLimitError|FreeUsageLimitError|Monthly usage limit reached|available balance|insufficient_quota|out of budget|quota exceeded|billing/i.test(errorMessage);
-    }
     /**
      * Check if an error is retryable (overloaded, rate limit, server errors).
      * Context overflow errors are NOT retryable (handled by compaction instead).
      */
     _isRetryableError(message) {
-        if (message.stopReason !== "error" || !message.errorMessage)
-            return false;
-        // Context overflow is handled by compaction, not retry
-        const contextWindow = this.model?.contextWindow ?? 0;
-        if (isContextOverflow(message, contextWindow))
-            return false;
-        const err = message.errorMessage;
-        if (this._isNonRetryableProviderLimitError(err))
-            return false;
-        // Shared contract with provider-resilience.ts (Fable safety stop, K3 orphan tool_call_id, terminated).
-        return isTransientProviderErrorMessage(err);
+        return isRetryableAssistantError(message, this.model?.contextWindow ?? 0);
     }
     /**
      * Retry policy + callbacks shared by compaction and branch-summary summarization calls.
@@ -3721,8 +3682,12 @@ export class AgentSession {
     /** Eject sticky safety model at prompt boundary (session resume / leftover default). */
     async _ejectStickySafetyModelIfNeeded() {
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        if (!resilience.blockStickySafetyModels)
+        if (!shouldEjectStickySafetyModel({
+            blockStickySafetyModels: resilience.blockStickySafetyModels,
+            modelPinned: this._modelPinned,
+        })) {
             return;
+        }
         const current = this.model;
         if (!current || !isStickySafetyModel(current.id, current.provider))
             return;
@@ -3750,19 +3715,28 @@ export class AgentSession {
      */
     async _maybeFailoverFromSafetyStop(message) {
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        if (!resilience.autoFailoverOnSafetyStop)
+        if (!shouldHonorSafetyFailover({
+            autoFailoverOnSafetyStop: resilience.autoFailoverOnSafetyStop,
+            modelPinned: this._modelPinned,
+            modelId: this.model?.id,
+            provider: this.model?.provider,
+        })) {
             return undefined;
-        if (!isContentSafetyStopMessage(message.errorMessage))
+        }
+        // Fire on safety-stop FPs AND on billing/quota exhaustion: both mean the
+        // current model cannot finish this turn and same-model retry is useless.
+        if (!isFailoverTriggerError(message.errorMessage)) {
             return undefined;
+        }
         const current = this.model;
         // v10.0-Ω: do NOT gate on isStickySafetyModel(source).
         // claude-opus-5 emits the same stop_reason=refusal FP; same-model retry is useless.
         // v10.3-Ω: mark the model that just refused so we never re-pick it this turn.
         if (current)
-            this._refusedModels.add(`${current.provider}/${current.id}`);
+            this._refusedModels.add(failoverModelKey(current.provider, current.id));
         const pick = pickFailoverCandidate(resilience.failoverCandidates, current ? { provider: current.provider, id: current.id } : undefined, (c) => {
             // Skip any model that already refused/failed this turn → advance the chain.
-            if (this._refusedModels.has(`${c.provider}/${c.id}`))
+            if (this._refusedModels.has(failoverModelKey(c.provider, c.id)))
                 return false;
             const next = this._modelRegistry.find(c.provider, c.id);
             if (!next)
@@ -3780,34 +3754,32 @@ export class AgentSession {
         }
         catch {
             // setModel failed (auth/guard) — blacklist so next retry advances further.
-            this._refusedModels.add(`${pick.provider}/${pick.id}`);
+            this._refusedModels.add(failoverModelKey(pick.provider, pick.id));
             return undefined;
         }
     }
     async _prepareRetry(message) {
         const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled) {
-            return false;
-        }
-        this._retryAttempt++;
-        if (this._retryAttempt > settings.maxRetries) {
-            // Preserve the completed attempt count so post-run handling can emit the final failure.
-            this._retryAttempt--;
+        const maxRetries = retryBudgetForAssistantError(message, settings.maxRetries);
+        const attempt = nextRetryAttempt({
+            enabled: settings.enabled,
+            completedAttempts: this._retryAttempt,
+            maxRetries,
+        });
+        if (attempt === undefined)
             return false;
-        }
+        this._retryAttempt = attempt;
         // Content/safety stop (Fable/Opus/Sonnet): switch model BEFORE delay so retry is not same-model refusal.
         const failoverTo = await this._maybeFailoverFromSafetyStop(message);
         // Safety stops are usually immediate false positives — short delay after failover, full backoff otherwise.
-        const delayMs = failoverTo
-            ? Math.min(400, settings.baseDelayMs)
-            : settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        const delayMs = computeRetryDelayMs(settings.baseDelayMs, attempt, failoverTo !== undefined);
         const errorMessage = failoverTo
             ? `${message.errorMessage || "content/safety stop"} → failover ${failoverTo}`
             : message.errorMessage || "Unknown error";
         this._emit({
             type: "auto_retry_start",
-            attempt: this._retryAttempt,
-            maxAttempts: settings.maxRetries,
+            attempt,
+            maxAttempts: maxRetries,
             delayMs,
             errorMessage,
         });
@@ -4319,21 +4291,6 @@ export class AgentSession {
         return this._extensionRunner;
     }
 }
-// ---------------------------------------------------------------------------
-// Context budget constants
-// ---------------------------------------------------------------------------
-/** Fraction of contextWindow reserved for model response generation. */
-const RESPONSE_RESERVE_RATIO = 0.2;
-/** Fraction of contextWindow held back as safety margin for token-count imprecision. */
-const SAFETY_MARGIN_RATIO = 0.1;
-// Default prompt budget = contextWindow - responseReserve - safetyMargin.
-// With the defaults above (0.2 + 0.1) this yields ~0.70 of contextWindow, but it
-// stays correct when responseReserve is overridden by model.maxTokens.
-/** Absolute floor for maxPromptTokens — below this the budget is meaningless. */
-const MIN_PROMPT_TOKENS = 4000;
-/** Legacy defaults when no model contextWindow is known. */
-const LEGACY_MAX_PROMPT_TOKENS = 60_000;
-const LEGACY_RESPONSE_RESERVE_TOKENS = 8_192;
 function parsePositiveIntegerEnv(name) {
     const raw = process.env[name];
     if (raw === undefined || raw.trim() === "") {