open-multi-agent-kit 0.96.1 → 0.97.0

package/dist/core/agent-session.js

@@ -44,6 +44,7 @@ import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { assertTextChatModelForCompletion } from "./grok-harness.js";
 import { grokPlaybookAppendForProvider } from "./grok-playbook.js";
+import { captureHostResourceSnapshot } from "./host-resource-snapshot.js";
 import { decideLoadoutAccess } from "./loadout-access-policy.js";
 import { loadMcpServerConfigs } from "./mcp/config.js";
 import { McpManager } from "./mcp/manager.js";
@@ -53,6 +54,7 @@ import { TurnMetricsSink } from "./turn-metrics.js";
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "disable", "disabled"]);
 const MAX_OVERFLOW_RECOVERY_ATTEMPTS = 2;
 const OVERFLOW_RECOVERY_EMERGENCY_TOKENS = 4_096;
+const MAX_RESOURCE_OBSERVATION_JOURNALS = 32;
 function isDisabledEnvValue(value) {
     return value !== undefined && DISABLED_ENV_VALUES.has(value.trim().toLowerCase());
 }
@@ -75,15 +77,21 @@ 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 { createPromptSettlementState, reducePromptSettlement, settlePromptIfReady, } from "./prompt-settlement.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { isQuotaExhaustionMessage, isStickySafetyModel, pickFailoverCandidate, resolveProviderResilience, shouldEjectStickySafetyModel, shouldHonorSafetyFailover, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { isQuotaExhaustionMessage, isStickySafetyModel, isUpstreamUnavailableMessage, pickFailoverCandidate, resolveFailoverCandidates, resolveProviderResilience, sameModelRouteCandidates, 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";
 import { getRepositoryRouterLearningPaths } from "./repository-learning-scope.js";
+import { decideResourceAdmission } from "./resource-admission.js";
+import { resolveResourceGovernorSettings } from "./resource-governor-settings.js";
+import { admissionObservationFacts, classificationObservationFacts, ResourceObservationJournal, settledObservationFacts, snapshotObservationFacts, soundObservationFacts, } from "./resource-observation-journal.js";
+import { decideResourceSafetyGate, RESOURCE_PRESSURE_REQUIRED_ACTION } from "./resource-safety-gate.js";
 import { appendRouterFeedbackRecord, ROUTER_FEEDBACK_LEVELS, } from "./router-feedback-collector.js";
 import { RunJournalStore } from "./run-journal-store.js";
+import { RunResourceLeaseController } from "./run-resource-lease.js";
 import { SessionBashRuntime } from "./session-bash-runtime.js";
 import { SessionBashService } from "./session-bash-service.js";
 import { SessionCompactionService } from "./session-compaction-service.js";
@@ -98,6 +106,8 @@ import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { createVerifiedBashOperations } from "./verified-bash-adapter.js";
 import { resolveSessionWorkspaceScope } from "./verified-bash-runtime.js";
+import { classifyWorkloadCommand } from "./workload-classifier.js";
+import { WorkloadPermitError, WorkloadPermitPool } from "./workload-permit-pool.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -356,6 +366,14 @@ export class AgentSession {
     _runJournalStore;
     _ownedSessionOwnerLease;
     _activeRunId = null;
+    // Resource governor (roadmap M2): lease controller owns the temporary tool
+    // cap for governed runs; the last decision backs the §19.4 read-only API.
+    _resourceLeaseController;
+    _resourceObservations = null;
+    _resourceObservationJournals = new Map();
+    _latestResourcePromptRunId = null;
+    _lastResourceAdmission = null;
+    _workloadPermitPool;
     _pendingRuntimeTerminationCause;
     _activeRunToolTermination;
     _lastTermination;
@@ -436,6 +454,7 @@ export class AgentSession {
             isStreaming: () => this.isStreaming,
             pushMessage: (message) => this.agent.state.messages.push(message),
             appendMessage: (message) => this.sessionManager.appendMessage(message),
+            acquireResourcePermit: (command, signal) => this._acquireBashResourcePermit(command, signal),
         });
         this._compactionService = new SessionCompactionService({
             sessionManager: this.sessionManager,
@@ -605,6 +624,12 @@ export class AgentSession {
         if (/auth|unauthori[sz]ed|forbidden|invalid.?api.?key|no api key|401|403|\/login/i.test(text)) {
             return { area: "provider", code: "auth" };
         }
+        // Gateway/upstream 5xx and dropped streams are transport failures, not
+        // transcript-shape problems. Classify as network so the guidance points to
+        // retry/model-switch instead of the protocol sanitize path.
+        if (isUpstreamUnavailableMessage(text)) {
+            return { area: "provider", code: "network" };
+        }
         // 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)) {
@@ -629,6 +654,9 @@ export class AgentSession {
         if (/auth|api key|unauthori[sz]ed|forbidden|401|403|\/login/i.test(message)) {
             return { area: "provider", code: "auth" };
         }
+        if (isUpstreamUnavailableMessage(message)) {
+            return { area: "provider", code: "network" };
+        }
         if (/context.+overflow|context window|too many tokens/i.test(message)) {
             return { area: "provider", code: "context_overflow" };
         }
@@ -1111,6 +1139,11 @@ export class AgentSession {
         }
         else if (event.type === "agent_end") {
             await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
+            // `agent_end` fires once per attempt. Extensions that release per-run
+            // state need the boundary no retry follows, so mark it explicitly.
+            if (!this._willRetryAfterAgentEnd(event)) {
+                await this._extensionRunner.emit({ type: "agent_settled", messages: event.messages });
+            }
         }
         else if (event.type === "turn_start") {
             this._turnMetricsState = {
@@ -1627,7 +1660,15 @@ export class AgentSession {
         this._promptCacheKey = nextKey;
         this._promptCacheStablePrefixCharacters = boundary ?? 0;
     }
+    _getDefaultActiveSkills() {
+        const trustedSkillNames = new Set(this._resourceLoader
+            .getSkills()
+            .skills.filter((skill) => skill.sourceInfo.scope === "user")
+            .map((skill) => skill.name));
+        return this.settingsManager.getDefaultActiveSkills().filter((name) => trustedSkillNames.has(name));
+    }
     _rebuildSystemPrompt(toolNames, model = this.model) {
+        const defaultActiveSkills = this._getDefaultActiveSkills();
         const assembled = assembleSessionSystemPrompt({
             cwd: this._cwd,
             toolNames,
@@ -1638,6 +1679,8 @@ export class AgentSession {
             appendSystemPrompt: this._resourceLoader.getAppendSystemPrompt(),
             providerAppend: grokPlaybookAppendForProvider(model?.provider),
             skills: this._resourceLoader.getSkills().skills,
+            activeSkillNames: defaultActiveSkills,
+            activeSkillSource: defaultActiveSkills.length > 0 ? "settings" : undefined,
             contextFiles: selectContextFilesForModel(this._resourceLoader.getAgentsFiles().agentsFiles, model),
             contextBudget: this._getContextBudgetOptions(undefined, model),
         });
@@ -1649,6 +1692,15 @@ export class AgentSession {
     // Prompting
     // =========================================================================
     async _runAgentPrompt(messages) {
+        // One identity per top-level run (§16.2): internal retries and
+        // continuations inside this call share it, as does the resource lease.
+        const promptRunId = `prompt-run-${randomUUID()}`;
+        const startedAtEpochMs = Date.now();
+        // Roadmap M2: the lease spans the whole run including internal retries
+        // and continuations, so they share one admission decision (§8.3).
+        const resourceLease = await this._beginResourceGovernedRun(promptRunId);
+        const resourceObservations = this._resourceObservationJournals.get(promptRunId) ?? null;
+        let outcome = "completed";
         try {
             await this.agent.prompt(messages);
             while (await this._handlePostAgentRun()) {
@@ -1656,11 +1708,251 @@ export class AgentSession {
             }
         }
         catch (error) {
+            outcome =
+                this._userAbortRequested || (error instanceof Error && /abort/i.test(error.message)) ? "aborted" : "failed";
             this._publishRuntimeFailure(error);
             throw error;
         }
         finally {
+            if (resourceLease !== null) {
+                // Generation-safe: a stale release after another run acquired the
+                // lease is a no-op instead of clobbering the newer cap (§8.1).
+                this._resourceLeaseController?.release(resourceLease);
+                resourceObservations?.record("resource_lease_released_v1", { promptRunId });
+            }
             this._flushPendingBashMessages();
+            // §16.4 (M4): settle only after every in-run continuation drained.
+            this._emitPromptSettledIfReady({ promptRunId, startedAtEpochMs, outcome, resourceObservations });
+        }
+    }
+    /**
+     * Emit `prompt_settled` when the §16.4 conditions hold. Called exactly
+     * once per promptRunId (from `_runAgentPrompt`'s finally), so the same
+     * run can never emit twice; late-queued messages block emission
+     * conservatively — the continuation run settles under its own id.
+     * Settlement is a UX signal only and must never affect the run (§16.1).
+     */
+    _emitPromptSettledIfReady(input) {
+        try {
+            let state = createPromptSettlementState(input.promptRunId, input.startedAtEpochMs);
+            state = reducePromptSettlement(state, { kind: "terminal", outcome: input.outcome });
+            if (this.isStreaming) {
+                state = reducePromptSettlement(state, { kind: "tool", delta: 1 });
+            }
+            if (this.agent.hasQueuedMessages()) {
+                state = reducePromptSettlement(state, { kind: "continuation", delta: 1 });
+            }
+            const settled = settlePromptIfReady(state, Date.now());
+            if (settled.event !== null) {
+                input.resourceObservations?.record("prompt_settled_v1", settledObservationFacts(settled.event));
+                this._emit(settled.event);
+            }
+        }
+        catch {
+            // Never let settlement bookkeeping break a run.
+        }
+    }
+    /**
+     * Resource governor preflight for one top-level run (roadmap §8, §25.3 M2).
+     *
+     * - `off`: nothing; v0.96.1 observable behavior is preserved.
+     * - `observe` (default): fire-and-forget probe records a decision for the
+     *   §19.4 read-only API; the cap never changes and the prompt is never
+     *   delayed. The pending probe is bounded (~cpuSampleMs) and never rejects.
+     * - `adaptive`/`strict`: bounded blocking probe (default 300 ms deadline),
+     *   then a generation-safe lease applies the effective tool cap for this
+     *   run. The caller's `finally` releases it exactly once.
+     *
+     * Never throws: any probe or policy failure leaves this run ungoverned
+     * (§2.1: probe failure must not crash or block the prompt).
+     */
+    async _beginResourceGovernedRun(promptRunId) {
+        try {
+            const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+            if (resolved.mode === "off") {
+                return null;
+            }
+            const resourceObservations = this._openResourceObservations(promptRunId);
+            const probeOptions = {
+                cwd: this._cwd,
+                maxProbeMs: resolved.maxProbeMs,
+                cpuSampleMs: resolved.cpuSampleMs,
+            };
+            // §7.3: Agent.maxToolConcurrency uses undefined for "unlimited"; the
+            // admission contract uses 0 for the same meaning.
+            const configuredCaps = { maxToolConcurrency: this.agent.maxToolConcurrency ?? 0 };
+            if (resolved.mode === "observe") {
+                void captureHostResourceSnapshot(probeOptions)
+                    .then((snapshot) => {
+                    const decision = decideResourceAdmission({
+                        snapshot,
+                        config: resolved.admission,
+                        configuredCaps,
+                    });
+                    if (this._latestResourcePromptRunId === promptRunId) {
+                        this._lastResourceAdmission = decision;
+                    }
+                    resourceObservations?.record("resource_snapshot_v1", snapshotObservationFacts(snapshot));
+                    resourceObservations?.record("resource_admission_v1", admissionObservationFacts(decision));
+                })
+                    .catch(() => { });
+                return null;
+            }
+            const snapshot = await captureHostResourceSnapshot(probeOptions);
+            const decision = decideResourceAdmission({ snapshot, config: resolved.admission, configuredCaps });
+            if (this._latestResourcePromptRunId === promptRunId) {
+                this._lastResourceAdmission = decision;
+            }
+            resourceObservations?.record("resource_snapshot_v1", snapshotObservationFacts(snapshot));
+            resourceObservations?.record("resource_admission_v1", admissionObservationFacts(decision));
+            this._resourceLeaseController ??= new RunResourceLeaseController({
+                getCap: () => this.agent.maxToolConcurrency,
+                setCap: (cap) => {
+                    this.agent.maxToolConcurrency = cap;
+                },
+            });
+            const lease = this._resourceLeaseController.acquire({ promptRunId, decision });
+            resourceObservations?.record("resource_lease_acquired_v1", {
+                decisionId: decision.decisionId,
+                appliedToolCap: decision.maxToolConcurrency,
+            });
+            return lease;
+        }
+        catch {
+            return null;
+        }
+    }
+    _openResourceObservations(promptRunId) {
+        this._latestResourcePromptRunId = promptRunId;
+        try {
+            const journal = ResourceObservationJournal.open(this._cwd, promptRunId);
+            this._resourceObservations = journal;
+            this._resourceObservationJournals.set(promptRunId, journal);
+            while (this._resourceObservationJournals.size > MAX_RESOURCE_OBSERVATION_JOURNALS) {
+                const oldestPromptRunId = this._resourceObservationJournals.keys().next().value;
+                if (oldestPromptRunId === undefined)
+                    break;
+                this._resourceObservationJournals.delete(oldestPromptRunId);
+            }
+            return journal;
+        }
+        catch {
+            this._resourceObservations = null;
+            this._resourceObservationJournals.delete(promptRunId);
+            return null;
+        }
+    }
+    /** §20.2: record the TUI-side completion sound result in its originating run journal. */
+    recordCompletionSoundResult(promptRunId, result) {
+        const journal = this._resourceObservationJournals.get(promptRunId);
+        journal?.record("completion_sound_result_v1", soundObservationFacts(result));
+        this._resourceObservationJournals.delete(promptRunId);
+        if (this._latestResourcePromptRunId === promptRunId) {
+            this._latestResourcePromptRunId = null;
+            if (this._resourceObservations === journal)
+                this._resourceObservations = null;
+        }
+    }
+    /** §19.4 read-only SDK surface: the most recent resource admission decision, if any. */
+    getCurrentResourceAdmission() {
+        return this._lastResourceAdmission;
+    }
+    /** §19.4 read-only SDK surface: capture a fresh host resource snapshot. */
+    async getHostResourceSnapshot() {
+        const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+        return captureHostResourceSnapshot({
+            cwd: this._cwd,
+            maxProbeMs: resolved.maxProbeMs,
+            cpuSampleMs: resolved.cpuSampleMs,
+        });
+    }
+    /** §19.4 read-only SDK surface: shared workload permit pool state, if any. */
+    getWorkloadPermitSnapshot() {
+        return this._workloadPermitPool?.snapshot() ?? null;
+    }
+    /**
+     * §14.1 shared-budget seam: child subagents must reuse this instance
+     * instead of creating a private pool (host oversubscription). The live
+     * child launcher wiring lands in M6.
+     */
+    get workloadPermitPool() {
+        this._workloadPermitPool ??= new WorkloadPermitPool();
+        return this._workloadPermitPool;
+    }
+    /**
+     * Resource safety gate for the bash boundary (roadmap §9.4/§11, M3).
+     * Runs only in adaptive/strict mode with a recorded admission decision;
+     * observe/off keep v0.96.1 behavior. Never throws: gate machinery
+     * failures leave the command ungated (§2.1), while computed block
+     * verdicts and permit rejections return a bounded §11.3 payload.
+     */
+    async _acquireBashResourcePermit(command, signal) {
+        try {
+            const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+            if (resolved.mode !== "adaptive" && resolved.mode !== "strict") {
+                return {};
+            }
+            const decision = this._lastResourceAdmission;
+            if (decision === null) {
+                return {};
+            }
+            const classification = classifyWorkloadCommand(command);
+            this._resourceObservations?.record("workload_classification_v1", classificationObservationFacts(classification));
+            const verdict = decideResourceSafetyGate({ commandSafety: "allowed", classification, decision });
+            if (verdict.kind === "allow") {
+                return {};
+            }
+            if (verdict.kind === "block") {
+                return { blocked: JSON.stringify(verdict.block) };
+            }
+            this._workloadPermitPool ??= new WorkloadPermitPool({ capacity: decision.maxHeavyProcesses });
+            const pool = this._workloadPermitPool;
+            pool.setCapacity(decision.maxHeavyProcesses);
+            const waitStartedMs = Date.now();
+            this._resourceObservations?.record("workload_permit_wait_v1", {
+                workloadClass: classification.workloadClass,
+                weight: verdict.weight,
+            });
+            try {
+                const permit = await pool.acquire({
+                    requestId: `bash-${randomUUID()}`,
+                    promptRunId: this._resourceLeaseController?.activeLease?.promptRunId ?? "unleased",
+                    workloadClass: classification.workloadClass,
+                    weight: verdict.weight,
+                    signal,
+                    // Bounded §10.3 timeout-aware wait; a settings knob can follow later.
+                    timeoutMs: 60_000,
+                });
+                this._resourceObservations?.record("workload_permit_acquired_v1", {
+                    workloadClass: classification.workloadClass,
+                    weight: verdict.weight,
+                    waitMs: Date.now() - waitStartedMs,
+                });
+                return {
+                    release: () => {
+                        permit.release();
+                        this._resourceObservations?.record("workload_permit_released_v1", {
+                            workloadClass: classification.workloadClass,
+                            weight: verdict.weight,
+                        });
+                    },
+                };
+            }
+            catch (error) {
+                const code = error instanceof WorkloadPermitError ? error.code : "queue_overflow";
+                return {
+                    blocked: JSON.stringify({
+                        kind: "resource_pressure",
+                        pressure: decision.pressure,
+                        action: "defer-heavy",
+                        reasonCodes: [...decision.reasons, `resource.permit.${code}`],
+                        requiredAction: RESOURCE_PRESSURE_REQUIRED_ACTION,
+                    }),
+                };
+            }
+        }
+        catch {
+            return {};
         }
     }
     async _handlePostAgentRun() {
@@ -1702,8 +1994,13 @@ export class AgentSession {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let currentText = redactSensitiveText(text);
-        let promptActiveSkillNames = [...(options?.activeSkillNames ?? [])];
-        let promptActiveSkillSource = options?.activeSkillSource;
+        const defaultActiveSkills = this._getDefaultActiveSkills();
+        let promptActiveSkillNames = mergePromptActiveSkillNames(defaultActiveSkills, options?.activeSkillNames ?? []);
+        let promptActiveSkillSource = defaultActiveSkills.length > 0
+            ? options?.activeSkillSource
+                ? `settings+${options.activeSkillSource}`
+                : "settings"
+            : options?.activeSkillSource;
         let isBangSkillInvocation = false;
         if (expandPromptTemplates) {
             const bangInvocation = parseBangInvocation(text, {
@@ -1715,7 +2012,8 @@ export class AgentSession {
                     ? `/skill:${bangInvocation.skillName} ${bangInvocation.prompt}`
                     : `/skill:${bangInvocation.skillName}`;
                 promptActiveSkillNames = mergePromptActiveSkillNames(promptActiveSkillNames, bangInvocation.activeSkillNames);
-                promptActiveSkillSource = bangInvocation.source;
+                promptActiveSkillSource =
+                    defaultActiveSkills.length > 0 ? `settings+${bangInvocation.source}` : bangInvocation.source;
             }
         }
         let messages;
@@ -1819,8 +2117,8 @@ export class AgentSession {
             const turnSystemPromptOptions = {
                 ...this._baseSystemPromptOptions,
                 contextBudget: this._getContextBudgetOptions(expandedText),
-                ...(promptActiveSkillNames.length > 0 ? { activeSkillNames: promptActiveSkillNames } : {}),
-                ...(promptActiveSkillSource ? { activeSkillSource: promptActiveSkillSource } : {}),
+                activeSkillNames: promptActiveSkillNames,
+                activeSkillSource: promptActiveSkillSource,
             };
             const turnSystemPrompt = buildSystemPromptPlan(turnSystemPromptOptions);
             // Emit before_agent_start extension event
@@ -2702,6 +3000,25 @@ export class AgentSession {
         });
         return model;
     }
+    /**
+     * Authenticated failover candidates for compaction summarization, in
+     * resilience-chain order, excluding the primary compaction model itself.
+     * Used when the primary model's quota is exhausted (same-model retry is
+     * useless until reset; another provider can still save the compaction).
+     */
+    _compactionFailoverModels(primary) {
+        const candidates = resolveFailoverCandidates(this.settingsManager.getProviderResilienceSettings());
+        const available = this._modelRegistry.getAvailable();
+        const models = [];
+        for (const candidate of candidates) {
+            if (candidate.provider === primary.provider && candidate.id === primary.id)
+                continue;
+            const resolved = available.find((m) => m.provider === candidate.provider && m.id === candidate.id);
+            if (resolved)
+                models.push(resolved);
+        }
+        return models;
+    }
     /**
      * Manually compact the session context.
      * Aborts current agent operation first.
@@ -2762,7 +3079,7 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const result = await compact(preparation, compactionModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason: "manual" }));
+                const result = await compact(preparation, compactionModel, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason: "manual" }), this._compactionFailoverModels(compactionModel));
                 summary = result.summary;
                 firstKeptEntryId = result.firstKeptEntryId;
                 tokensBefore = result.tokensBefore;
@@ -2805,6 +3122,8 @@ export class AgentSession {
                 compactionCode = "aborted";
             else if (stale)
                 compactionCode = "stale";
+            else if (isQuotaExhaustionMessage(message))
+                compactionCode = "quota_exhausted";
             const timestamp = new Date().toISOString();
             this._publishTermination(classifySessionTermination({
                 sessionId: this.sessionId,
@@ -2858,7 +3177,7 @@ export class AgentSession {
     /**
      * Effective context window for the upcoming turn.
      * Image-bearing turns with a text-only session model are auto-routed to the
-     * vision model (gpt-5.6-luna, 400K) — that window is the real limit. Text-only
+     * vision model (gpt-5.6-luna, 1M) — that window is the real limit. Text-only
      * turns keep the session model's (typically much larger) window.
      */
     _effectiveTurnContextWindow(pendingMessages, sessionWindow) {
@@ -3093,7 +3412,7 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const compactResult = await compact(preparation, compactionModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }));
+                const compactResult = await compact(preparation, compactionModel, apiKey, headers, undefined, this._autoCompactionAbortController.signal, this.thinkingLevel, this.agent.streamFn, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), this._compactionFailoverModels(compactionModel));
                 summary = compactResult.summary;
                 firstKeptEntryId = compactResult.firstKeptEntryId;
                 tokensBefore = compactResult.tokensBefore;
@@ -3708,6 +4027,41 @@ export class AgentSession {
         // setModel itself blocks sticky targets, not sources — safe.
         await this.setModel(next);
     }
+    /**
+     * Rotate to another authenticated provider route serving the SAME model
+     * family (e.g. openrouter/stealth/ox-alpha ↔ opencode-go/ox-alpha-free ↔
+     * opencode/x-preview-f-free). Used when the current route fails with an
+     * upstream availability error — same-model retry would hammer a dead
+     * endpoint while the identical model is one route away. Visited and
+     * unauthenticated routes are marked in {@link _refusedModels} so repeat
+     * failures advance the rotation within the turn.
+     */
+    async _maybeRotateModelRoutes() {
+        const current = this.model;
+        if (!current)
+            return undefined;
+        const candidates = sameModelRouteCandidates(current, this._modelRegistry.getAvailable());
+        for (const candidate of candidates) {
+            const key = failoverModelKey(candidate.provider, candidate.id);
+            if (this._refusedModels.has(key))
+                continue;
+            const next = this._modelRegistry.find(candidate.provider, candidate.id);
+            if (!next || !this._modelRegistry.hasConfiguredAuth(next)) {
+                this._refusedModels.add(key);
+                continue;
+            }
+            try {
+                await this.setModel(next);
+                // The old route just failed upstream — keep it out of this turn's retries.
+                this._refusedModels.add(failoverModelKey(current.provider, current.id));
+                return `${next.provider}/${next.id}`;
+            }
+            catch {
+                this._refusedModels.add(key);
+            }
+        }
+        return undefined;
+    }
     /**
      * Content/safety stops (stop_reason=refusal) are often false positives on coding turns
      * for Fable AND Claude Opus/Sonnet. Retrying the same model usually reprints the refusal —
@@ -3769,12 +4123,19 @@ export class AgentSession {
         if (attempt === undefined)
             return false;
         this._retryAttempt = attempt;
+        // Upstream-unavailable (gateway 5xx / dropped stream): rotate to another
+        // authenticated route of the SAME model family so the retry lands on a
+        // live endpoint instead of hammering the dead one.
+        const rotatedTo = isUpstreamUnavailableMessage(message.errorMessage)
+            ? await this._maybeRotateModelRoutes()
+            : undefined;
         // Content/safety stop (Fable/Opus/Sonnet): switch model BEFORE delay so retry is not same-model refusal.
         const failoverTo = await this._maybeFailoverFromSafetyStop(message);
+        const switchedVia = failoverTo ? `failover ${failoverTo}` : rotatedTo ? `route ${rotatedTo}` : undefined;
         // Safety stops are usually immediate false positives — short delay after failover, full backoff otherwise.
-        const delayMs = computeRetryDelayMs(settings.baseDelayMs, attempt, failoverTo !== undefined);
-        const errorMessage = failoverTo
-            ? `${message.errorMessage || "content/safety stop"} → failover ${failoverTo}`
+        const delayMs = computeRetryDelayMs(settings.baseDelayMs, attempt, switchedVia !== undefined);
+        const errorMessage = switchedVia
+            ? `${message.errorMessage || "content/safety stop"} → ${switchedVia}`
             : message.errorMessage || "Unknown error";
         this._emit({
             type: "auto_retry_start",