mixdog 1.2.1 → 1.2.2

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/runtime-core/config-helpers.mjs

@@ -351,6 +351,9 @@ export function normalizeCompactionConfig(value = {}) {
   return {
     ...next,
     auto: raw.auto !== false && raw.enabled !== false,
+    // Compact a conversation on its current model before switching it to
+    // another one in place (default on).
+    onModelChange: raw.onModelChange !== false,
   };
 }
 

package/src/runtime/agent/orchestrator/runtime-core/goal-reminder.mjs

@@ -80,21 +80,3 @@ export function acknowledgePendingGoalReminder(session, revision) {
   session.updatedAt = Date.now();
   return true;
 }
-
-export function prependGoalReminderToLatestUserMessage(messages, content) {
-  const reminder = clean(content);
-  const out = Array.isArray(messages) ? [...messages] : [];
-  if (!reminder) return out;
-  for (let index = out.length - 1; index >= 0; index -= 1) {
-    const message = out[index];
-    if (message?.role !== 'user') continue;
-    const current = message.content;
-    const nextContent = Array.isArray(current)
-      ? [{ type: 'text', text: `${reminder}\n\n` }, ...current]
-      : `${reminder}\n\n${String(current ?? '')}`;
-    out[index] = { ...message, content: nextContent };
-    return out;
-  }
-  out.push({ role: 'user', content: reminder });
-  return out;
-}

package/src/runtime/agent/orchestrator/runtime-core/model-capabilities.mjs

@@ -7,6 +7,7 @@ import { modelSupportsServiceTier } from '../providers/model-service-tiers.mjs';
 import { openAiDirectSupportsFast, openAiDirectSupportsUltrafast } from '../providers/openai-direct-request.mjs';
 import { supportsAnthropicFastMode } from '../../../shared/llm/anthropic-betas.mjs';
 import { normalizeContextTokens } from '../../../shared/llm/default-context-window.mjs';
+import { getModelMetadataSync } from '../../../shared/llm/model-catalog.mjs';
 
 const FAST_CAPABLE_PROVIDERS = new Set([
   'anthropic',
@@ -24,41 +25,59 @@ export function routeFastKey(provider, model) {
   return p && m ? `${p}/${m}` : '';
 }
 
-function openAiModelSupportsHostedWebSearch(model) {
-  const id = clean(model?.id || model).toLowerCase();
-  if (!id) return false;
-  if (model?.supportsWebSearch === true) return true;
+// What one catalog row states about hosted web search: its own
+// `supportsWebSearch` flag (true or false), else a web_search tool in its tool
+// lists. Null when the row says nothing, which leaves the answer to the id
+// fallback of each family.
+function rowWebSearchDeclaration(row) {
+  if (!row || typeof row !== 'object') return null;
+  if (typeof row.supportsWebSearch === 'boolean') return row.supportsWebSearch;
   const tools = [
-    ...(Array.isArray(model?.supportedTools) ? model.supportedTools : []),
-    ...(Array.isArray(model?.tools) ? model.tools : []),
-    ...(Array.isArray(model?.capabilities?.tools) ? model.capabilities.tools : []),
+    ...(Array.isArray(row.supportedTools) ? row.supportedTools : []),
+    ...(Array.isArray(row.tools) ? row.tools : []),
+    ...(Array.isArray(row.capabilities?.tools) ? row.capabilities.tools : []),
   ].map((tool) => clean(tool?.type || tool?.name || tool).toLowerCase());
-  if (tools.some((tool) => tool === 'web_search' || tool === 'web_search_preview')) return true;
-  if (/codex|image|audio|tts|stt|embedding|rerank|moderation|search-preview/.test(id)) return false;
-  return /^gpt-(5(?:\.|$|-)|4\.1(?:-|$)|4o(?:-|$)|4\.5(?:-|$))/.test(id) || /^o[34](?:-|$)/.test(id);
-}
-
-function grokModelSupportsHostedWebSearch(model) {
-  const id = clean(model?.id || model).toLowerCase();
-  if (!id || /imagine|image|video|composer/.test(id)) return false;
-  if (id === 'grok-build') return false;
-  return /^grok-/.test(id);
+  return tools.some((tool) => tool === 'web_search' || tool === 'web_search_preview') ? true : null;
 }
 
-function geminiModelSupportsHostedWebSearch(model) {
-  const id = clean(model?.id || model).toLowerCase();
-  if (!id || /embedding|aqa|imagen|veo|tts|image|computer-use|customtools/.test(id)) return false;
-  return /^gemini-(3(?:\.|-|$)|2\.5-|2\.0-flash)/.test(id);
+// The route's own row first, then the provider catalog's row for the model.
+function hostedWebSearchDeclared(model, catalogRow) {
+  return rowWebSearchDeclaration(model) ?? rowWebSearchDeclaration(catalogRow);
 }
 
-function anthropicModelSupportsHostedWebSearch(model) {
+// When neither the route row nor the catalog states hosted web search, the
+// vendor family (already fixed by the provider) is taken as capable unless the
+// id names a non-chat modality or a retired generation. Only those closed,
+// frozen sets are matched by id, so a model released later needs no entry here;
+// guessing "capable" wrongly would hard-fail the request, which is why the
+// retired generations stay excluded.
+function hostedWebSearchFallback(model, catalogRow, unsupportedId) {
   const id = clean(model?.id || model).toLowerCase();
   if (!id) return false;
-  const match = id.match(/^claude-(opus|sonnet|haiku|fable|mythos)-(\d+)(?:[-.](\d+))?/);
-  if (!match) return false;
-  return (Number(match[2]) || 0) >= 4;
+  const declared = hostedWebSearchDeclared(model, catalogRow);
+  if (declared !== null) return declared;
+  return !unsupportedId.test(id);
 }
 
+const NON_CHAT_ID = 'embedding|rerank|moderation|image|imagen|imagine|video|veo|audio|tts|stt|aqa|search-preview';
+
+const OPENAI_UNSUPPORTED = new RegExp(
+  `${NON_CHAT_ID}|codex|^gpt-(?:3|4(?:$|-))|^o[12](?:-|$)|^(?:babbage|davinci|text-)`
+);
+const GROK_UNSUPPORTED = new RegExp(`${NON_CHAT_ID}|composer|^grok-build$|^grok-[123](?:[.-]|$)`);
+// The Gemini family is also reached through a relay serving other vendors'
+// models, whose hosted search is Gemini's alone, so a non-Gemini id is out.
+const GEMINI_UNSUPPORTED = new RegExp(
+  `${NON_CHAT_ID}|^(?!gemini-)|computer-use|customtools|^gemini-(?:1[.-]|pro|ultra)|^gemini-2\\.0-(?!flash)`
+);
+const ANTHROPIC_UNSUPPORTED = /^claude-(?:\d|instant)|^claude-[a-z]+-[123](?:[-.]|$)/;
+
+const openAiModelSupportsHostedWebSearch = (model, row) => hostedWebSearchFallback(model, row, OPENAI_UNSUPPORTED);
+const grokModelSupportsHostedWebSearch = (model, row) => hostedWebSearchFallback(model, row, GROK_UNSUPPORTED);
+const geminiModelSupportsHostedWebSearch = (model, row) => hostedWebSearchFallback(model, row, GEMINI_UNSUPPORTED);
+const anthropicModelSupportsHostedWebSearch = (model, row) =>
+  hostedWebSearchFallback(model, row, ANTHROPIC_UNSUPPORTED);
+
 export function fastCapableFor(provider, model, effort = null, modelParameters = {}) {
   const p = clean(provider);
   if (!FAST_CAPABLE_PROVIDERS.has(p)) return false;
@@ -77,8 +96,13 @@ export function fastCapableFor(provider, model, effort = null, modelParameters =
     }
     return !selectedEffort || fastEfforts.length === 0 || fastEfforts.includes(selectedEffort);
   }
-  if (p === 'openai') return openAiDirectSupportsFast(model);
   if (p === 'openai-oauth') return modelSupportsServiceTier(model, 'priority');
+  // The route row's own declaration first, then the catalog via the helpers.
+  if (typeof model?.supportsFastMode === 'boolean') return model.supportsFastMode;
+  const modelId = clean(model?.id || model);
+  const declaredFast = modelId ? getModelMetadataSync(modelId, p)?.supportsFastMode : undefined;
+  if (typeof declaredFast === 'boolean') return declaredFast;
+  if (p === 'openai') return openAiDirectSupportsFast(model);
   if (p === 'anthropic' || p === 'anthropic-oauth') return supportsAnthropicFastMode(clean(model?.id || model));
   return false;
 }
@@ -100,10 +124,15 @@ const HOSTED_WEB_SEARCH_BY_FAMILY = {
 // webSearchCapableFor needs the web-search family mapping, which lives in
 // workflow.mjs and is pure. Wire it in via a factory to keep this module free
 // of a circular import at load time.
-export function makeWebSearchCapableFor(webSearchProviderFamily) {
+// `catalogRowFor(provider, id)` is the provider catalog's row for the model;
+// callers that hold only a bare id (or a row the provider list left silent)
+// still get the catalog's answer before the id fallback applies.
+export function makeWebSearchCapableFor(webSearchProviderFamily, catalogRowFor = getModelMetadataSync) {
   return function webSearchCapableFor(provider, model) {
     const supports = HOSTED_WEB_SEARCH_BY_FAMILY[webSearchProviderFamily(provider)];
-    return supports ? supports(model) : false;
+    if (!supports) return false;
+    const id = clean(model?.id || model);
+    return supports(model, id ? catalogRowFor(id, provider) : null);
   };
 }