mixdog 1.2.0 → 1.2.2

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-request/initial-status.mjs

@@ -2,9 +2,23 @@
 // sampled: a 429 becomes a typed quota error and a transient status a
 // retryable error; both drain the response and release its abort wiring so
 // re-issuing the POST is safe.
-import { noteFastModeCapacityError } from '../anthropic-fast-mode.mjs';
+import { fastModeDowngraded, noteFastModeCapacityError } from '../anthropic-fast-mode.mjs';
+import { applyAnthropicErrorContract, retryAfterMsFromHeaders } from '../anthropic-error-contract.mjs';
 import { headerValue } from '../retry-classification.mjs';
-import { classifyError, retryAfterMsFromError } from '../retry-classifier.mjs';
+import { classifyError } from '../retry-classifier.mjs';
+
+// Anthropic's exact official revoked-token 403 body; any other 403 is an
+// ordinary permission/policy refusal and stays terminal.
+const REVOKED_TOKEN_MARKER = 'OAuth token has been revoked';
+
+/**
+ * True when a rejected initial response is one a forced credential refresh can
+ * fix: every 401, and only the exact revoked-token 403 signature. Shared by
+ * the streaming request and the non-streaming fallback.
+ */
+export function isRefreshableAuthRejection(status, bodyText) {
+  return status === 401 || (status === 403 && String(bodyText ?? '').includes(REVOKED_TOKEN_MARKER));
+}
 
 // A subscription-window refusal carries these unified quota headers. A 429
 // without them is an entitlement/routing refusal or a capacity blip — the
@@ -31,16 +45,13 @@ function formatRetryAfter(ms) {
 }
 
 export function anthropicQuotaError(status, headers, bodyText = '') {
-  const retryAfterMs = retryAfterMsFromError({ headers, response: { headers } });
+  const retryAfterMs = retryAfterMsFromHeaders(headers);
   const retryAfter = formatRetryAfter(retryAfterMs);
   const detail = bodyText ? `: ${String(bodyText).slice(0, 200)}` : '';
   const retry = retryAfter ? ` retryAfter=${retryAfter}` : '';
   const quota = hasQuotaHeaders(headers);
   const err = new Error(`Anthropic OAuth API ${status} ${quota ? 'quota/rate limit' : 'request rejected'}${retry}${detail}`);
   err.name = quota ? 'ProviderQuotaError' : 'ProviderRequestRejectedError';
-  err.code = quota ? 'PROVIDER_QUOTA' : 'PROVIDER_REQUEST_REJECTED';
-  err.httpStatus = status;
-  err.status = status;
   err.headers = headers;
   err.response = { status, headers };
   err.retryAfterMs = retryAfterMs;
@@ -50,7 +61,7 @@ export function anthropicQuotaError(status, headers, bodyText = '') {
   // SSE parsing can expose text or a tool call. It is therefore safe for the
   // request-local withRetry loop. Mid-stream paths stamp unsafeToRetry when
   // output/tool exposure actually occurs.
-  return err;
+  return applyAnthropicErrorContract(err, { status, headers, bodyText });
 }
 
 export async function judgeInitialStatus(result, requestBody, { provider, cleanupCancelHandler }) {
@@ -71,26 +82,41 @@ export async function judgeInitialStatus(result, requestBody, { provider, cleanu
     // in-loop; a drained or unavailable fast pool says nothing about
     // standard-speed capacity, so `speed` is dropped and the error is
     // flagged for a single standard-speed replay by the caller.
-    const fastDecision = noteFastModeCapacityError(
-      { httpStatus: status, headers: result?.response?.headers, message: quotaText },
-      { fast: requestBody?.speed === 'fast' }
-    );
-    const fastDowngraded = fastDecision === 'downgrade' || fastDecision === 'disabled';
-    if (fastDowngraded) delete requestBody.speed;
+    const fastDowngraded = dropFastSpeed(requestBody, status, result?.response?.headers, quotaText);
     throw Object.assign(anthropicQuotaError(status, result?.response?.headers, provider.scrubTokens(quotaText)), {
       initialResponseError: true,
       fastDowngraded,
     });
   }
+  let overloadText = '';
+  try {
+    overloadText = await result.response.text();
+  } catch {}
+  release();
+  // A drained fast pool (529) is replayed at standard speed within the same
+  // attempt, exactly like a fast-pool 429, instead of waiting out its window.
+  const fastDowngraded = dropFastSpeed(requestBody, status, result?.response?.headers, overloadText);
   const err = new Error(`Anthropic OAuth API ${status}`);
-  err.httpStatus = status;
-  err.status = status;
   err.headers = result?.response?.headers;
   err.response = { status, headers: result?.response?.headers };
   err.initialResponseError = true;
-  try {
-    await result.response.text();
-  } catch {}
-  release();
-  throw err;
+  err.fastDowngraded = fastDowngraded;
+  throw applyAnthropicErrorContract(err, {
+    status,
+    headers: result?.response?.headers,
+    bodyText: provider.scrubTokens(overloadText),
+  });
+}
+
+// Records a fast-pool capacity refusal; on an explicit downgrade/disable the
+// request drops `speed` and the caller replays once at standard speed. Any
+// other verdict ('ignored', 'retry-fast') leaves the request untouched.
+function dropFastSpeed(requestBody, status, headers, text) {
+  const decision = noteFastModeCapacityError(
+    { httpStatus: status, headers, message: text },
+    { fast: requestBody?.speed === 'fast' }
+  );
+  if (!fastModeDowngraded(decision)) return false;
+  delete requestBody.speed;
+  return true;
 }

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-request.mjs

@@ -11,7 +11,6 @@
 import { traceAgentFetch } from '../agent-trace.mjs';
 import { createAbortController } from '../../../shared/abort-controller.mjs';
 import { notifyCurrentAnthropicRateLimit } from './admission-scheduler.mjs';
-import { noteFastModeCapacityError } from './anthropic-fast-mode.mjs';
 import { noteRequestServiceTier } from '../../../shared/llm/usage-context.mjs';
 import {
   ANTHROPIC_RETRY_BACKOFF_MS,
@@ -21,6 +20,7 @@ import {
   emitProviderRetryStage,
   withRetry,
 } from './retry-classifier.mjs';
+import { ANTHROPIC_MAX_CONSECUTIVE_529 } from './retry-backoff.mjs';
 import { postMessages } from './anthropic-oauth-request/gzip-post.mjs';
 import { removeAbortListener, wireRequestAbort } from './anthropic-oauth-request/abort-wiring.mjs';
 import { judgeInitialStatus } from './anthropic-oauth-request/initial-status.mjs';
@@ -38,6 +38,7 @@ export { anthropicQuotaError } from './anthropic-oauth-request/initial-status.mj
  * @param {AbortSignal|null} deps.totalSignal  session-lifetime pass-through
  * @param {(requestBody: object) => string} deps.betaHeadersFor
  * @param {((stage: string) => void)|null} deps.onStageChange
+ * @param {{ state: { consecutive529Errors: number } }|null} [deps.overload]  the send's shared overload counter
  */
 export function createAnthropicOAuthRequest({
   provider,
@@ -48,8 +49,10 @@ export function createAnthropicOAuthRequest({
   totalSignal,
   betaHeadersFor,
   onStageChange,
+  overload = null,
 }) {
   const requestTimeoutMs = anthropicRequestTimeoutMs();
+  const isEnterprise = String(provider?.credentials?.subscriptionType || '').toLowerCase() === 'enterprise';
   const cleanupCancelHandler = (handler) => removeAbortListener(totalSignal, handler);
 
   const doRequest = async (accessToken, requestSignal = null, requestBody = body) => {
@@ -100,7 +103,7 @@ export function createAnthropicOAuthRequest({
         try {
           await judgeInitialStatus(result, requestBody, { provider, cleanupCancelHandler });
         } catch (err) {
-          // Fast-pool 429 before any byte was sampled: `speed` is already
+          // Fast-pool 429/529 before any byte was sampled: `speed` is already
           // dropped, so replay once at standard speed within this attempt.
           if (err?.fastDowngraded !== true) throw err;
           const replay = await doRequestImpl(accessToken, attemptSignal, requestBody);
@@ -118,23 +121,25 @@ export function createAnthropicOAuthRequest({
         // Max/Pro OAuth sessions use subscription quota windows. Claude
         // Code fails their 429s immediately rather than waiting through
         // the API-key/PAYG retry budget (which may carry hours-long
-        // Retry-After values).
-        retry429: false,
+        // Retry-After values). Enterprise bills PAYG-style, so its 429s
+        // are retried like an API key's.
+        retry429: isEnterprise,
         retry529: opts.retry529,
         perAttemptTimeoutMs: requestTimeoutMs,
         perAttemptLabel: 'Anthropic OAuth initial response',
         provider: 'anthropic',
+        // This transport honors the positive x-should-retry override.
+        honorShouldRetryTrue: true,
         model: useModel,
         fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
+        // One overload counter for the send: SSE overloads count toward the
+        // same limit as request-loop 529s.
+        overloadState: overload?.state,
+        overloadFallbackAfter: ANTHROPIC_MAX_CONSECUTIVE_529,
         onRetry: ({ attempt, maxAttempts, lastErr, delayMs, delayReason }) => {
           emitProviderRetryStage(onStageChange, { attempt: attempt + 1, maxAttempts, lastErr, delayMs });
           const status = Number(lastErr?.httpStatus || lastErr?.status || lastErr?.response?.status || 0) || null;
           if (status === 429) notifyCurrentAnthropicRateLimit(lastErr);
-          // Fast capacity exhausted: drop `speed` so the replay runs at
-          // standard speed instead of re-hitting the drained pool.
-          if (requestBody?.speed === 'fast' && noteFastModeCapacityError(lastErr, { fast: true }) !== 'retry-fast') {
-            delete requestBody.speed;
-          }
           const reason = status || lastErr?.code || lastErr?.message || 'network error';
           const suffix = delayReason ? ` (${delayReason})` : '';
           try {

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -42,8 +42,12 @@ import { AnthropicFallbackTriggeredError } from './retry-classifier.mjs';
 import { ANTHROPIC_MAX_MIDSTREAM_RETRIES, parseSSEStream, _classifyMidstreamError } from './anthropic-sse.mjs';
 import { buildAnthropicBetaHeaders, supportsAnthropicFastMode } from './anthropic-betas.mjs';
 import { applyAnthropicServerFallback } from './anthropic-server-fallback.mjs';
-import { fastModeAvailable } from './anthropic-fast-mode.mjs';
+import { fastModeAvailable, fastModeDowngraded, noteFastModeCapacityError } from './anthropic-fast-mode.mjs';
 import { ANTHROPIC_VERSION, anthropicQuotaError, createAnthropicOAuthRequest } from './anthropic-oauth-request.mjs';
+import { isRefreshableAuthRejection } from './anthropic-oauth-request/initial-status.mjs';
+import { applyAnthropicErrorContract } from './anthropic-error-contract.mjs';
+import { adjustMaxTokensForContextOverflow } from './anthropic-max-tokens-recovery.mjs';
+import { announceAnthropicModelFallback, createAnthropicOverloadTracker } from './anthropic-overload-fallback.mjs';
 import { createAnthropicOAuthRecovery } from './anthropic-oauth-recovery.mjs';
 import { createMidState, createMidstreamRecovery } from './anthropic-oauth-midstream.mjs';
 import { assertAnthropicStreamNotEmpty } from './anthropic-midstream-recovery.mjs';
@@ -91,12 +95,6 @@ function logQuiet(line) {
   if (!process.env.MIXDOG_QUIET_PROVIDER_LOG) process.stderr.write(`[anthropic-oauth] ${line}\n`);
 }
 
-function requiresSystemPrefix(model) {
-  // Every Claude OAuth model needs the first-party system prefix for OAuth
-  // pool routing; without it the server answers 429 rate_limit_error "Error".
-  return /^claude-/.test(String(model || '').toLowerCase());
-}
-
 function buildOAuthBetaHeaders(body, { fastMode = false, toolSearch = false, model, opts = {} } = {}) {
   return buildAnthropicBetaHeaders({
     base: usesAnthropicEffortBody(body) ? `${OAUTH_BETA_HEADERS},${EFFORT_CONFIGURATION_BETA}` : OAUTH_BETA_HEADERS,
@@ -114,23 +112,21 @@ function buildOAuthBetaHeaders(body, { fastMode = false, toolSearch = false, mod
 // content (even the prefix concatenated with extra text in the same block)
 // falls into the standard pool and Opus/Sonnet return 429. Splitting into
 // two blocks — [prefix, rest] — keeps both routing and user instructions.
-function buildSystemBlocks(systemMsgs, model, systemTtl, tier3Ttl) {
+function buildSystemBlocks(systemMsgs, systemTtl, tier3Ttl) {
   // systemMsgs is an array of { content, cacheTier } — each non-empty element
   // becomes its own Anthropic content block with its own cache_control
   // breakpoint. Blocks tagged cacheTier:'tier3' (BP3 sessionMarker) take the
   // tier3 TTL; every other block (BP1 baseRules / BP2 stableSystem) takes the
   // system TTL. Invariant: callers must pass an array.
   const items = systemBlockItems(systemMsgs);
-  const gated = requiresSystemPrefix(model);
 
-  const blocks = [];
-  if (gated) {
-    blocks.push({ type: 'text', text: CLAUDE_CODE_SYSTEM_PREFIX });
-  }
+  // Every model on the OAuth route is routed by this prefix block, so it is
+  // sent unconditionally rather than keyed on the model id.
+  const blocks = [{ type: 'text', text: CLAUDE_CODE_SYSTEM_PREFIX }];
   for (let i = 0; i < items.length; i++) {
     let body = items[i].text;
     // Strip a duplicated OAuth system prefix from the first block if present.
-    if (gated && i === 0 && body.startsWith(CLAUDE_CODE_SYSTEM_PREFIX)) {
+    if (i === 0 && body.startsWith(CLAUDE_CODE_SYSTEM_PREFIX)) {
       body = body.slice(CLAUDE_CODE_SYSTEM_PREFIX.length).trim();
       if (!body) continue;
     }
@@ -170,8 +166,8 @@ function buildSystemBlocks(systemMsgs, model, systemTtl, tier3Ttl) {
 //   1. MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS env override, if set, wins outright.
 //   2. Catalog outputTokens (trusted over hardcoded heuristics when present),
 //      clamped to [MAX_TOKENS_FLOOR, safetyCap].
-//   3. Static MAX_TOKENS table / family heuristic fallback when the catalog
-//      has no entry for this model, also clamped to the safety cap.
+//   3. Shared model catalog outputTokens, then the floor, when the live
+//      roster has no entry for this model.
 function resolveMaxTokens(model) {
   return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokens });
 }
@@ -202,7 +198,7 @@ function buildRequestBody(messages, model, tools, sendOpts) {
   // Each system message becomes its own Anthropic content block with its own
   // breakpoint: BP1 baseRules + BP2 stableSystem at ttls.system, BP3
   // sessionMarker (cacheTier:'tier3') at ttls.tier3.
-  const systemBlocks = buildSystemBlocks(systemMsgs, model, ttls?.system, ttls?.tier3);
+  const systemBlocks = buildSystemBlocks(systemMsgs, ttls?.system, ttls?.tier3);
 
   // Message-tail cache budget (4-BP layout + ANTHROPIC_MSG_SLOTS) is shared
   // with anthropic.mjs — see resolveAnthropicMessageCacheSlots.
@@ -480,6 +476,12 @@ export class AnthropicOAuthProvider {
     // totalSignal is therefore a pure pass-through of externalSignal with no timer.
     const totalTimeout = createPassthroughSignal(externalSignal);
     const totalSignal = totalTimeout.signal;
+    // Request-loop 529s and SSE overload events share one counter; at the
+    // limit the configured fallback model takes over the whole send.
+    const overload = createAnthropicOverloadTracker({
+      model: useModel,
+      fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
+    });
     const { requestWithRetry, cleanupCancelHandler } = createAnthropicOAuthRequest({
       provider: this,
       opts,
@@ -487,6 +489,7 @@ export class AnthropicOAuthProvider {
       useModel,
       sessionId,
       totalSignal,
+      overload,
       betaHeadersFor: (requestBody) =>
         buildOAuthBetaHeaders(requestBody, {
           fastMode: this.fastModeBetaHeaderLatched,
@@ -516,24 +519,14 @@ export class AnthropicOAuthProvider {
       recovery,
       onStageChange,
       retry529: opts.retry529 !== false,
+      overload,
     });
 
+    let maxTokensAdjusted = false;
     try {
       for (let attemptIndex = 0; attemptIndex <= ANTHROPIC_MAX_MIDSTREAM_RETRIES; attemptIndex++) {
         let response, controller, cancelHandler;
-        try {
-          ({ response, controller, cancelHandler } = await requestWithRetry(auth.creds.accessToken));
-        } catch (err) {
-          if (err instanceof AnthropicFallbackTriggeredError) {
-            process.stderr.write(`[anthropic-oauth] ${err.message}\n`);
-            return this.send(messages, err.fallbackModel, tools, {
-              ...opts,
-              fallbackModel: undefined,
-              _fallbackTriggered: true,
-            });
-          }
-          throw err;
-        }
+        ({ response, controller, cancelHandler } = await requestWithRetry(auth.creds.accessToken));
 
         // Refresh on 401, and only Anthropic's exact official revoked-token
         // 403 signature. Ordinary permission/policy 403s are terminal.
@@ -541,8 +534,7 @@ export class AnthropicOAuthProvider {
         if (response.status === 401 || response.status === 403) {
           rejectedAuthBody = await response.text().catch(() => '');
         }
-        const revoked403 = response.status === 403 && String(rejectedAuthBody).includes('OAuth token has been revoked');
-        if (response.status === 401 || revoked403) {
+        if (isRefreshableAuthRejection(response.status, rejectedAuthBody)) {
           process.stderr.write(`[anthropic-oauth] ${response.status} — forcing refresh and retrying once\n`);
           cleanupCancelHandler(cancelHandler);
           // Body was drained above; abort closes any remaining transport
@@ -555,6 +547,20 @@ export class AnthropicOAuthProvider {
           rejectedAuthBody = null;
         }
 
+        // "input length and max_tokens exceed context limit": shrink max_tokens
+        // to what the context has room for and replay once.
+        if (response.status === 400 && !maxTokensAdjusted) {
+          rejectedAuthBody = await response.text().catch(() => '');
+          if (adjustMaxTokensForContextOverflow(body, 400, rejectedAuthBody)) {
+            maxTokensAdjusted = true;
+            cleanupCancelHandler(cancelHandler);
+            try {
+              controller?.abort?.();
+            } catch {}
+            ({ response, controller, cancelHandler } = await requestWithRetry(auth.creds.accessToken));
+            rejectedAuthBody = null;
+          }
+        }
         if (!response.ok) {
           cleanupCancelHandler(cancelHandler);
           return await this._resendAfterRejection({
@@ -615,6 +621,18 @@ export class AnthropicOAuthProvider {
         }
       }
       throw midstream.exhaustedError();
+    } catch (err) {
+      // The fallback trigger can surface from the request loop, a mid-stream
+      // overload, or the non-streaming recovery: handle it around the whole
+      // operation, not just the first request.
+      if (!(err instanceof AnthropicFallbackTriggeredError)) throw err;
+      process.stderr.write(`[anthropic-oauth] ${err.message}\n`);
+      announceAnthropicModelFallback(onStageChange, _displayModel(useModel), _displayModel(err.fallbackModel));
+      return await this.send(messages, err.fallbackModel, tools, {
+        ...opts,
+        fallbackModel: undefined,
+        _fallbackTriggered: true,
+      });
     } finally {
       totalTimeout.cleanup();
     }
@@ -632,6 +650,21 @@ export class AnthropicOAuthProvider {
       throw anthropicQuotaError(response.status, response.headers, safeText);
     }
 
+    // An account that cannot use fast mode answers the speed field with a
+    // 400. Fast mode is now off for this process, so replaying the turn once
+    // builds a standard-speed request.
+    if (
+      response.status === 400 &&
+      opts.fast === true &&
+      !opts._fastModeRetry &&
+      fastModeDowngraded(
+        noteFastModeCapacityError({ httpStatus: 400, message: scrubbedText }, { fast: true })
+      )
+    ) {
+      process.stderr.write(`[anthropic-oauth] fast mode is not enabled for this account; retrying at standard speed\n`);
+      return this.send(messages, useModel, tools, { ...opts, _fastModeRetry: true });
+    }
+
     // A newer model that rejects the mid-conversation effort update: switch
     // the updates off for it in this process and replay the turn once
     // without them (the request keeps its turn effort).
@@ -694,9 +727,14 @@ export class AnthropicOAuthProvider {
       return this.send(messages, fallbackModel || model, tools, { ...opts, _modelRetry: true });
     }
     const err = new Error(`Anthropic OAuth API ${response.status}: ${safeText}`);
-    err.status = response.status;
-    err.httpStatus = response.status;
-    throw err;
+    // 413 stays `request_too_large` (a byte/media size refusal) and a 400
+    // "prompt is too long" stays `invalid_request_error`, so the core can tell
+    // a payload it must shrink from a context it can compact.
+    throw applyAnthropicErrorContract(err, {
+      status: response.status,
+      headers: response.headers,
+      bodyText: scrubbedText,
+    });
   }
 
   // Traces + catalog upkeep for a streamed turn, then the empty-stream guard.

package/src/runtime/agent/orchestrator/providers/anthropic-overload-fallback.mjs

@@ -0,0 +1,69 @@
+/**
+ * anthropic-overload-fallback.mjs — one overload counter per logical send,
+ * shared by the request loop (HTTP 529 before a stream exists) and the SSE
+ * parser (`overloaded_error` event after one started). Both reach it through
+ * the same error fields — `status: 529` / `code: 'overloaded_error'` — so a
+ * mix of the two trips the configured fallback model after the same number of
+ * consecutive overloads, instead of each path counting only its own.
+ *
+ * The request loop's counter is withRetry's `overloadState`; this tracker owns
+ * that object, so the SSE path increments the very counter the loop reads.
+ */
+import { ANTHROPIC_MAX_CONSECUTIVE_529 } from './retry-backoff.mjs';
+import { AnthropicFallbackTriggeredError } from './retry-classifier.mjs';
+
+export const OVERLOADED_ERROR_CODE = 'overloaded_error';
+
+/** Consecutive 529s end the request only for API-key (non-subscriber) first-party Opus. */
+export function isTerminalOverloadModel(model) {
+  return /^claude-opus-/.test(String(model || '').trim().toLowerCase());
+}
+
+export function isAnthropicOverloadError(err) {
+  const status = Number(err?.httpStatus || err?.status || err?.response?.status || 0);
+  return status === 529 || String(err?.code || '').toLowerCase() === OVERLOADED_ERROR_CODE;
+}
+
+/**
+ * @param {{ model: string, fallbackModel?: string|null, terminalAtLimit?: boolean }} deps  fallbackModel is
+ *   already undefined when this send IS the fallback (no second hop).
+ */
+export function createAnthropicOverloadTracker({ model, fallbackModel, terminalAtLimit = false }) {
+  const canFallback = Boolean(fallbackModel) && fallbackModel !== model;
+  // Handed to every withRetry of the send as `overloadState`: the request
+  // loop increments this same object on each 529.
+  const state = { consecutive529Errors: 0 };
+  return {
+    state,
+    // Repeated-overload stop, handed to withRetry as `stopAfterRepeated529`: with no
+    // fallback model, API-key Opus stops after repeated 529s. A configured
+    // fallback always wins (the executor checks it first).
+    stopAfterRepeated529: terminalAtLimit && !canFallback,
+    /**
+     * An overload SSE error. Returns the fallback trigger to throw once the
+     * consecutive limit is reached and a fallback model is configured.
+     */
+    noteStreamOverload(err) {
+      state.consecutive529Errors += 1;
+      if (state.consecutive529Errors < ANTHROPIC_MAX_CONSECUTIVE_529) return null;
+      if (canFallback) return new AnthropicFallbackTriggeredError(model, fallbackModel, err);
+      // No fallback model: API-key Opus stops here ("Repeated 529 Overloaded
+      // errors") instead of spending the full budget.
+      if (!terminalAtLimit) return null;
+      err.repeated529 = true;
+      return err;
+    },
+  };
+}
+
+/** Visible model-switch notice on the existing display-only stage channel. */
+export function announceAnthropicModelFallback(onStageChange, fromLabel, toLabel) {
+  if (typeof onStageChange !== 'function') return;
+  try {
+    onStageChange('reconnecting', {
+      message: `${fromLabel} is overloaded — continuing on ${toLabel}`,
+    });
+  } catch {
+    /* display-only */
+  }
+}

package/src/runtime/agent/orchestrator/providers/anthropic-server-fallback.mjs

@@ -6,6 +6,10 @@ function normalizedModelId(value) {
   return typeof raw === 'string' ? raw.trim() : '';
 }
 
+// Kept as an id pattern: no catalog field declares server-side fallback, and
+// `fallbacks` is a beta-gated body field other models reject (a wrong "yes" is
+// a 400, a wrong "no" only skips an optional refusal fallback), so unknown ids
+// stay off.
 export function supportsAnthropicServerFallback(model) {
   const id = normalizeClaudeModelId(normalizedModelId(model));
   return /^claude-(?:opus|fable)-5(?:$|[-@])/.test(id);

package/src/runtime/agent/orchestrator/providers/anthropic-sse.mjs

@@ -109,6 +109,13 @@ function _anthropicSseError(event, labels) {
     err.httpStatus = status;
     err.status = status;
   }
+  // Provider-boundary contract: `code` is the lowercased Anthropic error type
+  // (an overload carries `overloaded_error` + 529, which the overload counter
+  // reads); an untyped `error` frame keeps the generic SSE code. A 413 is a
+  // byte-size refusal, never a prompt-token one.
+  const wireType = typeof type === 'string' ? type.trim().toLowerCase() : '';
+  if (status === 413) err.code = 'request_too_large';
+  else if (wireType && wireType !== 'error') err.code = wireType;
   // Wire-error marker: an error type OUTSIDE the documented enumeration
   // (no status resolved above) default-retries under the shared wire-error
   // contract instead of failing the turn as 'unknown'. Typed statuses and
@@ -162,7 +169,7 @@ function applyAnthropicSseEvent(framedEvent, { turn, watchdogs, state, progress,
         return false;
     }
   } catch (err) {
-    if (err?.code === 'EANTHROPIC_SSE_ERROR') throw err;
+    if (err?.name === 'AnthropicSseError') throw err;
     /* skip malformed events */
     return false;
   }

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -1,6 +1,11 @@
-import { getAgentApiKey } from '../../../shared/provider-api-key.mjs';
+import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
 import { sanitizeToolPairs } from '../session/context-utils.mjs';
 import { AnthropicFallbackTriggeredError } from './retry-classifier.mjs';
+import {
+  announceAnthropicModelFallback,
+  createAnthropicOverloadTracker,
+  isTerminalOverloadModel,
+} from './anthropic-overload-fallback.mjs';
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { createPassthroughSignal } from '../stall-policy.mjs';
 import { createAbortController } from '../../../shared/abort-controller.mjs';
@@ -42,9 +47,19 @@ export class AnthropicProvider {
   constructor(config) {
     this.config = config || {};
     this.name = this.config.name || 'anthropic';
-    this.apiKey = this.config.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+    this.apiKey = resolveProviderApiKey(this.name, this.config) || null;
     this.client = this._createClient(this.apiKey);
   }
+  // Client for the currently resolved key; rebuilt when the key changed since
+  // it was built (e.g. a keyless-constructed instance).
+  _currentClient() {
+    const key = resolveProviderApiKey(this.name, this.config) || null;
+    if (key && key !== this.apiKey) {
+      this.apiKey = key;
+      this.client = this._createClient(key);
+    }
+    return this.client;
+  }
   // Tool-search is a request capability, not an account capability. Keep it
   // off the client defaults and add it only on turns that actually serialize
   // defer_loading tools.
@@ -55,8 +70,10 @@ export class AnthropicProvider {
     const custom = isCustomProviderName(this.name);
     const keyless = custom && this.config.keyless === true;
     const betaHeaders = this.config.disableBetaHeaders || custom ? null : buildAnthropicBetaHeaders();
+    let credentials = { apiKey };
+    if (custom) credentials = { apiKey: keyless ? '' : apiKey || '', authToken: null };
     return new (loadAnthropic())({
-      ...(custom ? { apiKey: keyless ? '' : apiKey || '', authToken: null } : { apiKey }),
+      ...credentials,
       ...(this.config.baseURL ? { baseURL: this.config.baseURL } : {}),
       defaultHeaders: {
         ...(betaHeaders ? { 'anthropic-beta': betaHeaders } : {}),
@@ -68,10 +85,7 @@ export class AnthropicProvider {
   }
   reloadApiKey() {
     try {
-      const newKey =
-        getAgentApiKey(this.name) ||
-        this.config.apiKey ||
-        (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+      const newKey = reloadProviderApiKey(this.name, this.config);
       if (newKey) {
         this.config = { ...(this.config || {}), apiKey: newKey };
         this.apiKey = newKey;
@@ -157,16 +171,24 @@ export class AnthropicProvider {
       } catch {}
     };
 
+    // Request-loop 529s and SSE overload events share one counter; at the
+    // limit the configured fallback model takes over the whole send.
+    const overload = createAnthropicOverloadTracker({
+      model: useModel,
+      fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
+      terminalAtLimit: !isCustomProviderName(this.name) && isTerminalOverloadModel(useModel),
+    });
     // The SDK calls and their initial-response retry policy
     // (anthropic-api-transport.mjs).
     const transport = createAnthropicApiTransport({
-      client: this.client,
+      client: this._currentClient(),
       label: this.name,
       opts,
       useModel,
       params,
       requestHeaders,
       totalSignal,
+      overload,
     });
     // Usage accounting + caller-visible projection, shared by the streaming
     // success path and the non-streaming fallback (anthropic-turn-result.mjs).
@@ -204,8 +226,10 @@ export class AnthropicProvider {
       recovery,
       onStageChange,
       retry529: opts.retry529 !== false,
+      overload,
     });
 
+    let streamingFallbackTried = false;
     try {
       for (let attemptIndex = 0; attemptIndex <= ANTHROPIC_MAX_MIDSTREAM_RETRIES; attemptIndex++) {
         const streamController = createAbortController();
@@ -265,13 +289,13 @@ export class AnthropicProvider {
 
           return buildTurnResult(parseResult);
         } catch (err) {
-          if (err instanceof AnthropicFallbackTriggeredError) {
-            process.stderr.write(`[${this.name}] ${err.message}\n`);
-            return this._doSend(messages, err.fallbackModel, tools, {
-              ...opts,
-              fallbackModel: undefined,
-              _fallbackTriggered: true,
-            });
+          // The fallback trigger is handled around the whole send below.
+          if (err instanceof AnthropicFallbackTriggeredError) throw err;
+          // Gateways that 404 the streaming endpoint but serve non-streaming:
+          // one non-streaming replay (nothing was streamed yet).
+          if (err?.initialResponseError === true && Number(err.status) === 404 && !streamingFallbackTried) {
+            streamingFallbackTried = true;
+            return await recovery.issueNonStreamingFallback(streamController, err);
           }
           // Ordered recovery ladder: canonical outcome stamp, acknowledged
           // non-streaming replay for exposed output, bounded streaming
@@ -291,13 +315,24 @@ export class AnthropicProvider {
         }
       }
       throw midstream.exhaustedError();
+    } catch (err) {
+      // The fallback trigger can surface from the request loop, a mid-stream
+      // overload, or the non-streaming recovery: handle it around the whole
+      // operation, not just the first request.
+      if (!(err instanceof AnthropicFallbackTriggeredError)) throw err;
+      process.stderr.write(`[${this.name}] ${err.message}\n`);
+      announceAnthropicModelFallback(onStageChange, useModel, err.fallbackModel);
+      return await this._doSend(messages, err.fallbackModel, tools, {
+        ...opts,
+        fallbackModel: undefined,
+        _fallbackTriggered: true,
+      });
     } finally {
       totalTimeout.cleanup();
     }
   }
   async listModels() {
-    const apiKey =
-      this.apiKey || this.config?.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+    const apiKey = resolveProviderApiKey(this.name, this.config);
     if (!apiKey) return MODELS;
     try {
       const base = String(this.config?.baseURL || 'https://api.anthropic.com').replace(/\/+$/, '');
@@ -329,6 +364,6 @@ export class AnthropicProvider {
   async isAvailable() {
     // Availability probes must not spend tokens or depend on a live
     // network. Dispatch owns authentication validation and 401 reload.
-    return !!(this.apiKey || this.config?.apiKey || (this.name === 'anthropic' && process.env.ANTHROPIC_API_KEY));
+    return !!resolveProviderApiKey(this.name, this.config);
   }
 }