mixdog 1.2.0 → 1.2.2

package/src/runtime/agent/orchestrator/providers/openai-compat.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import { noteErrorUsage } from './lib/note-error-usage.mjs';
-import { getAgentApiKey } from '../../../shared/provider-api-key.mjs';
+import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
 import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
 import { appendAgentTrace } from '../agent-trace.mjs';
 import { OPENAI_COMPAT_PRESETS } from './openai-compat-presets.mjs';
@@ -13,7 +13,9 @@ import {
   _shouldFallbackXaiWsToHttp,
 } from './openai-compat-xai.mjs';
 import { withEffortRejectionFallback } from './effort-rejection.mjs';
+import { applyCompatErrorContract } from './openai-compat-error-contract.mjs';
 import { sendCompatResponses } from './openai-compat-responses.mjs';
+import { COMPAT_RETRY_POLICY, COMPAT_RETRY_PROFILES, XAI_COMPAT_RETRY_POLICY } from './openai-compat-retry-profile.mjs';
 import { sendCompatChat, recoverCompatNonStreaming } from './openai-compat-chat-send.mjs';
 import { sendXaiResponses, sendXaiResponsesWebSocket } from './openai-compat-xai-send.mjs';
 import {
@@ -69,8 +71,10 @@ export class OpenAICompatProvider {
   constructor(name, config) {
     const preset = PRESETS[name];
     const baseURL = assertSafeBaseURL(config.baseURL || preset?.baseURL || 'http://localhost:8080/v1', name);
-    const apiKey = config.apiKey || 'no-key';
+    const apiKey = resolveProviderApiKey(name, config) || 'no-key';
     this.name = name;
+    // A profiled provider's limits are final: no loop-level recovery cycles on top.
+    if (COMPAT_RETRY_PROFILES[name]) this.retryPolicy = name === 'xai' ? XAI_COMPAT_RETRY_POLICY : COMPAT_RETRY_POLICY;
     this.config = config;
     this.baseURL = baseURL;
     this.apiKey = apiKey;
@@ -121,7 +125,7 @@ export class OpenAICompatProvider {
   reloadApiKey() {
     try {
       const preset = PRESETS[this.name];
-      const newKey = getAgentApiKey(this.name) || this.config.apiKey;
+      const newKey = reloadProviderApiKey(this.name, this.config);
       const baseURL = assertSafeBaseURL(
         this.config.baseURL || preset?.baseURL || 'http://localhost:8080/v1',
         this.name
@@ -138,6 +142,12 @@ export class OpenAICompatProvider {
     }
   }
   async send(messages, model, tools, sendOpts) {
+    // A keyless-constructed instance picks up the key once it is available.
+    const resolvedKey = resolveProviderApiKey(this.name, this.config) || 'no-key';
+    if (resolvedKey !== this.apiKey) {
+      this.apiKey = resolvedKey;
+      this.client = this._createClient(resolvedKey);
+    }
     try {
       return await this._doSend(messages, model, tools, sendOpts);
     } catch (err) {
@@ -162,9 +172,19 @@ export class OpenAICompatProvider {
   }
   async _doSend(messages, model, tools, sendOpts) {
     const useModel = model || this.defaultModel;
-    return withEffortRejectionFallback(this.name, useModel, sendOpts || {}, this.config?.reasoningEffort, (opts) =>
-      this._sendWithOpts(messages, useModel, tools, opts)
-    );
+    try {
+      return await withEffortRejectionFallback(
+        this.name,
+        useModel,
+        sendOpts || {},
+        this.config?.reasoningEffort,
+        (opts) => this._sendWithOpts(messages, useModel, tools, opts)
+      );
+    } catch (err) {
+      // Every provider built on this transport (custom, grok, muse, mimo,
+      // command-code, local) leaves through here with the boundary contract.
+      throw applyCompatErrorContract(err);
+    }
   }
   async _sendWithOpts(messages, useModel, tools, opts) {
     // Re-warm a kept-alive socket to the provider origin before the turn so

package/src/runtime/agent/orchestrator/providers/openai-direct-request.mjs

@@ -1,33 +1,52 @@
 import { getModelMetadataSync } from '../../../shared/llm/model-catalog.mjs';
 
-// Public Responses contracts are independent of the OAuth backend.
-// Match documented model IDs and dated snapshots, not unknown future families.
-// GPT-5.6 and later: prompt_cache_options caching and Fast mode.
-const GPT_56_PLUS_MODELS =
+// Public Responses contracts are independent of the OAuth backend. Every
+// capability here comes from the model catalog (the service-tier price columns
+// and the cache-write rate), so a model the catalog lists works without an
+// edit. Only a model no catalog describes (cold install) falls back to the
+// documented ids known before the catalogs carried these columns.
+const SNAPSHOT_SUFFIX = /-\d{4}-\d{2}-\d{2}$/;
+const PRE_CATALOG_GPT_56_PLUS =
   /^(?:gpt-6-(?:astra|sol|luna)|gpt-6\.1-sol|gpt-5\.6-(?:sol|terra|luna))(?:-\d{4}-\d{2}-\d{2})?$/;
+const PRE_CATALOG_EARLIER_FAST = /^gpt-5\.(?:5|4|4-mini)(?:-\d{4}|$)/;
+const PRE_CATALOG_ULTRAFAST = /^(?:gpt-6-astra|gpt-6\.1-sol)(?:-\d{4}-\d{2}-\d{2})?$/;
+const modelId = (model) => String(model?.id || model || '').trim();
 
-// OpenAI bills prompt-cache writes from GPT-5.6 on, and exactly those models
-// take prompt_cache_options and Fast mode. The id pattern is the offline
-// floor; a published cache-write price admits a later model without an edit
-// here, and a family no catalog lists yet stays out.
-// https://developers.openai.com/api/docs/guides/prompt-caching
-function isGpt56PlusModel(model) {
-  const id = String(model || '').trim();
-  if (!id) return false;
-  return GPT_56_PLUS_MODELS.test(id) || getModelMetadataSync(id, 'openai')?.cacheWriteCostPerM > 0;
+// The catalog metadata of one model. A dated snapshot reads as its undated
+// alias when only the alias is listed.
+function openAiCatalogMeta(model) {
+  const id = String(model?.id || model || '').trim();
+  for (const candidate of new Set([id, id.replace(SNAPSHOT_SUFFIX, '')])) {
+    const meta = candidate ? getModelMetadataSync(candidate, 'openai') : null;
+    if (meta) return meta;
+  }
+  return null;
 }
-// Earlier models documented for Priority processing (now Fast mode).
-const EARLIER_FAST_MODELS = /^gpt-5\.(?:5|4|4-mini)(?:-\d{4}|$)/;
 
 export function openAiDirectSupportsFast(model) {
-  const id = String(model?.id || model || '').trim();
-  return isGpt56PlusModel(id) || EARLIER_FAST_MODELS.test(id);
+  const meta = openAiCatalogMeta(model);
+  // The catalog's declaration (true or false) decides; a published Priority
+  // rate is the same declaration. A row silent on Fast keeps the documented ids.
+  if (typeof meta?.supportsFastMode === 'boolean') return meta.supportsFastMode;
+  if (meta?.fastPricing) return true;
+  const id = modelId(model);
+  return PRE_CATALOG_GPT_56_PLUS.test(id) || PRE_CATALOG_EARLIER_FAST.test(id);
 }
 
-const ULTRAFAST_MODELS = /^(?:gpt-6-astra|gpt-6\.1-sol)(?:-\d{4}-\d{2}-\d{2})?$/;
-
+// A published Ultrafast rate (the `_ultrafast` price columns) is the tier's
+// declaration; a row silent on it keeps the documented ids.
 export function openAiDirectSupportsUltrafast(model) {
-  return ULTRAFAST_MODELS.test(String(model?.id || model || '').trim());
+  if (openAiCatalogMeta(model)?.ultrafastPricing) return true;
+  return PRE_CATALOG_ULTRAFAST.test(modelId(model));
+}
+
+// OpenAI bills prompt-cache writes from GPT-5.6 on, and exactly those models
+// take prompt_cache_options in place of prompt_cache_retention, so a published
+// cache-write rate selects the new form.
+// https://developers.openai.com/api/docs/guides/prompt-caching
+function promptCacheForm(model) {
+  const writeRate = openAiCatalogMeta(model)?.cacheWriteCostPerM > 0;
+  return writeRate || PRE_CATALOG_GPT_56_PLUS.test(modelId(model)) ? 'options' : 'retention';
 }
 
 export function applyOpenAIDirectCachePolicy(body, model, storeResponses) {
@@ -37,10 +56,8 @@ export function applyOpenAIDirectCachePolicy(body, model, storeResponses) {
   // Preserve the existing opt-out: no explicit cache-retention hint when
   // response storage is disabled. The provider's default cache still applies.
   if (!storeResponses) return body;
-  if (isGpt56PlusModel(model)) {
-    body.prompt_cache_options = { ttl: '30m' };
-  } else {
-    body.prompt_cache_retention = '24h';
-  }
+  const form = promptCacheForm(model);
+  if (form === 'options') body.prompt_cache_options = { ttl: '30m' };
+  else if (form === 'retention') body.prompt_cache_retention = '24h';
   return body;
 }

package/src/runtime/agent/orchestrator/providers/openai-error-contract.mjs

@@ -0,0 +1,274 @@
+/**
+ * openai-error-contract.mjs — the one place the OpenAI provider boundary
+ * stamps the shared error contract onto a thrown error:
+ *
+ *   status / httpStatus  typed HTTP status
+ *   code                 lowercased error code/type from the JSON body or wire event
+ *   headers              response headers (HTTP, WS handshake, nested error.headers)
+ *   retryAfterMs         server advice, uncapped (Retry-After / Retry-After-Ms)
+ *   resetAt              epoch ms from quota reset fields (resets_at, resets_in_seconds)
+ *
+ * Pure: no I/O. Message text is never parsed for status or code.
+ */
+import { retryAfterMsFromError, sleepWithAbort } from './retry-classifier.mjs';
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// Explicit quota / billing refusals: waiting never helps, so no retry layer
+// may treat them as an ordinary rate limit.
+const QUOTA_OR_BILLING_CODE_RE = /quota|billing|usage_limit|usage_not_included/;
+
+export function isQuotaOrBillingCode(code) {
+  return QUOTA_OR_BILLING_CODE_RE.test(String(code || '').toLowerCase());
+}
+
+/**
+ * Parse an HTTP error body ONCE into its contract fields. `message` is the
+ * body's own message (untruncated); callers truncate for diagnostics.
+ */
+export function parseErrorBody(text) {
+  let json = null;
+  try {
+    json = JSON.parse(String(text || ''));
+  } catch {}
+  const error = isObject(json?.error) ? json.error : isObject(json) ? json : null;
+  const rawCode = error?.code ?? error?.type ?? (typeof json?.error === 'string' ? json.error : null);
+  const code = typeof rawCode === 'string' && rawCode.trim() ? rawCode.trim().toLowerCase() : '';
+  const message = typeof error?.message === 'string' ? error.message : '';
+  return { json, error, code, message };
+}
+
+function epochMsFrom(value) {
+  if (typeof value === 'string' && value.trim() && !Number.isFinite(Number(value))) {
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+  }
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  // Epoch seconds (the wire form) vs epoch milliseconds.
+  return n < 1e12 ? Math.round(n * 1000) : Math.round(n);
+}
+
+/** Absolute quota reset time (epoch ms) from the first source carrying one; 0 when none. */
+export function resetAtFrom(...sources) {
+  for (const source of sources) {
+    if (!isObject(source)) continue;
+    const absolute = epochMsFrom(source.resets_at ?? source.reset_at ?? source.resetsAt);
+    if (absolute) return absolute;
+    const inSeconds = Number(source.resets_in_seconds ?? source.reset_in_seconds);
+    if (Number.isFinite(inSeconds) && inSeconds > 0) return Date.now() + Math.round(inSeconds * 1000);
+  }
+  return 0;
+}
+
+// ── User-facing messages for typed wire errors ───────────────────────────────
+const QUOTA_EXCEEDED_MESSAGE = 'Quota exceeded. Check your plan and billing details.';
+const USAGE_NOT_INCLUDED_MESSAGE =
+  'To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus.';
+const SERVER_OVERLOADED_MESSAGE = 'Selected model is at capacity. Please try a different model.';
+const WS_CONNECTION_LIMIT_MESSAGE =
+  'Responses websocket connection limit reached (60 minutes). Create a new websocket connection to continue.';
+const PREVIOUS_RESPONSE_NOT_FOUND_MESSAGE = 'Previous response was not found. Retrying the full request.';
+const QUOTA_EXCEEDED_CODES = new Set([
+  'insufficient_quota',
+  'credit_balance_exhausted',
+  'organization_spend_limit_exceeded',
+  'project_spend_limit_exceeded',
+  'organization_usage_limit_exceeded',
+]);
+// Wire codes whose own message is empty fall back to this copy.
+const FALLBACK_MESSAGES = Object.freeze({
+  websocket_connection_limit_reached: WS_CONNECTION_LIMIT_MESSAGE,
+  previous_response_not_found: PREVIOUS_RESPONSE_NOT_FOUND_MESSAGE,
+});
+
+function headerValue(headers, name) {
+  if (!headers || typeof headers !== 'object') return '';
+  if (typeof headers.get === 'function') return String(headers.get(name) ?? '').trim();
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower) return String(Array.isArray(value) ? value[0] : (value ?? '')).trim();
+  }
+  return '';
+}
+
+function ordinalSuffix(day) {
+  if (day >= 11 && day <= 13) return 'th';
+  return { 1: 'st', 2: 'nd', 3: 'rd' }[day % 10] || 'th';
+}
+
+/** Retry timestamp: "3:04 PM" today, else "Mar 5th, 2026 3:04 PM" (local time). */
+export function formatRetryTimestamp(resetsAtMs, now = Date.now()) {
+  const reset = new Date(resetsAtMs);
+  const time = reset.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', hour12: true });
+  if (reset.toDateString() === new Date(now).toDateString()) return time;
+  const month = reset.toLocaleDateString('en-US', { month: 'short' });
+  return `${month} ${reset.getDate()}${ordinalSuffix(reset.getDate())}, ${reset.getFullYear()} ${time}`;
+}
+
+const WORKSPACE_REACHED_MESSAGES = Object.freeze({
+  workspace_owner_credits_depleted: 'Your workspace is out of credits. Add credits to continue.',
+  workspace_member_credits_depleted:
+    'Your workspace is out of credits. Ask your workspace owner to refill in order to continue.',
+  workspace_owner_usage_limit_reached:
+    'You hit your spend cap set in your workspace. Increase your spend cap to continue.',
+  workspace_member_usage_limit_reached:
+    'You hit your spend cap set by the owner of your workspace. Ask an owner to increase your spend cap to continue.',
+});
+const PRO_PLANS = new Set(['pro', 'prolite', 'promax']);
+const ADMIN_PLANS = new Set([
+  'team',
+  'self_serve_business_prolite',
+  'self_serve_business_usage_based',
+  'business',
+  'ent26',
+  'enterprise_cbp_automation',
+  'enterprise_cbp_usage_based',
+]);
+
+/**
+ * Usage-limit copy: per-limit name first, then workspace
+ * credits / spend cap, then the promo message, then the plan upgrade copy.
+ * @param {{planType?: string, resetsAtMs?: number, promo?: string, reachedType?: string, limitName?: string, now?: number}} f
+ */
+export function usageLimitMessage({ planType, resetsAtMs, promo, reachedType, limitName, now } = {}) {
+  const at = resetsAtMs ? formatRetryTimestamp(resetsAtMs, now) : '';
+  const suffix = at ? ` Try again at ${at}.` : ' Try again later.';
+  const suffixOr = at ? ` or try again at ${at}.` : ' or try again later.';
+  const name = String(limitName || '').trim();
+  if (name && !/^(codex|gpt-reserve)$/i.test(name)) {
+    return `You’ve hit your usage limit for ${name}. Switch to another model now,${suffixOr}`;
+  }
+  const workspace = WORKSPACE_REACHED_MESSAGES[String(reachedType || '').toLowerCase()];
+  if (workspace) return workspace;
+  if (promo) return `You’ve hit your usage limit. ${promo},${suffixOr}`;
+  const plan = String(planType || '').toLowerCase();
+  if (plan === 'plus') {
+    return `You’ve hit your usage limit. Upgrade to Pro (https://chatgpt.com/explore/pro), visit https://chatgpt.com/settings/usage to purchase more credits${suffixOr}`;
+  }
+  if (ADMIN_PLANS.has(plan)) {
+    return `You’ve hit your usage limit. To get more access now, send a request to your admin${suffixOr}`;
+  }
+  if (plan === 'free' || plan === 'go') {
+    return `You’ve hit your usage limit. Upgrade to Plus to continue using Codex (https://chatgpt.com/explore/plus),${suffixOr}`;
+  }
+  if (PRO_PLANS.has(plan)) {
+    return `You’ve hit your usage limit. Visit https://chatgpt.com/settings/usage to purchase more credits${suffixOr}`;
+  }
+  return `You’ve hit your usage limit.${suffix}`;
+}
+
+/** The user-facing copy for a typed wire error, or '' when none applies. */
+function typedWireErrorMessage({ code, type, error, headers, resetAt }) {
+  if (type === 'usage_limit_reached' || code === 'usage_limit_reached') {
+    const limitId = headerValue(headers, 'x-codex-active-limit').toLowerCase().replace(/_/g, '-');
+    return usageLimitMessage({
+      planType: error?.plan_type,
+      resetsAtMs: resetAt,
+      promo: headerValue(headers, 'x-codex-promo-message'),
+      reachedType: headerValue(headers, 'x-codex-rate-limit-reached-type'),
+      limitName: limitId ? headerValue(headers, `x-${limitId}-limit-name`) : '',
+    });
+  }
+  if (type === 'usage_not_included' || code === 'usage_not_included') return USAGE_NOT_INCLUDED_MESSAGE;
+  if (QUOTA_EXCEEDED_CODES.has(code) || type === 'insufficient_quota') return QUOTA_EXCEEDED_MESSAGE;
+  if (code === 'server_is_overloaded') return SERVER_OVERLOADED_MESSAGE;
+  const fallback = FALLBACK_MESSAGES[code];
+  return fallback && !String(error?.message || '').trim() ? fallback : '';
+}
+
+// Swap the server's own text inside `err.message` for the mapped copy; the
+// original stays on providerError. `userMessage` always carries the copy.
+function applyTypedWireMessage(err, mapped, original) {
+  err.userMessage = mapped;
+  const current = String(err.message || '');
+  const raw = String(original || '');
+  for (const needle of [raw, raw.slice(0, 200)]) {
+    if (needle && current.endsWith(needle)) {
+      err.message = current.slice(0, current.length - needle.length) + mapped;
+      return;
+    }
+  }
+  if (!raw && current) err.message = `${current}: ${mapped}`;
+}
+/**
+ * Stamp the contract onto `err`. Every field is optional input; only the
+ * ones present are written, and a field already on `err` is never replaced
+ * by an absent one.
+ *
+ * @param {Error} err
+ * @param {object} src
+ * @param {number} [src.status]
+ * @param {object} [src.headers]     Headers or plain object
+ * @param {string} [src.code]        already-lowercased code
+ * @param {object} [src.error]       parsed error object (code/type/resets_at/headers)
+ * @param {object} [src.event]       wire event the error was built from
+ */
+export function applyErrorContract(err, { status, headers, code, error, event } = {}) {
+  try {
+    const n = Number(status);
+    if (Number.isFinite(n) && n >= 100 && n <= 599) {
+      err.status = n;
+      err.httpStatus = n;
+    }
+    const wireHeaders = headers ?? error?.headers ?? event?.error?.headers ?? event?.response?.error?.headers ?? event?.headers;
+    if (wireHeaders && typeof wireHeaders === 'object') err.headers = wireHeaders;
+    const rawCode = code ?? error?.code ?? error?.type ?? null;
+    if (typeof rawCode === 'string' && rawCode.trim()) err.code = rawCode.trim().toLowerCase();
+    const resetAt = resetAtFrom(error, event?.error, event?.response?.error, event);
+    if (resetAt) err.resetAt = resetAt;
+    const retryAfterMs = retryAfterMsFromError(err);
+    if (retryAfterMs != null) {
+      err.retryAfterMs = retryAfterMs;
+      // Server advice is a deadline captured once, so a
+      // later transport switch cannot restart or skip it.
+      if (err.retryAfterAt == null) err.retryAfterAt = Date.now() + retryAfterMs;
+    }
+    const type = typeof error?.type === 'string' ? error.type.trim().toLowerCase() : '';
+    const mapped = typedWireErrorMessage({ code: err.code || '', type, error, headers: err.headers, resetAt: err.resetAt });
+    if (mapped) applyTypedWireMessage(err, mapped, error?.message);
+  } catch {}
+  return err;
+}
+
+/**
+ * A response.incomplete with reason `content_filter` is a policy refusal:
+ * type it so no layer mistakes it for a transient or untyped failure. The
+ * wire event is deliberately NOT attached as `responseFailed` (that marker
+ * makes unknown codes default-retryable).
+ */
+export function markContentFilter(err, reason) {
+  if (String(reason || '').trim().toLowerCase() !== 'content_filter') return err;
+  err.code = 'content_filter';
+  err.providerErrorCode = 'content_filter';
+  return err;
+}
+
+/**
+ * The error for a non-2xx HTTP response whose body has been read as `text`.
+ * The message carries a bounded diagnostic; the structured fields come from
+ * the full parsed body.
+ */
+export function httpResponseError({ label, status, headers, text, initialResponse = false, diagnosticLimit = 200 }) {
+  const parsed = parseErrorBody(text);
+  const diagnostic = (parsed.message || String(text || '')).slice(0, diagnosticLimit);
+  const err = new Error(diagnostic ? `${label} ${status}: ${diagnostic}` : `${label} ${status}`);
+  if (initialResponse) err.initialResponseError = true;
+  if (parsed.error) err.providerError = parsed.error;
+  if (parsed.code) err.providerErrorCode = parsed.code;
+  return applyErrorContract(err, { status, headers, code: parsed.code, error: parsed.error, event: parsed.json });
+}
+
+// The route decides the HTTP/SSE label: the api-key `openai` provider is not OAuth.
+export const httpLabel = (auth) => (auth?.type === 'openai-direct' ? 'OpenAI HTTP fallback' : 'OpenAI OAuth HTTP fallback');
+
+/**
+ * Changing transport must not bypass the server's retry deadline.
+ * Sleeps until the deadline the failed attempt captured (abortable).
+ */
+export async function waitForRetryDeadline(err, externalSignal, sleepFn) {
+  // retryAfterMsFromError reports what is left of the captured retryAfterAt.
+  const remaining = retryAfterMsFromError(err) ?? 0;
+  if (!(remaining > 0)) return;
+  await sleepWithAbort(remaining, externalSignal, sleepFn, 'OpenAI transport fallback wait aborted');
+}

package/src/runtime/agent/orchestrator/providers/openai-http-sse-request.mjs

@@ -9,11 +9,17 @@
 import zlib from 'node:zlib';
 import { traceAgentFetch } from '../agent-trace.mjs';
 import { PROVIDER_HTTP_RESPONSE_TIMEOUT_MS, createTimeoutSignal } from '../stall-policy.mjs';
+import { CODEX_REQUEST_RETRY_BACKOFF_MS, CODEX_RETRY_JITTER_RATIO } from './openai-retry-policy.mjs';
 import { classifyError, jitterDelayMs, retryAfterMsFromError, sleepWithAbort } from './retry-classifier.mjs';
+import { emitProviderRetryStage } from './retry-executor.mjs';
+import { adviceGatedRetry } from './retry-midstream.mjs';
+import { TERMINAL_EDGE_STATUSES } from './retry-classification.mjs';
+import { DETERMINISTIC_KINDS, providerErrorKind } from './provider-error-kind.mjs';
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { getLlmDispatcher, recycleLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
 import { CODEX_RESPONSES_URL } from './openai-codex-endpoints.mjs';
 import { captureCodexTurnState } from './openai-turn-state.mjs';
+import { httpLabel, httpResponseError } from './openai-error-contract.mjs';
 
 // Public OpenAI Responses API endpoint for the api-key `openai` provider.
 // The openai-direct WS transport hits the same origin (openai-ws-pool
@@ -22,9 +28,28 @@ import { captureCodexTurnState } from './openai-turn-state.mjs';
 // openai-oauth. Same Responses SSE wire format, only endpoint + auth differ.
 const OPENAI_DIRECT_RESPONSES_URL = 'https://api.openai.com/v1/responses';
 const CODEX_REQUEST_MAX_RETRIES = 4;
-const CODEX_REQUEST_BACKOFF_MS = Object.freeze([200, 400, 800, 1600]);
-const CODEX_RETRY_JITTER_RATIO = 0.1;
+// Advice-gated retry for the OpenAI request loops (same options the shared
+// withRetry takes): an overload and an untyped 429 retry only with server advice.
+const OPENAI_REQUEST_RETRY_OPTS = Object.freeze({
+  overloadRetryRequiresAdvice: true,
+  generic429RetryRequiresAdvice: true,
+  backoffMs: CODEX_REQUEST_RETRY_BACKOFF_MS,
+  retryJitterRatio: CODEX_RETRY_JITTER_RATIO,
+});
 
+
+// Request-layer retry: 5xx and typed transport
+// failures only. 408 and 429 are NOT retried here; they surface to the outer
+// stream-retry layer, which owns their budget and honors Retry-After.
+// A deterministic refusal (quota, billing, entitlement, policy, auth,
+// permission, invalid request) is terminal whatever status carries it.
+function isRetryableHttpFailure(err) {
+  const status = err.httpStatus;
+  if (!(status >= 500 && status <= 599) || TERMINAL_EDGE_STATUSES.has(status)) return false;
+  const { kind } = providerErrorKind(err);
+  if (DETERMINISTIC_KINDS.has(kind)) return false;
+  return adviceGatedRetry(err, OPENAI_REQUEST_RETRY_OPTS) !== false;
+}
 // Request-body zstd gate. Namespace import: on Node runtimes without zlib
 // zstd bindings the named export would fail at module load, so the call site
 // typeof-guards zlib.zstdCompressSync instead.
@@ -65,13 +90,15 @@ async function postWithRetries({
   onStageChange,
   _sleepFn,
 }) {
+  const label = httpLabel(auth);
   let bodyForSend = encodeRequestBody(auth, rawBytes);
   let response;
+  let httpError = null;
   for (let attempt = 0; attempt <= CODEX_REQUEST_MAX_RETRIES; attempt++) {
     const headerTimeout = createTimeoutSignal(
       totalTimeout.signal,
       PROVIDER_HTTP_RESPONSE_TIMEOUT_MS,
-      'OpenAI OAuth HTTP fallback initial response'
+      `${label} initial response`
     );
     let requestError = null;
     try {
@@ -113,7 +140,19 @@ async function postWithRetries({
       attempt--;
       continue;
     }
-    const retryableStatus = response && response.status >= 500 && response.status <= 599;
+    // The error body is read exactly once, here, into the contract fields.
+    httpError = null;
+    if (response && !response.ok) {
+      const text = await response.text().catch(() => '');
+      httpError = httpResponseError({
+        label,
+        status: response.status,
+        headers: response.headers,
+        text,
+        initialResponse: true,
+      });
+    }
+    const retryableStatus = httpError !== null && isRetryableHttpFailure(httpError);
     // Typed transient transport failures only (errno / SDK connection
     // type). An unknown pre-response failure throws immediately instead of
     // re-issuing the POST.
@@ -135,30 +174,36 @@ async function postWithRetries({
       // Reissuing the POST is a REPLAY: allowed for a typed transient
       // failure of the initial request, denied once the failure carries
       // exposure evidence (relayed output / dispatched tool call).
-      const attemptFailure =
-        requestError ||
-        Object.assign(new Error(`OpenAI OAuth HTTP fallback ${response.status}`), {
-          httpStatus: response.status,
-          headers: response.headers,
-          initialResponseError: true,
-        });
+      const attemptFailure = requestError || httpError;
       if (readStreamOutcome(attemptFailure).replaySafe !== true) {
-        if (response) await response.arrayBuffer().catch(() => {});
         totalTimeout.cleanup();
         throw attemptFailure;
       }
-      // A non-success response has not exposed any streamed output. Drain
-      // its body before reissuing so the dispatcher can reuse the socket.
-      if (response) await response.arrayBuffer().catch(() => {});
       // Server advice (Retry-After / Retry-After-Ms) replaces the local curve.
-      const raw = CODEX_REQUEST_BACKOFF_MS[attempt];
-      await sleepWithAbort(
-        retryAfterMsFromError(attemptFailure) ?? jitterDelayMs(raw, CODEX_RETRY_JITTER_RATIO),
-        externalSignal,
-        _sleepFn,
-        'OpenAI OAuth HTTP request retry backoff aborted'
-      );
+      // Uncapped for retryable errors; the attempt count is
+      // the bound, and the abort signal cancels the wait.
+      // The shared schedule carries a leading duplicate (withRetry convention).
+    const raw = OPENAI_REQUEST_RETRY_OPTS.backoffMs[attempt + 1];
+      const delayMs = retryAfterMsFromError(attemptFailure) ?? jitterDelayMs(raw, OPENAI_REQUEST_RETRY_OPTS.retryJitterRatio);
+      emitProviderRetryStage(onStageChange, {
+        attempt: attempt + 2,
+        maxAttempts: CODEX_REQUEST_MAX_RETRIES + 1,
+        lastErr: attemptFailure,
+        delayMs,
+      });
+      try {
+        await sleepWithAbort(
+          delayMs,
+          externalSignal || totalTimeout.signal,
+          _sleepFn,
+          `${label} request retry backoff aborted`
+        );
+      } catch (abortErr) {
+        totalTimeout.cleanup();
+        throw abortErr;
+      }
       response = undefined;
+      httpError = null;
       continue;
     }
     if (requestError) {
@@ -169,7 +214,7 @@ async function postWithRetries({
     }
     break;
   }
-  return response;
+  return { response, httpError };
 }
 
 export async function openHttpSseResponse({
@@ -187,7 +232,7 @@ export async function openHttpSseResponse({
 }) {
   const fetchStartedAt = Date.now();
   const responsesUrl = auth?.type === 'openai-direct' ? OPENAI_DIRECT_RESPONSES_URL : CODEX_RESPONSES_URL;
-  const response = await postWithRetries({
+  const { response, httpError } = await postWithRetries({
     responsesUrl,
     headers,
     rawBytes: Buffer.from(JSON.stringify(body)),
@@ -208,14 +253,9 @@ export async function openHttpSseResponse({
     transport: 'http',
   });
 
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    const err = new Error(`OpenAI OAuth HTTP fallback ${response.status}: ${text.slice(0, 200)}`);
-    err.httpStatus = response.status;
-    err.headers = response.headers;
-    err.initialResponseError = true;
+  if (httpError) {
     totalTimeout.cleanup();
-    throw err;
+    throw httpError;
   }
   if (auth?.type !== 'openai-direct') {
     const responseTurnState = response.headers?.get?.('x-codex-turn-state');
@@ -223,7 +263,7 @@ export async function openHttpSseResponse({
   }
   if (!response.body) {
     totalTimeout.cleanup();
-    throw Object.assign(new Error('OpenAI OAuth HTTP fallback returned no response body'), {
+    throw Object.assign(new Error(`${httpLabel(auth)} returned no response body`), {
       initialResponseError: true,
     });
   }