mixdog 1.2.0 → 1.2.2

package/src/runtime/agent/orchestrator/providers/account-pool.mjs

@@ -3,23 +3,68 @@ import {
   accountScopedSessionId,
   readProviderAccountPool,
   chooseProviderAccount,
-  changeProviderAccounts,
+  selectProviderAccountIf,
   blockProviderAccount,
   providerAccountExhausted,
+  providerAccountExhaustedForModelOnly,
+  providerAccountPolicy,
   providerAccountsResetAt,
 } from '../../../shared/provider-accounts.mjs';
 import { withProviderAccount, hasExplicitProviderAuthBinding } from '../../../shared/provider-auth-binding.mjs';
-import { retryAfterMsFromError, isExplicitUserAbortError, typedErrorCode } from './retry-classifier.mjs';
+import { isExplicitUserAbortError, markProviderRecoveryExhausted } from './retry-classifier.mjs';
+import { sleepWithAbort } from './retry-backoff.mjs';
+import { QUOTA_KINDS, providerErrorKind } from './provider-error-kind.mjs';
 import { fetchOAuthUsageSnapshot, readCachedOAuthUsageSnapshot } from './oauth-usage.mjs';
 
-// Only an explicit quota refusal advances the roster; a generic 429, auth
-// refusal, policy denial or transport failure retains its existing recovery.
+// Only an explicit quota / plan / billing refusal advances the roster as
+// quota; a generic 429, overload, auth refusal, policy denial or transport
+// failure retains its existing recovery.
 export function isAccountQuotaError(error) {
-  const status = Number(error?.status || error?.httpStatus || error?.response?.status || 0);
-  if (status === 401 || status === 403 || isExplicitUserAbortError(error)) return false;
-  return ['insufficient_quota', 'quota_exceeded', 'usage_limit_reached', 'usage_not_included'].includes(
-    String(typedErrorCode(error) || error?.error?.type || '').toLowerCase()
-  );
+  if (isExplicitUserAbortError(error)) return false;
+  const { kind, status } = providerErrorKind(error);
+  if (status === 401 || status === 403) return false;
+  return QUOTA_KINDS.has(kind);
+}
+
+// Kinds that say nothing about the account: the server (or the network) is
+// temporarily unable to serve (or has no capacity in the requested service
+// tier). They never block or rotate an account.
+const SERVER_SIDE_KINDS = new Set(['overloaded', 'transient', 'service_tier_unavailable']);
+
+// Provider-supplied roster cooldowns (`accountCooldownPolicy` on the provider
+// object), used when the server named no delay:
+//   { floorMs, rateLimitedMs, quotaStepsMs, unknownMs, rotateOnRateLimit,
+//     waitForCooldownMs, blockedMs }
+// blockedMs: cooldown for an `accountBlocked` refusal, which then rotates.
+// quotaStepsMs escalates per consecutive quota refusal of one account (reset
+// by a served answer). Absent → the inferred five minutes.
+// rotateOnRateLimit rotates on a plain 429 rate limit; its advice, when
+// present, becomes that account's cooldown.
+// waitForCooldownMs: when every eligible account is only cooling down (no
+// quota evidence), the send waits — cancellable, reported as reconnect
+// progress — for the earliest cooldown while the send's total wait stays
+// within this bound; beyond it the cooldown error surfaces. Absent → no wait.
+const INFERRED_COOLDOWN_MS = 5 * 60_000;
+const quotaStrikes = new Map();
+
+function cooldownPolicyOf(instance) {
+  const policy = instance?.accountCooldownPolicy;
+  return policy && typeof policy === 'object' ? policy : null;
+}
+
+function finiteMs(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+function policyCooldownMs(policy, strikeKey, reason) {
+  if (reason === 'rate_limited') return finiteMs(policy.rateLimitedMs, INFERRED_COOLDOWN_MS);
+  if (reason === 'quota' && Array.isArray(policy.quotaStepsMs) && policy.quotaStepsMs.length) {
+    const strikes = quotaStrikes.get(strikeKey) || 0;
+    quotaStrikes.set(strikeKey, strikes + 1);
+    return finiteMs(policy.quotaStepsMs[Math.min(strikes, policy.quotaStepsMs.length - 1)], INFERRED_COOLDOWN_MS);
+  }
+  return finiteMs(policy.unknownMs, INFERRED_COOLDOWN_MS);
 }
 
 // Burst throttles reopen within seconds. A 429 whose Retry-After points
@@ -75,6 +120,23 @@ function accountsExhaustedError(useCredits) {
   return error;
 }
 
+// Every eligible account is only cooling down after a rate limit (no quota
+// evidence): a rate limit, advising the earliest cooldown end as the wait.
+// The pool already spent its cooldown wait, so this is a terminal verdict for
+// the loop, not an unclassified failure.
+function earliestCooldownMs(rows, now) {
+  const ends = rows.map((row) => Number(row.blockedUntil)).filter((until) => Number.isFinite(until) && until > now);
+  return ends.length ? Math.min(...ends) - now : null;
+}
+
+function accountsCoolingDownError(rows, now) {
+  const error = new Error('Every connected account is cooling down after a rate limit. Try again shortly.');
+  error.code = 'rate_limited';
+  const wait = earliestCooldownMs(rows, now);
+  if (wait != null) error.retryAfterMs = wait;
+  return markProviderRecoveryExhausted(error, { owner: 'account-pool', terminal: true });
+}
+
 // Structured proof that the send ended because no account can serve `model`
 // (not merely because a generic 429 or a stopped loop surfaced an error).
 function quotaExhausted(error, providerName, model, rows, options = {}) {
@@ -116,28 +178,135 @@ function boundAccountSend(providerName, row, messages, options) {
   return { opts, history, emitted: () => emitted };
 }
 
-// Commit only a successful fallback, without overwriting a newer selection.
-function commitFallbackAccount(providerName, pool, row) {
-  if (row.id === pool.selectedId) return;
-  const current = readProviderAccountPool(providerName);
-  if (current.selectedId === pool.selectedId && current.accounts.some((entry) => entry.id === row.id)) {
-    return changeProviderAccounts(providerName, { selectedId: row.id });
+// Commit only a successful fallback, without overwriting a newer selection:
+// the selection is compared under the write's lock, not before it. A fallback
+// forced by a model-scoped limit ("7D Fable" full, or a block attributed to
+// one family) serves this request only: the selected account still serves
+// every other model, so it stays the provider's account of record.
+async function commitFallbackAccount(providerName, pool, row, model, refusalScoped, policy) {
+  if (row.id === pool.selectedId || refusalScoped) return null;
+  if (accountExhaustedForModelOnly(providerName, pool.selectedId, model)) return null;
+  return selectProviderAccountIf(providerName, pool.selectedId, row.id, policy);
+}
+
+// The account each session runs on under the headroom policy. Every answer
+// records its provider and account in the assistant message's
+// `providerMetadata` (and in provider state when the adapter keeps one), so
+// the binding survives a restart and eviction from this map, which only
+// spares the history walk. Bounded, oldest binding first out.
+const SESSION_ACCOUNT_LIMIT = 1000;
+const ROUTING_METADATA_KEY = 'accountRouting';
+const sessionAccounts = new Map();
+
+// Forget every in-memory binding, as a restart does (tests).
+export function resetSessionAccountBindings() {
+  sessionAccounts.clear();
+}
+
+function rememberSessionAccount(key, id) {
+  sessionAccounts.delete(key);
+  sessionAccounts.set(key, id);
+  if (sessionAccounts.size > SESSION_ACCOUNT_LIMIT) sessionAccounts.delete(sessionAccounts.keys().next().value);
+}
+
+function accountExhaustedForModelOnly(providerName, id, model) {
+  const pool = readProviderAccountPool(providerName);
+  const row = pool.accounts.find((entry) => entry.id === id);
+  return (
+    Boolean(row) &&
+    providerAccountExhaustedForModelOnly(row, Date.now(), model, { useCredits: pool.useCredits === true })
+  );
+}
+
+// Only a binding recorded for THIS provider counts: a session that switched
+// providers carries another roster's account ids (every roster has a `default`).
+// The session's binding is read before the serving account, which differs
+// when a model-scoped limit lent this one answer to another account.
+function sessionAccountId(providerName, key, messages, options) {
+  if (key && sessionAccounts.has(key)) return sessionAccounts.get(key);
+  const state = options.providerState;
+  if (state?.providerAccountId && state.providerAccountProvider === providerName) {
+    return state.providerSessionAccountId || state.providerAccountId;
   }
+  for (let index = (messages?.length || 0) - 1; index >= 0; index -= 1) {
+    const routing = messages[index]?.providerMetadata?.[ROUTING_METADATA_KEY];
+    if (routing?.accountId && routing.provider === providerName) return routing.sessionAccountId || routing.accountId;
+  }
+  return null;
+}
+
+// Stamp the serving account on the answer, independent of transport state,
+// with the account the session stays bound to (`bindingId`).
+function recordServingAccount(providerName, result, id, bindingId) {
+  if (!result || typeof result !== 'object') return;
+  if (result.providerReplay) result.providerReplay = { ...result.providerReplay, accountId: id };
+  if (result.providerState) {
+    result.providerState = {
+      ...result.providerState,
+      providerAccountId: id,
+      providerSessionAccountId: bindingId,
+      providerAccountProvider: providerName,
+    };
+  }
+  const metadata =
+    result.providerMetadata && typeof result.providerMetadata === 'object' ? result.providerMetadata : {};
+  result.providerMetadata = {
+    ...metadata,
+    [ROUTING_METADATA_KEY]: { provider: providerName, accountId: id, sessionAccountId: bindingId },
+  };
 }
 
 // Whether the failed account's quota window is exhausted, plus the server's
 // retry delay. Anthropic and other subscriptions may use the same 429 code
 // for burst throttling and exhausted subscription windows, so the native
 // usage endpoint decides rather than a human-readable message.
+// `until` is when the block lifts: the real quota reset when the provider
+// named one, else the advised delay, else an inferred five minutes. A long
+// Retry-After without quota evidence is a rate-limit cooldown: it rotates
+// this send, blocks no longer than advised and is never quota evidence.
 async function accountQuotaExhausted(providerName, row, model, error, account) {
-  const status = Number(error?.status || error?.httpStatus || error?.response?.status || 0);
-  const delay = retryAfterMsFromError(error);
+  const { kind, status, retryAfterMs: delay, resetAt } = providerErrorKind(error);
+  const now = Date.now();
+  const policy = cooldownPolicyOf(account(row.id));
+  const floorMs = policy ? finiteMs(policy.floorMs, 0) : 0;
+  const blockUntil = (withReset, reason = 'unknown') => {
+    if (withReset && resetAt > now) return { until: resetAt, source: 'retry-after' };
+    if (delay > 0) return { until: now + Math.max(delay, floorMs), source: 'retry-after' };
+    if (policy) {
+      const ms = policyCooldownMs(policy, `${providerName}:${row.id}`, reason);
+      return { until: now + Math.max(ms, floorMs), source: 'inferred' };
+    }
+    return { until: now + INFERRED_COOLDOWN_MS, source: 'inferred' };
+  };
+  if (SERVER_SIDE_KINDS.has(kind) || isExplicitUserAbortError(error)) {
+    return { exhausted: false, delay, evidence: false, ...blockUntil(false) };
+  }
+  // An account-level block (`accountBlocked`, e.g. the account needs
+  // verification): with a policy `blockedMs` that account cools for it and the
+  // roster rotates; never quota evidence. Without one it surfaces as before.
+  const blockedMs = policy ? finiteMs(policy.blockedMs, 0) : 0;
+  if (error?.accountBlocked === true && blockedMs > 0) {
+    return {
+      exhausted: true,
+      accountBlocked: true,
+      delay,
+      evidence: false,
+      until: now + Math.max(blockedMs, floorMs),
+      source: 'inferred',
+    };
+  }
   const typed = isAccountQuotaError(error);
-  let exhausted = typed || (status === 429 && delay > QUOTA_WINDOW_RETRY_AFTER_MS);
+  if (typed) return { exhausted: true, delay, evidence: true, ...blockUntil(true, 'quota') };
+  // A policy with rotateOnRateLimit rotates on a plain rate limit too (the
+  // advice as its cooldown, else rateLimitedMs); never quota evidence.
+  if (policy?.rotateOnRateLimit === true && kind === 'rate_limited' && status === 429) {
+    return { exhausted: true, delay, evidence: false, ...blockUntil(false, 'rate_limited') };
+  }
+  let exhausted = status === 429 && delay > QUOTA_WINDOW_RETRY_AFTER_MS;
   // Proof of a spent quota: a typed quota refusal or an exhausted usage window
   // (a long Retry-After alone only rotates the roster, it proves nothing).
-  let evidence = typed;
-  if (!typed && status === 429) {
+  let evidence = false;
+  if (status === 429) {
     await fetchOAuthUsageSnapshot({ provider: providerName, accountId: row.id }, account(row.id), () => {}, {
       force: true,
     });
@@ -147,7 +316,7 @@ async function accountQuotaExhausted(providerName, row, model, error, account) {
     evidence = providerAccountExhausted({ ...entry, blockedUntil: 0 }, Date.now(), model, options);
     exhausted = exhausted || evidence || providerAccountExhausted(entry, Date.now(), model, options);
   }
-  return { exhausted, delay, evidence };
+  return { exhausted, delay, evidence, ...(exhausted ? blockUntil(evidence, evidence ? 'quota' : 'unknown') : {}) };
 }
 
 // The pool's send: walks the eligible accounts until one answers, blocking
@@ -158,12 +327,20 @@ function poolSend(providerName, account) {
     let lastError;
     let probed = false;
     const evidenced = new Set();
+    const sessionKey = options.sessionId ? `${providerName}:${options.sessionId}` : null;
+    const boundId = sessionAccountId(providerName, sessionKey, messages, options);
+    // Whether this send already left an account, and whether the latest quota
+    // refusal held only for this model's family.
+    let switched = false;
+    let refusalScoped = false;
     // Mark `error` only when every account in `ids` (default: the roster) is
     // exhausted with quota evidence: observed in this send, or a full window.
-    const markExhausted = (error, ids) => {
+    // Without an error of its own, the send reports quota exhaustion only on
+    // that evidence, and a rate-limit cooldown otherwise.
+    const exhaustion = (ids) => {
       const pool = readProviderAccountPool(providerName);
-      // Auto switching off: the eligible set is the selected account alone.
-      const scope = ids || (pool.auto === false ? [pool.selectedId] : null);
+      // Manual policy: the eligible set is the selected account alone.
+      const scope = ids || (providerAccountPolicy(pool) === 'manual' ? [pool.selectedId] : null);
       const rows = scope ? pool.accounts.filter((entry) => scope.includes(entry.id)) : pool.accounts;
       const opts = { useCredits: pool.useCredits === true };
       const now = Date.now();
@@ -177,9 +354,47 @@ function poolSend(providerName, account) {
             opts
           )
         );
-      return all ? quotaExhausted(error, providerName, model, rows, opts) : error;
+      return { rows, opts, now, all };
+    };
+    const markExhausted = (error, ids) => {
+      const { rows, opts, now, all } = exhaustion(ids);
+      if (all) {
+        return quotaExhausted(error || accountsExhaustedError(opts.useCredits), providerName, model, rows, opts);
+      }
+      return error || accountsCoolingDownError(rows, now);
+    };
+    // Accounts this send blocked on a rate-limit cooldown, the time it spent
+    // waiting for cooldowns, and the provider's wait bound.
+    const cooled = new Set();
+    let waitedMs = 0;
+    let sends = 0;
+    const waitBoundMs = (ids) => {
+      const id = ids?.[0] || readProviderAccountPool(providerName).selectedId || 'default';
+      return finiteMs(cooldownPolicyOf(account(id))?.waitForCooldownMs, 0);
     };
-    while (attempted.size < 20) {
+    // A cooldown-only eligible set whose earliest cooldown ends inside the
+    // remaining wait budget is waited out; otherwise the send fails as before.
+    const waitOrThrow = async (error, ids) => {
+      const { rows, now, all } = exhaustion(ids);
+      const wait = all ? null : earliestCooldownMs(rows, now);
+      if (wait == null || waitedMs + wait > waitBoundMs(ids)) throw markExhausted(error, ids);
+      options.onStageChange?.('reconnecting', {
+        message: `Rate limited — every account is cooling down; retrying in ${Math.ceil(wait / 1000)}s`,
+        reason: 'rate_limited',
+        waitMs: wait,
+        retryAt: now + wait,
+      });
+      await sleepWithAbort(wait, options.signal);
+      waitedMs += wait;
+      const lifted = Date.now();
+      for (const row of readProviderAccountPool(providerName).accounts) {
+        if (cooled.has(row.id) && !(Number(row.blockedUntil) > lifted)) {
+          cooled.delete(row.id);
+          attempted.delete(row.id);
+        }
+      }
+    };
+    while (attempted.size < 20 && sends < 20) {
       options.signal?.throwIfAborted();
       const pool = readProviderAccountPool(providerName);
       if (!pool.accounts.length) {
@@ -194,7 +409,8 @@ function poolSend(providerName, account) {
         }
         return account('default').send(messages, model, tools, options);
       }
-      const row = chooseProviderAccount(pool, attempted, Date.now(), model);
+      const policy = providerAccountPolicy(pool);
+      const row = chooseProviderAccount(pool, attempted, Date.now(), model, { sessionAccountId: boundId });
       if (!row) {
         // Once per send: a refusal built on a stale meter must not outlive the
         // meter. Re-measuring can only widen the roster, so it is tried before
@@ -203,15 +419,27 @@ function poolSend(providerName, account) {
           probed = true;
           if (await probeRefusedAccounts(providerName, pool, model, account)) continue;
         }
-        throw markExhausted(lastError || accountsExhaustedError(pool.useCredits === true));
+        await waitOrThrow(lastError);
+        continue;
       }
       attempted.add(row.id);
+      sends += 1;
       const bound = boundAccountSend(providerName, row, messages, options);
       try {
         const result = await account(row.id).send(bound.history, model, tools, bound.opts);
-        if (result?.providerReplay) result.providerReplay = { ...result.providerReplay, accountId: row.id };
-        if (result?.providerState) result.providerState = { ...result.providerState, providerAccountId: row.id };
-        if (commitFallbackAccount(providerName, pool, row)) {
+        quotaStrikes.delete(`${providerName}:${row.id}`);
+        // Headroom policy: a session's first pick, or its move off its account
+        // on a limit, becomes the selection; continuing on its account does
+        // not, so concurrent sessions never flip the selection back and forth.
+        // A move forced by a model-scoped limit serves this request only.
+        const leftBound = Boolean(boundId) && row.id !== boundId;
+        const scoped = switched
+          ? refusalScoped
+          : policy === 'headroom' && leftBound && accountExhaustedForModelOnly(providerName, boundId, model);
+        recordServingAccount(providerName, result, row.id, scoped && boundId ? boundId : row.id);
+        if (sessionKey && policy === 'headroom' && !scoped) rememberSessionAccount(sessionKey, row.id);
+        const commit = policy !== 'headroom' || !boundId || leftBound;
+        if (commit && (await commitFallbackAccount(providerName, pool, row, model, scoped, policy))) {
           // Publish only a committed selection, never a speculative retry or
           // one superseded by a manual switch. The existing progress channel
           // carries this across runtime shards to the attached UI.
@@ -230,7 +458,7 @@ function poolSend(providerName, account) {
         if (options.signal?.aborted) throw error;
         if (error?.reauthRequired === true) {
           if (
-            pool.auto === false ||
+            policy === 'manual' ||
             bound.emitted() ||
             error.unsafeToRetry ||
             error.liveTextEmitted ||
@@ -238,25 +466,47 @@ function poolSend(providerName, account) {
           )
             throw error;
           lastError = error;
+          switched = true;
+          refusalScoped = false;
           options.onStageChange?.('reconnecting', { message: 'Sign-in expired — switching to the next account' });
           continue;
         }
-        const { exhausted, delay, evidence } = await accountQuotaExhausted(providerName, row, model, error, account);
-        if (options.signal?.aborted || !exhausted) throw error;
-        if (evidence) evidenced.add(row.id);
-        blockProviderAccount(
+        const { exhausted, evidence, until, source, accountBlocked } = await accountQuotaExhausted(
           providerName,
-          row.id,
-          Date.now() + (delay > 0 ? delay : 5 * 60_000),
+          row,
           model,
-          delay > 0 ? 'retry-after' : 'inferred',
-          { quota: evidence === true }
+          error,
+          account
         );
-        if (bound.emitted() || error.unsafeToRetry || error.liveTextEmitted || error.emittedToolCall) throw error;
-        // Auto switching off: the eligible set is the selected account alone.
-        if (pool.auto === false) throw markExhausted(error, [row.id]);
+        if (options.signal?.aborted || !exhausted) throw error;
+        if (evidence) evidenced.add(row.id);
+        else cooled.add(row.id);
+        await blockProviderAccount(providerName, row.id, until, model, source, { quota: evidence === true });
+        // An account block is unsafe to re-issue on THAT account only; with no
+        // output emitted, the next account may serve the same request.
+        if (
+          bound.emitted() ||
+          (error.unsafeToRetry && accountBlocked !== true) ||
+          error.liveTextEmitted ||
+          error.emittedToolCall
+        )
+          throw error;
+        // Manual policy: the eligible set is the selected account alone.
+        if (policy === 'manual') {
+          await waitOrThrow(error, [row.id]);
+          lastError = error;
+          continue;
+        }
         lastError = error;
-        options.onStageChange?.('reconnecting', { message: 'Quota exhausted — switching to the next account' });
+        switched = true;
+        refusalScoped = accountExhaustedForModelOnly(providerName, row.id, model);
+        options.onStageChange?.('reconnecting', {
+          message: evidence
+            ? 'Quota exhausted — switching to the next account'
+            : accountBlocked
+              ? 'Account blocked — switching to the next account'
+              : 'Rate limited (cooldown) — switching to the next account',
+        });
       }
     }
     throw markExhausted(lastError || new Error('Provider account attempts exhausted.'));

package/src/runtime/agent/orchestrator/providers/anthropic-api-recovery.mjs

@@ -9,6 +9,7 @@
 import { PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS, createTimeoutSignal } from '../stall-policy.mjs';
 import { AnthropicFallbackTriggeredError, markProviderRecoveryExhausted } from './retry-classifier.mjs';
 import { normalizeAnthropicNonStreamingResponse } from './lib/anthropic-request-utils.mjs';
+import { capForNonStreaming } from './anthropic-max-tokens-recovery.mjs';
 import { createAnthropicRecoveryGuards } from './anthropic-recovery-guards.mjs';
 
 /**
@@ -44,7 +45,7 @@ export function createAnthropicApiRecovery({
     try {
       onStageChange?.('requesting', { transport: 'non-streaming-fallback' });
     } catch {}
-    const nonStreamingParams = { ...params, stream: false };
+    const nonStreamingParams = capForNonStreaming({ ...params, stream: false });
     const timeoutMs =
       Number(opts._nonStreamingTimeoutMs) > 0
         ? Number(opts._nonStreamingTimeoutMs)

package/src/runtime/agent/orchestrator/providers/anthropic-api-transport.mjs

@@ -14,13 +14,16 @@ import {
   ANTHROPIC_RETRY_JITTER_RATIO,
   anthropicMaxAttempts,
   anthropicRequestTimeoutMs,
+  AnthropicFallbackTriggeredError,
   emitProviderRetryStage,
   withRetry,
-  retryAfterMsFromError,
   retryDelayLabel,
 } from './retry-classifier.mjs';
+import { ANTHROPIC_MAX_CONSECUTIVE_529 } from './retry-backoff.mjs';
 import { PROVIDER_FIRST_BYTE_TIMEOUT_MS, createTimeoutSignal } from '../stall-policy.mjs';
-import { noteFastModeCapacityError } from './anthropic-fast-mode.mjs';
+import { fastModeDowngraded, noteFastModeCapacityError } from './anthropic-fast-mode.mjs';
+import { adjustMaxTokensForContextOverflow } from './anthropic-max-tokens-recovery.mjs';
+import { applyAnthropicErrorContract, retryAfterMsFromHeaders } from './anthropic-error-contract.mjs';
 import { noteRequestServiceTier } from '../../../shared/llm/usage-context.mjs';
 import { notifyCurrentAnthropicRateLimit } from './admission-scheduler.mjs';
 
@@ -78,12 +81,61 @@ export function armFirstByteWatchdog(streamController, midState) {
  * @param {object} deps.params  the streaming request body (mutated on fast-pool de-latch)
  * @param {object|null} deps.requestHeaders  per-call beta/extra headers
  * @param {AbortSignal|null} deps.totalSignal  session-lifetime pass-through
+ * @param {{ state: { consecutive529Errors: number } }|null} [deps.overload]  the send's shared overload counter
  */
-export function createAnthropicApiTransport({ client, label, opts, useModel, params, requestHeaders, totalSignal }) {
+export function createAnthropicApiTransport({
+  client,
+  label,
+  opts,
+  useModel,
+  params,
+  requestHeaders,
+  totalSignal,
+  overload = null,
+}) {
   const requestOptions = (attemptSignal) => ({
     signal: attemptSignal,
     ...(requestHeaders ? { headers: requestHeaders } : {}),
   });
+  // The SDK throws a non-2xx before `.asResponse()` resolves, so an HTTP
+  // failure arrives as an APIError rather than a Response. Stamp the
+  // provider-boundary error contract on it (status, lowercased error type as
+  // `code`, preserved headers, uncapped retryAfterMs / resetAt).
+  const annotateHttpFailure = (err) => {
+    if (err && typeof err === 'object' && Number(err.status || err.httpStatus || 0) > 0) {
+      applyAnthropicErrorContract(err, { status: err.status || err.httpStatus, headers: err.headers });
+    }
+    return err;
+  };
+  // A fast-pool refusal (or a "Fast mode is not enabled" 400) says nothing
+  // about standard-speed capacity: drop `speed` and let the caller replay at
+  // once instead of waiting out a window that only the fast pool owns.
+  const dropFastSpeedAfter = (body, err) => {
+    if (body.speed !== 'fast') return false;
+    if (!fastModeDowngraded(noteFastModeCapacityError(err, { fast: true }))) return false;
+    delete body.speed;
+    return true;
+  };
+  // In-attempt body repairs, each replayed once: drop speed after a fast-pool
+  // refusal, and shrink max_tokens after the "input length and max_tokens
+  // exceed context limit" 400.
+  const withBodyRecovery = (body, attempt) => async (ctx) => {
+    let speedDropped = false;
+    let tokensAdjusted = false;
+    for (;;) {
+      try {
+        return await attempt(ctx);
+      } catch (err) {
+        if (!speedDropped && dropFastSpeedAfter(body, err)) {
+          speedDropped = true;
+        } else if (!tokensAdjusted && adjustMaxTokensForContextOverflow(body, err?.status, err?.message)) {
+          tokensAdjusted = true;
+        } else {
+          throw err;
+        }
+      }
+    }
+  };
   // Initial-response retry policy shared by the streaming request and the
   // non-streaming fallback.
   const retryPolicy = (signal, perAttemptLabel, recoveryOwner) => ({
@@ -95,23 +147,27 @@ export function createAnthropicApiTransport({ client, label, opts, useModel, par
     perAttemptTimeoutMs: anthropicRequestTimeoutMs(),
     perAttemptLabel,
     provider: 'anthropic',
+    // This transport honors the positive x-should-retry override.
+    honorShouldRetryTrue: true,
     recoveryOwner,
     retry529: opts.retry529,
     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,
+    stopAfterRepeated529: overload?.stopAfterRepeated529 === true,
   });
 
-  const requestStreamingResponse = () =>
-    withRetry(
-      async ({ signal: attemptSignal }) => {
-        noteRequestServiceTier(params.speed);
+  const requestStreamingResponse = async () => {
+    const attempt = async ({ signal: attemptSignal }) => {
+      noteRequestServiceTier(params.speed);
+      try {
         const res = await client.messages.create(params, requestOptions(attemptSignal)).asResponse();
         if (!res.ok) {
           const text = await res.text().catch(() => '');
           const err = new Error(`Anthropic API ${res.status}: ${text.slice(0, 200)}`);
-          err.status = res.status;
-          err.httpStatus = res.status;
-          err.initialResponseError = true;
           // Carry response headers so withRetry can honor a
           // short Retry-After and upstream can read quota hints.
           err.headers = res.headers;
@@ -120,48 +176,55 @@ export function createAnthropicApiTransport({ client, label, opts, useModel, par
           // output/tool exposure, so the request-local
           // withRetry loop may retry it with jitter.
           if (res.status === 429) {
-            const retryAfterMs = retryAfterMsFromError({
-              headers: res.headers,
-              response: { headers: res.headers },
-            });
             err.name = 'ProviderQuotaError';
-            err.code = 'PROVIDER_QUOTA';
-            err.retryAfterMs = retryAfterMs;
+            err.retryAfterMs = retryAfterMsFromHeaders(res.headers);
             err.providerQuota = true;
             err.quotaExceeded = true;
           }
-          throw err;
+          throw applyAnthropicErrorContract(err, { status: res.status, headers: res.headers, bodyText: text });
         }
         if (!res.body) {
           throw new Error('Anthropic streaming response has no body');
         }
         return res;
-      },
-      {
+      } catch (err) {
+        throw annotateHttpFailure(err);
+      }
+    };
+    try {
+      return await withRetry(withBodyRecovery(params, attempt), {
         ...retryPolicy(totalSignal, `${label} Anthropic streaming response`, `${label}-initial-response`),
-        onRetry: ({ attempt, maxAttempts, lastErr, delayMs, delayReason }) => {
-          emitProviderRetryStage(opts.onStageChange, { attempt: attempt + 1, maxAttempts, lastErr, delayMs });
-          // Long/unknown fast-pool window: replay at
-          // standard speed rather than waiting it out.
-          if (params?.speed === 'fast' && noteFastModeCapacityError(lastErr, { fast: true }) !== 'retry-fast') {
-            delete params.speed;
-          }
+        onRetry: ({ attempt: retryNo, maxAttempts, lastErr, delayMs, delayReason }) => {
+          emitProviderRetryStage(opts.onStageChange, { attempt: retryNo + 1, maxAttempts, lastErr, delayMs });
           const status = Number(lastErr?.httpStatus || lastErr?.status || lastErr?.response?.status || 0);
           if (status === 429) notifyCurrentAnthropicRateLimit(lastErr);
           const delayLabel = retryDelayLabel(delayMs, delayReason);
           process.stderr.write(
-            `[${label}] retry attempt ${attempt + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}${delayLabel}\n`
+            `[${label}] retry attempt ${retryNo + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}${delayLabel}\n`
           );
         },
+      });
+    } catch (err) {
+      // Whatever escapes withRetry failed before any stream existed and has
+      // already spent the request-level budget: mark it so mid-stream
+      // recovery never grants it a second, SSE-sized retry budget.
+      if (err && typeof err === 'object' && !(err instanceof AnthropicFallbackTriggeredError)) {
+        err.initialResponseError = true;
       }
-    );
+      throw err;
+    }
+  };
 
   const requestNonStreamingMessage = (nonStreamingParams, signal) =>
     withRetry(
-      async ({ signal: attemptSignal }) => {
+      withBodyRecovery(nonStreamingParams, async ({ signal: attemptSignal }) => {
         noteRequestServiceTier(nonStreamingParams.speed);
-        return client.messages.create(nonStreamingParams, requestOptions(attemptSignal));
-      },
+        try {
+          return await client.messages.create(nonStreamingParams, requestOptions(attemptSignal));
+        } catch (err) {
+          throw annotateHttpFailure(err);
+        }
+      }),
       {
         ...retryPolicy(signal, `${label} Anthropic non-streaming fallback`, `${label}-nonstreaming-request`),
         onRetry: ({ attempt, maxAttempts, lastErr, delayMs }) =>