mixdog 1.2.1 → 1.2.3

package/src/runtime/agent/orchestrator/providers/retry-executor.mjs

@@ -7,17 +7,16 @@ import { noteErrorUsage } from './lib/note-error-usage.mjs';
 import { retryReasonText, retryStatusLine } from '../../../shared/err-text.mjs';
 import {
   TERMINAL_EDGE_STATUSES,
-  headerValue,
   boundedCauseChain,
   classifyError,
-  isPermanentQuotaError,
   isStaleKeepAliveError,
   isToolInputCut,
   retryAfterMsFromError,
 } from './retry-classification.mjs';
+import { DETERMINISTIC_KINDS, QUOTA_KINDS, errorHeaderValue, providerErrorKind } from './provider-error-kind.mjs';
+import { adviceGatedRetry } from './retry-midstream.mjs';
 import {
-  ANTHROPIC_MAX_CONSECUTIVE_529,
-  AnthropicFallbackTriggeredError,
+  ModelFallbackTriggeredError,
   DEFAULT_BACKOFF_MS,
   DEFAULT_MAX_ATTEMPTS,
   jitterDelayMs,
@@ -64,11 +63,16 @@ export function createStreamSafetyStamps() {
 
 const providerRecoveryExhaustedErrors = new WeakSet();
 
-export function markProviderRecoveryExhausted(error, { owner = 'provider', attempts = null } = {}) {
+// `terminal: true` records a provider VERDICT that recovery is over (a policy
+// veto such as an unadvised advice-gated overload, or the repeated-overload
+// stop), not merely a spent ladder: outer layers end recovery on it instead
+// of opening another budget.
+export function markProviderRecoveryExhausted(error, { owner = 'provider', attempts = null, terminal = false } = {}) {
   if (!error || (typeof error !== 'object' && typeof error !== 'function')) return error;
   providerRecoveryExhaustedErrors.add(error);
   try {
     error.providerRecoveryExhausted = true;
+    if (terminal) error.providerRecoveryTerminal = true;
     if (owner) error.providerRecoveryOwner = String(owner);
     const count = Number(attempts);
     if (Number.isFinite(count) && count > 0) error.providerRecoveryAttempts = Math.floor(count);
@@ -85,18 +89,25 @@ export function isProviderRecoveryExhausted(error) {
   );
 }
 
+/** True when a provider layer ruled that no further recovery may run (see markProviderRecoveryExhausted). */
+export function isProviderRecoveryTerminal(error) {
+  if (!error || (typeof error !== 'object' && typeof error !== 'function')) return false;
+  return boundedCauseChain(error).some((candidate) => candidate?.providerRecoveryTerminal === true);
+}
+
 function throwIfRetryAborted(signal) {
   if (!signal?.aborted) return;
   const reason = signal.reason;
   throw reason instanceof Error ? reason : new Error('withRetry: aborted');
 }
 
-// A stale keep-alive socket, or (Grok) the first 5xx, rebuilds the HTTP
-// client to escape a poisoned HTTP/2 keep-alive pool (CF 522/523/524
-// included). 525/526 stay fatal.
-function recycleDispatcherAfter(caught, status) {
+// Before a retry: a stale keep-alive socket rebuilds the HTTP client to escape
+// a poisoned keep-alive pool. A caller whose upstream poisons its HTTP/2 pool
+// on server faults (`recycleDispatcherOn5xx`) also rebuilds it on a retried
+// 5xx (edge 522/523/524 included). Never runs for a failure that is not retried.
+function recycleDispatcherAfter(caught, status, opts) {
   const poisoned =
-    isStaleKeepAliveError(caught) || (status >= 500 && status < 600 && !TERMINAL_EDGE_STATUSES.has(status));
+    isStaleKeepAliveError(caught) || (opts.recycleDispatcherOn5xx === true && status >= 500 && status < 600);
   if (!poisoned) return;
   try {
     recycleLlmDispatcher();
@@ -105,23 +116,71 @@ function recycleDispatcherAfter(caught, status) {
   }
 }
 
+// Opt-in: without a fallback model, the request loop stops after
+// `overloadFallbackAfter` overloads instead of spending the whole
+// attempt budget. A provider verdict: no outer layer re-opens recovery.
+function repeated529Error(caught, opts, maxAttempts) {
+  const error = new Error('Repeated 529 Overloaded errors', { cause: caught });
+  error.name = 'Repeated529Error';
+  error.repeated529 = true;
+  error.status = Number(caught?.status || caught?.httpStatus || 529) || 529;
+  error.httpStatus = error.status;
+  error.code = 'overloaded_error';
+  if (caught?.headers) error.headers = caught.headers;
+  return markProviderRecoveryExhausted(error, {
+    owner: opts.recoveryOwner || 'withRetry',
+    attempts: maxAttempts,
+    terminal: true,
+  });
+}
+
+// Deterministic refusals of this request (auth, permission, policy, invalid
+// request, context/size) end the loop before any status, header or overload
+// rule may re-issue it. Quota kinds are judged separately below.
+function deterministicRefusal(errorKind, kind, status, opts) {
+  if (!DETERMINISTIC_KINDS.has(errorKind) || QUOTA_KINDS.has(errorKind)) return false;
+  // Opt-in: a status-only 499 is retried (classifyError's retry499 verdict;
+  // a typed code on the 499 keeps it final).
+  return !(status === 499 && opts.retry499 === true && kind === 'transient');
+}
+
+// The overload counter (`overloadFallbackAfter`) counts every overload of the
+// send; intervening non-overload failures do not reset it.
+function isOverloadFailure(status, errorKind) {
+  return status === 529 || errorKind === 'overloaded';
+}
+
 // Decides whether `caught` may be re-issued: returns the error to throw (the
 // caught one, the exhausted-marked one on the last attempt, or the model
-// fallback trigger) or null when the next attempt may run.
-function retryVeto(caught, { opts, attempt, maxAttempts, state }) {
+// fallback trigger) or null when the next attempt may run — and only then
+// rebuilds a poisoned HTTP pool for it.
+function retryVeto(caught, context) {
+  const verdict = retryVerdict(caught, context);
+  if (verdict === null) {
+    const status = Number(caught?.httpStatus || caught?.status || caught?.response?.status || 0);
+    recycleDispatcherAfter(caught, status, context.opts);
+  }
+  return verdict;
+}
+
+function retryVerdict(caught, { opts, attempt, maxAttempts, state }) {
   const lastAttempt = attempt === maxAttempts - 1;
+  // `finalOnExhaust`: the caller's ladder is the whole recovery, so a spent
+  // ladder is a provider-terminal verdict no outer layer re-opens.
   const exhaustedError = () =>
-    maxAttempts > 1
+    maxAttempts > 1 || opts.finalOnExhaust === true
       ? markProviderRecoveryExhausted(caught, {
           owner: opts.recoveryOwner || 'withRetry',
           attempts: maxAttempts,
+          terminal: opts.finalOnExhaust === true,
         })
       : caught;
   // A nested provider layer already spent its complete recovery budget.
   // Never multiply that budget by replaying it from an outer withRetry.
   if (isProviderRecoveryExhausted(caught)) return caught;
   const status = Number(caught?.httpStatus || caught?.status || caught?.response?.status || 0);
-  const kind = classifyError(caught);
+  const kind = classifyError(caught, { retry499: opts.retry499 === true });
+  const errorKind = providerErrorKind(caught).kind;
   // Hard replay boundary: a retry RE-ISSUES the request, so it is denied
   // once visible output was relayed or a tool call was dispatched. Whether
   // an eligible failure is actually retried remains the typed question
@@ -131,40 +190,67 @@ function retryVeto(caught, { opts, attempt, maxAttempts, state }) {
   // split-call notice; re-issuing the identical request here would tend to be
   // cut at the same place again.
   if (isToolInputCut(caught)) return caught;
-  recycleDispatcherAfter(caught, status);
+  const overload = isOverloadFailure(status, errorKind);
+  // Deterministic refusals first: no status, header (x-should-retry:true
+  // included) or overload rule below may re-issue them.
+  if (deterministicRefusal(errorKind, kind, status, opts)) return caught;
+  // An origin-TLS edge failure (525/526) is final whatever header, advice or
+  // overload code accompanies it.
+  if (TERMINAL_EDGE_STATUSES.has(status)) return caught;
+  // An explicit quota / plan / billing refusal cannot recover by replaying
+  // the same request, whatever Retry-After the server attached. A 429 whose
+  // only quota evidence is header-derived (providerQuota / quotaExceeded) is
+  // still retried for non-subscriber callers (Enterprise/PAYG
+  // 429s); a typed quota/billing code never is.
+  if (QUOTA_KINDS.has(errorKind)) {
+    const typedQuota = QUOTA_KINDS.has(providerErrorKind(caught, { quotaFlags: false }).kind);
+    if (typedQuota || opts.retry429 === false || status !== 429) return caught;
+  }
   // Background calls (titles and the like) never retry an overload: during a
   // capacity cascade every retry multiplies gateway load, and nobody is
   // waiting on the result.
   if (status === 529 && opts.retry529 === false) return caught;
-  // x-should-retry:false is an explicit server veto on retrying and is
-  // honored as-is. Keep this ahead of status defaults, including the
-  // request-local 429 path.
-  const shouldRetryHeader = String(
-    headerValue(caught?.headers || caught?.response?.headers || caught?.data?.responseHeaders, 'x-should-retry') || ''
-  ).toLowerCase();
-  if (shouldRetryHeader === 'false') return caught;
-  // Anthropic's non-standard positive override outranks ordinary status
-  // classification. Keep subscription OAuth 429 fail-fast ownership:
-  // retry429:false is the Max/Pro gate and must not wait for that window.
-  if (opts.provider === 'anthropic' && shouldRetryHeader === 'true' && !(status === 429 && opts.retry429 === false)) {
-    return lastAttempt ? exhaustedError() : null;
+  // A caller may opt into advice-gated overload / generic-429 retries. The
+  // denial is the provider's verdict: outer recovery layers honor it.
+  if (adviceGatedRetry(caught, opts) === false) {
+    return markProviderRecoveryExhausted(caught, {
+      owner: opts.recoveryOwner || 'withRetry',
+      attempts: attempt + 1,
+      terminal: true,
+    });
   }
-  // The optional model fallback fires on the third 529. This remains opt-in:
-  // providers pass fallbackModel only when the caller set one. The hard
-  // progress veto above must run first so fallback can never replay partial
-  // thinking/tool output.
-  if (status === 529 && opts.fallbackModel && opts.fallbackModel !== opts.model) {
+  // Overload first: counted and retried ahead of the x-should-retry veto.
+  // The optional model fallback fires after `overloadFallbackAfter`
+  // overloads in the send (opt-in: providers pass fallbackModel only when
+  // the caller set one); without one, `stopAfterRepeated529` ends the loop
+  // there instead. The hard progress veto above runs first so neither can
+  // replay partial thinking/tool output. `overloadState` shares the count
+  // across a send.
+  if (overload) {
+    // Subscriber 429 fail-fast ownership also covers an overload-coded 429.
+    if (status === 429 && opts.retry429 === false) return caught;
     state.consecutive529Errors += 1;
-    if (state.consecutive529Errors >= ANTHROPIC_MAX_CONSECUTIVE_529) {
-      return new AnthropicFallbackTriggeredError(opts.model, opts.fallbackModel, caught);
+    const limit = Number(opts.overloadFallbackAfter);
+    if (Number.isFinite(limit) && limit > 0 && state.consecutive529Errors >= limit) {
+      if (opts.fallbackModel && opts.fallbackModel !== opts.model) {
+        return new ModelFallbackTriggeredError(opts.model, opts.fallbackModel, caught);
+      }
+      if (opts.stopAfterRepeated529 === true) return repeated529Error(caught, opts, maxAttempts);
     }
+    return lastAttempt ? exhaustedError() : null;
+  }
+  // x-should-retry:false is an explicit server veto on retrying and is
+  // honored as-is, ahead of status defaults including the 429 path.
+  const shouldRetryHeader = String(errorHeaderValue(caught, 'x-should-retry') || '').toLowerCase();
+  if (shouldRetryHeader === 'false') return caught;
+  // A transport that opts in (honorShouldRetryTrue) lets the non-standard
+  // positive override outrank ordinary status classification — except for
+  // subscribers (retry429:false), whose fail-fast ownership holds for every status.
+  if (opts.honorShouldRetryTrue === true && shouldRetryHeader === 'true' && opts.retry429 !== false) {
+    return lastAttempt ? exhaustedError() : null;
   }
   if (status === 429) {
     if (opts.retry429 === false) return caught;
-    // A deterministic quota refusal cannot recover by replaying the same
-    // request. An explicit server retry window outranks message-text quota
-    // heuristics: RESOURCE_EXHAUSTED + Retry-After/RetryInfo is transient.
-    if (retryAfterMsFromError(caught) == null && isPermanentQuotaError(caught)) return caught;
     // Retry only this request. Admission concurrency is fixed and is never
     // reduced by rate limits. Output/tool stamps above remain a hard replay
     // boundary.
@@ -184,8 +270,12 @@ function retryOptions(opts) {
     perAttemptTimeoutMs: Number(opts.perAttemptTimeoutMs || 0),
     perAttemptLabel: opts.perAttemptLabel || 'provider request',
     retryJitterRatio: Number(opts.retryJitterRatio ?? PROVIDER_RETRY_JITTER_RATIO),
-    retryJitterMode: opts.retryJitterMode === 'positive' ? 'positive' : 'symmetric',
+    retryJitterMode: ['positive', 'negative'].includes(opts.retryJitterMode) ? opts.retryJitterMode : 'symmetric',
     sleepFn: typeof opts.sleepFn === 'function' ? opts.sleepFn : undefined,
+    // Opt-in: positive jitter on server advice, and advice as a
+    // floor under — never a replacement for — the current backoff step.
+    retryAfterJitterRatio: Math.max(0, Number(opts.retryAfterJitterRatio) || 0),
+    adviceAtLeastBackoff: opts.adviceAtLeastBackoff === true,
   };
 }
 
@@ -193,11 +283,17 @@ function retryOptions(opts) {
 // the jittered backoff step. Retry-After is a server-mandated minimum. Do
 // not cap, shorten, or jitter it; cancellation remains active throughout
 // the full wait.
-function retryWaitMs(attempt, { nextDelayMs, nextDelayReason }, { backoffMs, retryJitterRatio, retryJitterMode }) {
-  const rawWait = nextDelayMs ?? backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? 0;
-  return nextDelayReason === 'retry-after'
-    ? Math.max(0, rawWait)
-    : jitterDelayMs(rawWait, retryJitterRatio, retryJitterMode);
+function retryWaitMs(
+  attempt,
+  { nextDelayMs, nextDelayReason },
+  { backoffMs, retryJitterRatio, retryJitterMode, retryAfterJitterRatio = 0, adviceAtLeastBackoff = false }
+) {
+  const step = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? 0;
+  if (nextDelayReason !== 'retry-after') return jitterDelayMs(nextDelayMs ?? step, retryJitterRatio, retryJitterMode);
+  let wait = Math.max(0, nextDelayMs ?? 0);
+  if (adviceAtLeastBackoff) wait = Math.max(wait, jitterDelayMs(step, retryJitterRatio, retryJitterMode));
+  // Positive-only jitter never shortens the advice.
+  return retryAfterJitterRatio > 0 ? jitterDelayMs(wait, retryAfterJitterRatio, 'positive') : wait;
 }
 
 /**
@@ -260,7 +356,14 @@ export async function withRetry(fn, opts = {}) {
   let lastErr = null;
   let nextDelayMs = null;
   let nextDelayReason = null;
-  const state = { consecutive529Errors: Math.max(0, Number(opts.initialConsecutive529Errors) || 0) };
+  // `opts.overloadState` ({ consecutive529Errors }) lets one logical send share
+  // its overload count across every withRetry it runs (streaming, recovery
+  // cycles, non-streaming fallback), so the configured fallback still fires.
+  const shared = opts.overloadState && typeof opts.overloadState === 'object' ? opts.overloadState : null;
+  const state = shared || {};
+  if (!Number.isFinite(state.consecutive529Errors)) {
+    state.consecutive529Errors = Math.max(0, Number(opts.initialConsecutive529Errors) || 0);
+  }
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     throwIfRetryAborted(signal);
     if (attempt > 0) {

package/src/runtime/agent/orchestrator/providers/retry-midstream.mjs

@@ -11,6 +11,46 @@ import {
   isTransientErrorCode,
   typedStatusFrom,
 } from './retry-classification.mjs';
+import { DETERMINISTIC_KINDS, providerErrorKind } from './provider-error-kind.mjs';
+
+// A 429 that is an overload or an ordinary rate limit is request-local: it is
+// re-issued under the bounded mid-stream budget (the server's advice, when it
+// sent one, sets the wait). Quota / plan / billing refusals never are.
+// The advice-honoring mid-stream wait lives with the backoff schedule.
+export { midstreamRetryDelayMs } from './retry-backoff.mjs';
+
+// Per-provider parity, as policy options (default false = retry under the
+// bounded budget with ordinary backoff):
+//   overloadRetryRequiresAdvice   — an overload (server_is_overloaded,
+//     overloaded_error, 529, statusless overload event) retries ONLY when the
+//     server gave advice (Retry-After / retryAfterMs / RetryInfo).
+//   generic429RetryRequiresAdvice — a rate limit without a typed
+//     rate_limit_exceeded / slow_down code retries ONLY on advice.
+// A typed rate_limit_exceeded / slow_down always retries (advice, else the
+// delay its message names, else local backoff). Returns false when the
+// policy denies the retry, null when it has no say.
+const TYPED_RATE_LIMIT_CODES = new Set(['rate_limit_exceeded', 'slow_down']);
+export function adviceGatedRetry(err, policy = {}) {
+  const { kind, code, retryAfterMs } = providerErrorKind(err);
+  const advised = retryAfterMs != null;
+  if (kind === 'overloaded' && policy.overloadRetryRequiresAdvice === true && !advised) return false;
+  if (
+    kind === 'rate_limited' &&
+    !TYPED_RATE_LIMIT_CODES.has(code) &&
+    policy.generic429RetryRequiresAdvice === true &&
+    !advised
+  ) {
+    return false;
+  }
+  return null;
+}
+
+function retryable429(err, policy) {
+  if (policy.retry429 === false) return false;
+  if (adviceGatedRetry(err, policy) === false) return false;
+  const { kind } = providerErrorKind(err);
+  return kind === 'overloaded' || kind === 'rate_limited';
+}
 
 // F) Retry-budget profiles as DATA. The numbers live ONLY here now.
 //    ws.*Retries (5)              — one Responses stream retry budget.
@@ -88,19 +128,24 @@ function isWebSocketConnectionLimit(err) {
 // bucket. Buckets need typed codes; the DEFAULT for an unrecognized (or
 // absent) code is the bounded retry, with fatal refusal codes staying
 // terminal.
-function classifyResponseFailed(failed, attemptIndex, policy) {
+function classifyResponseFailed(failed, attemptIndex, policy, err = null) {
   const detail = failed?.response?.error || failed?.error || failed;
   const failedStatus = typedStatusFrom(detail, failed?.response, failed);
+  // Deterministic codes outrank a numeric 5xx on the same payload.
+  const keys = [detail?.code, detail?.type]
+    .map((field) => (typeof field === 'string' ? field.trim().toLowerCase() : ''))
+    .filter(Boolean);
+  const codeClassifier = keys.map((key) => RESPONSE_FAILED_CODE_CLASSIFIERS.get(key)).find(Boolean) || null;
+  if (!codeClassifier && keys.some((key) => WIRE_ERROR_FATAL_CODES.has(key))) return null;
+  const subject = { responseFailed: failed, headers: err?.headers, retryAfterMs: err?.retryAfterMs };
+  if (DETERMINISTIC_KINDS.has(providerErrorKind(subject).kind)) return null;
+  // Statusless overload / generic rate-limit events follow the advice gate.
+  if (adviceGatedRetry(subject, policy) === false) return null;
   if (failedStatus >= 500 && failedStatus < 600) {
     if (TERMINAL_EDGE_STATUSES.has(failedStatus)) return null;
     return _allowMidstream(`http_${failedStatus}`, attemptIndex, policy);
   }
-  for (const field of [detail?.code, detail?.type]) {
-    const key = typeof field === 'string' ? field.trim().toLowerCase() : '';
-    const classifier = RESPONSE_FAILED_CODE_CLASSIFIERS.get(key);
-    if (classifier) return _allowMidstream(classifier, attemptIndex, policy);
-    if (key && WIRE_ERROR_FATAL_CODES.has(key)) return null;
-  }
+  if (codeClassifier) return _allowMidstream(codeClassifier, attemptIndex, policy);
   // A typed non-transient 4xx on the failure payload is a deterministic
   // refusal even without a recognized code string.
   if (failedStatus >= 400 && failedStatus < 500 && !TRANSIENT_STATUSES.has(failedStatus)) return null;
@@ -146,12 +191,19 @@ function _classifyMidstreamWs(err, state, attemptIndex, policy) {
   // NOMINAL closes count too: a pooled socket the server retires between
   // turns closes with 1000/1001/1005 and must reconnect fresh — treating
   // that as terminal killed the turn instead of reissuing it.
-  if (!state.sawResponseCreated && !NON_TERMINAL_STREAM_CLOSE_CODES.has(closeCode)) return null;
+  // An EXPLICIT wire failure (response.failed / error event) before
+  // response.created exposed nothing either: it gets the same bounded WS
+  // retry budget, and its typed code decides below.
+  const failed = err?.responseFailed || state.responseFailedPayload;
+  if (!state.sawResponseCreated && !NON_TERMINAL_STREAM_CLOSE_CODES.has(closeCode) && !failed) return null;
   if (state.userAbort) return null;
 
   if (!err) return null;
   const status = Number(err?.httpStatus || 0);
-  if (status === 401 || status === 403 || status === 429) return null;
+  if (status === 401 || status === 403) return null;
+  if (DETERMINISTIC_KINDS.has(providerErrorKind(err).kind)) return null;
+  if (status === 429) return retryable429(err, policy) ? _allowMidstream('http_429', attemptIndex, policy) : null;
+  if (status && adviceGatedRetry(err, policy) === false) return null;
   if (status >= 500 && status < 600) {
     if (TERMINAL_EDGE_STATUSES.has(status)) return null;
     return _allowMidstream(`http_${status}`, attemptIndex, policy);
@@ -167,8 +219,7 @@ function _classifyMidstreamWs(err, state, attemptIndex, policy) {
     return _allowMidstream(`ws_${closeCode}`, attemptIndex, policy);
   }
 
-  const failed = err?.responseFailed || state.responseFailedPayload;
-  if (failed) return classifyResponseFailed(failed, attemptIndex, policy);
+  if (failed) return classifyResponseFailed(failed, attemptIndex, policy, err);
   return null;
 }
 
@@ -181,8 +232,8 @@ const RESPONSE_FAILED_CODE_CLASSIFIERS = new Map([
   ['auth_expired', 'response_failed_auth_expired'],
   ['previous_response_not_found', 'previous_response_not_found'],
   ['websocket_connection_limit_reached', 'websocket_connection_limit'],
-  // A rate limit is retried after the server-advised wait (the reference
-  // client's RateLimitExceeded); a usage limit stays a fatal code.
+  // A rate limit is retried after the server-advised wait; a usage limit
+  // stays a fatal code.
   ['rate_limit_exceeded', 'response_failed_rate_limited'],
 ]);
 
@@ -197,7 +248,10 @@ function _classifyMidstreamSse(err, state, attemptIndex, policy) {
   if (!err) return null;
   const status = Number(err?.httpStatus || err?.status || err?.response?.status || 0);
   if (status === 401 || status === 403) return null;
-  if (status === 429) return 'http_429';
+  if (DETERMINISTIC_KINDS.has(providerErrorKind(err).kind)) return null;
+  if (status === 429) return retryable429(err, policy) ? 'http_429' : null;
+  // Opt-in: overloads retry only on server advice.
+  if (adviceGatedRetry(err, policy) === false) return null;
   if (status >= 500 && status < 600) {
     if (TERMINAL_EDGE_STATUSES.has(status)) return null;
     return `http_${status}`;
@@ -322,13 +376,24 @@ export function shouldFallbackTransport(err, { signal, enabled = true } = {}) {
 //    returns null. HTTP 401 is reserved for auth recovery and 426 for immediate
 //    HTTPS fallback. The OpenAI OAuth caller opts out of 429 retries
 //    (retry429:false); all other callers retain the historical retryable
-//    UnexpectedStatus policy.
-export function classifyHandshakeError(err, { retry429 = true } = {}) {
+//    UnexpectedStatus policy. overloadRetryRequiresAdvice /
+//    generic429RetryRequiresAdvice (default false) opt a caller into
+//    advice-gated overload / generic-429 retries.
+export function classifyHandshakeError(
+  err,
+  { retry429 = true, overloadRetryRequiresAdvice = false, generic429RetryRequiresAdvice = false } = {}
+) {
   if (!err) return null;
   const code = err.code || '';
   const status = Number(err.httpStatus || 0);
 
   if (status === 401 || status === 426 || (status === 429 && !retry429)) return null;
+  // Every deterministic refusal (quota, billing, auth, permission, policy,
+  // invalid request, context/size) is final, whatever 5xx or advice it carries.
+  if (DETERMINISTIC_KINDS.has(providerErrorKind(err).kind)) return null;
+  if (status && adviceGatedRetry(err, { overloadRetryRequiresAdvice, generic429RetryRequiresAdvice }) === false) {
+    return null;
+  }
   if (status > 0) {
     // Typed transient handshake statuses only. A 403/404/4xx upgrade refusal
     // is a deterministic decision: spending the retry budget on it cannot

package/src/runtime/agent/orchestrator/providers/transport-scope.d.mts

@@ -0,0 +1,6 @@
+export const TRANSPORT_SCOPE_DISPOSED: 'transport_scope_disposed';
+export function forkTransportScope(sessionId: string, label?: string): string;
+export function disposeTransportScope(
+  scope: string,
+  provider?: { releaseTransportScope?(scope: string): void } | null
+): void;

package/src/runtime/agent/orchestrator/providers/transport-scope.mjs

@@ -0,0 +1,28 @@
+// transport-scope.mjs — a send's transport state scope, apart from its
+// session identity. Providers key their session-scoped transport and
+// continuation state (pooled sockets and their previous_response_id anchor,
+// Codex turn-state routing tokens, sticky HTTP fallback, Cursor runs and
+// conversations) by `opts.transportScope || opts.sessionId`, while prompt
+// cache routing (prompt_cache_key, handshake session id) stays on
+// `opts.sessionId`. A request forked from a session (/btw) runs in a scope of
+// its own: it shares the session's prompt cache but reads and writes none of
+// its transport state, and its scope is disposed once it is answered.
+import { randomUUID } from 'node:crypto';
+
+/** The reason a scope's provider connections are closed when it is disposed. */
+export const TRANSPORT_SCOPE_DISPOSED = 'transport_scope_disposed';
+
+/** A fresh transport scope for one request forked from `sessionId`. */
+export function forkTransportScope(sessionId, label = 'fork') {
+  return `${sessionId}#${label}:${randomUUID()}`;
+}
+
+/** Close every connection and drop every transport record of `scope`. */
+export function disposeTransportScope(scope, provider) {
+  if (!scope) return;
+  try {
+    globalThis.__mixdogCloseProviderConnectionsForSession?.(scope, TRANSPORT_SCOPE_DISPOSED);
+  } finally {
+    provider?.releaseTransportScope?.(scope);
+  }
+}

package/src/runtime/agent/orchestrator/providers/wire-gateway.mjs

@@ -0,0 +1,157 @@
+/**
+ * wire-gateway.mjs — an API-key gateway that serves one account on several
+ * wires (OpenRouter, DeepSeek). Chat Completions and Responses go through the
+ * OpenAI-compatible engine, Anthropic Messages through an Anthropic engine
+ * bound to the gateway; wire-route.mjs picks the wire per model.
+ */
+import { AnthropicProvider } from './anthropic.mjs';
+import { OpenAICompatProvider, OPENAI_COMPAT_PRESETS } from './openai-compat.mjs';
+import { originBoundFetch } from './lib/origin-bound-fetch.mjs';
+import { withInclusiveUsage } from './lib/inclusive-usage.mjs';
+import { getModelMetadataSync } from './model-catalog.mjs';
+import { resolveWireRoute, sendOnRoute } from './wire-route.mjs';
+
+// A Files API file-ID image anywhere in the history (tool results nest content).
+function hasFileIdImage(value, depth = 0) {
+  if (!value || typeof value !== 'object' || depth > 6) return false;
+  if (Array.isArray(value)) return value.some((entry) => hasFileIdImage(entry, depth + 1));
+  const fileId = value.type === 'input_image' ? value.file_id : value.type === 'image' && value.source?.type === 'file' ? value.source.file_id : null;
+  if (typeof fileId === 'string' && fileId) return true;
+  return hasFileIdImage(value.content, depth + 1);
+}
+
+/**
+ * The per-request capability options a gateway's Messages engine hands the
+ * shared Anthropic request builder (anthropic-api-request.mjs):
+ *   - `modelMaxOutputTokens`: the gateway's own output ceiling for the model
+ *     (`config.modelMaxOutputTokens(model)`),
+ *   - `messagesEffortProjection`: the gateway's own effort projection
+ *     (`config.messagesEffortProjection`), replacing the Claude rules,
+ *   - `anthropic-beta` (`config.fileIdImageBeta`) only on a request that
+ *     carries a file-ID image; every other beta stays suppressed.
+ */
+export function gatewayMessagesOpts(config, model, messages, opts) {
+  const out = { ...(opts || {}) };
+  const ceiling = Math.floor(Number(typeof config?.modelMaxOutputTokens === 'function' ? config.modelMaxOutputTokens(model) : 0));
+  if (ceiling > 0 && out.modelMaxOutputTokens === undefined) out.modelMaxOutputTokens = ceiling;
+  if (typeof config?.messagesEffortProjection === 'function') out.messagesEffortProjection = config.messagesEffortProjection;
+  if (config?.fileIdImageBeta && hasFileIdImage(messages)) {
+    out.requestHeaders = { 'anthropic-beta': config.fileIdImageBeta, ...(out.requestHeaders || {}) };
+  }
+  return out;
+}
+
+/**
+ * Anthropic engine bound to a gateway: only the gateway key is sent — never
+ * an ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN from the environment — and only
+ * to the gateway origin. `config.authScheme: 'bearer'` sends the key as
+ * `Authorization: Bearer` (OpenRouter); the default is `x-api-key`. The client
+ * is rebuilt through here on every key change or reload.
+ * `config.capabilityModel(model)` maps the routing slug to the Claude id its
+ * capabilities are read from.
+ */
+export class GatewayMessagesEngine extends AnthropicProvider {
+  // Document capability of this gateway's Messages route, declared by the
+  // gateway config. `nativePdf`: PDFs ride as document blocks (default: lowered
+  // to text). `nativeDocuments`: any document block at all; unset leaves
+  // non-PDF documents as they are, an explicit false (DeepSeek) means every
+  // document variant is lowered to text or rejected.
+  nativePdf = this.config.nativePdf === true;
+  nativeDocuments = this.config.nativeDocuments;
+  _sendOnce(messages, model, tools, opts) {
+    return super._sendOnce(messages, model, tools, gatewayMessagesOpts(this.config, model, messages, opts));
+  }
+  _createClient(apiKey) {
+    const client = super._createClient(apiKey);
+    if (this.config.authScheme === 'bearer') {
+      client.apiKey = null;
+      client.authToken = apiKey || null;
+    } else {
+      client.authToken = null;
+    }
+    client.fetch = originBoundFetch(new URL(this.config.baseURL).origin, this.config.fetchImpl, this.name);
+    return client;
+  }
+  _capabilityModel(model) {
+    return (typeof this.config.capabilityModel === 'function' && this.config.capabilityModel(model)) || model;
+  }
+}
+
+export class WireGatewayProvider {
+  // No document block on any gateway wire: a PDF is lowered to text.
+  nativePdf = false;
+  // Every wire reports inclusive input (Messages usage is converted).
+  static inputExcludesCache = false;
+  name;
+  config;
+  openai;
+  anthropic;
+
+  /**
+   * @param {string} name  preset name (openai-compat-presets.mjs)
+   * @param {object} config  provider config
+   * @param {object} messages  the Messages engine: `{ baseURL, authScheme?, capabilityModel? }`
+   * @param {object} [compatConfig]  extra OpenAI-compatible engine config
+   */
+  constructor(name, config = {}, messages, compatConfig = {}) {
+    this.name = name;
+    this.config = config;
+    this.openai = new OpenAICompatProvider(name, { ...config, ...compatConfig });
+    this.anthropic = new GatewayMessagesEngine({
+      ...config,
+      ...messages,
+      name,
+      disableBetaHeaders: true,
+      modelMaxOutputTokens: messages.modelMaxOutputTokens ?? ((model) => this._modelMaxOutputTokens(model)),
+      extraHeaders: { ...(OPENAI_COMPAT_PRESETS[name]?.extraHeaders || {}), ...(config.extraHeaders || {}) },
+    });
+    // The Chat engine's retry profile stays the account's loop policy.
+    if (this.openai.retryPolicy) this.retryPolicy = this.openai.retryPolicy;
+  }
+
+  resolveWireRoute(model, ctx = {}) {
+    return resolveWireRoute(this.name, model, { ...ctx, override: this.config?.modelWires?.[model] ?? null });
+  }
+
+  // The model's output ceiling: the gateway roster, else the shared catalog.
+  _modelMaxOutputTokens(model) {
+    const declared = Number(this.getCachedModelInfo(model)?.outputTokens ?? getModelMetadataSync(model, this.name)?.outputTokens);
+    return Number.isFinite(declared) && declared > 0 ? declared : null;
+  }
+
+  send(messages, model, tools, sendOpts) {
+    const useModel = model || this.openai.defaultModel;
+    // The resolved route is the only wire authority: a caller's own wire
+    // switches never reach an engine, and one clear "unsupported" refusal
+    // moves the send to the next wire once (sendOnRoute).
+    return sendOnRoute(this, useModel, tools, sendOpts, messages, (wire, history, opts) => {
+      if (wire === 'messages') return withInclusiveUsage(() => this.anthropic.send(history, useModel, tools, opts));
+      if (wire === 'responses') return this.openai.send(history, model, tools, { ...opts, compatWireApi: 'responses' });
+      return this.openai.send(history, model, tools, opts);
+    });
+  }
+
+  reloadApiKey() {
+    this.openai.reloadApiKey();
+    this.anthropic.reloadApiKey();
+  }
+
+  async listModels() {
+    return this.openai.listModels();
+  }
+
+  async isAvailable() {
+    return this.openai.isAvailable();
+  }
+
+  getCachedModelInfo(model) {
+    return this.openai.getCachedModelInfo(model);
+  }
+}
+
+/** The Anthropic SDK base for a gateway's OpenAI base: the SDK appends `/v1/messages`. */
+export function messagesBaseFromOpenAIBase(baseURL) {
+  return String(baseURL || '')
+    .replace(/\/+$/, '')
+    .replace(/\/v1$/i, '');
+}