@bitkyc08/opencodex 2.33.0 → 2.34.0

package/src/types/config.ts

@@ -239,6 +239,11 @@ export interface OcxClientIntegrationsConfig {
   "claude-desktop"?: boolean;
 }
 
+export interface OcxConfigRebaseProvenance {
+  version: 1;
+  deletedTopLevelKeys: string[];
+}
+
 export interface OcxConfig {
   port: number;
   /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
@@ -260,6 +265,22 @@ export interface OcxConfig {
   managementUsageMaxReadBytes?: number;
   providers: Record<string, OcxProviderConfig>;
   defaultProvider: string;
+  /** Persisted state for newly discovered provider models (#2464). Absent keeps legacy "on" behavior. */
+  modelDiscovery?: {
+    newModelPolicy?: "on" | "off";
+    knownModels?: Record<string, {
+      ids: string[];
+      removed: string[];
+      updatedAt: string;
+      /** Consecutive successful discoveries in which an active id was absent. */
+      missing?: Record<string, number>;
+    }>;
+    recentArrivals?: Record<string, Array<{ id: string; at: string }>>;
+  };
+  /** Enable the shipped model alias patterns for providers without an override. */
+  defaultModelAliases?: boolean;
+  /** Explicit top-level deletion intent used by stale whole-config rebases. */
+  configRebaseProvenance?: OcxConfigRebaseProvenance | Record<string, unknown>;
   /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
   openaiProviderTierVersion?: 1 | 2;
   /** One-time migration marker for Antigravity's static-catalog defaults. */
@@ -483,6 +504,13 @@ export interface OcxConfig {
    * those are unset — Bun's fetch honors them for all outbound calls; localhost is excluded.
    */
   proxy?: string;
+  /**
+   * Hosts that bypass `proxy` for OpenCodex's own outbound provider calls, merged into
+   * NO_PROXY at startup. Accepts a comma-separated string (NO_PROXY syntax) or an array.
+   * Loopback is always excluded regardless of this setting, and an inherited NO_PROXY is
+   * preserved — this ADDS entries, it never replaces the environment.
+   */
+  noProxy?: string | string[];
   /**
    * Upstream stall timeout (seconds). After this many seconds of no upstream data, emits
    * response.incomplete. Default 300. Min 1.
@@ -554,6 +582,15 @@ export interface OcxConfig {
    * selector map remains visible for compatibility with hand-written configurations.
    */
   codexAccountPickerEnabled?: boolean;
+  /**
+   * Show the GPT-5.3-Codex-Spark weekly window on Codex quota surfaces. Default false.
+   *
+   * Spark is a single-model window that reads 0% for most operators, and on a multi-account
+   * pool it doubles the bar count for information almost nobody acts on. Hidden by default and
+   * revealed by an explicit `true`; a malformed value reads as hidden rather than rejecting the
+   * whole config.
+   */
+  showCodexSparkQuota?: boolean;
   /** Active pool account id for next session. undefined = main (passthrough as-is). */
   activeCodexAccountId?: string;
   /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
@@ -583,6 +620,22 @@ export interface OcxConfig {
     /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
     stickyLimit?: number;
   };
+  /**
+   * Generic OAuth multi-account 429 failover (#2568). Presence-driven by default.
+   *
+   * Rotates to another logged-in account of the SAME provider when one is rate-limited, for
+   * OAuth providers that have no pool of their own — xAI, Cursor, Kimi, GitHub Copilot,
+   * Antigravity, Nous. The Codex pool and the Anthropic pool own their own rotation and are
+   * excluded; this setting changes neither.
+   *
+   * With the key absent, rotation activates when a provider has 2 or more eligible stored
+   * accounts — the same consent rule API-key pools already apply to a 2+ key pool (#2568d). A
+   * single account is a strict no-op. Set `false` to keep strict single-account behaviour;
+   * `providers.<name>.oauthAccountFailover` overrides this per provider.
+   */
+  oauthAccountFailover?: {
+    enabled?: boolean;
+  };
   /** Virtual `combo/<id>` models spanning concrete provider/model targets (issue #133). */
   combos?: Record<string, OcxComboConfig>;
   /**

package/src/types/provider.ts

@@ -115,6 +115,15 @@ export interface TierObservationContext {
   fastWire: FastWire | null;
   demandDecision: "force-fast" | "force-default" | "inherit";
   callerTier?: string;
+  /**
+   * Whether the destination's echoed `service_tier` is authoritative about Fast scheduling.
+   *
+   * The ChatGPT-internal Codex backend returns `service_tier: "default"` on turns that were in
+   * fact scheduled as priority, so treating its echo as a downgrade produced a false
+   * `response-declined` on every Fast request (#2558). Absent means "assume authoritative",
+   * preserving the behaviour for the public API where the echo does mean what it says.
+   */
+  responseTierAuthoritative?: boolean;
 }
 
 export type TierDecision =
@@ -127,6 +136,12 @@ export type TierDecision =
  * retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
  */
 export interface OcxProviderConfig {
+  /** Optional short provider namespace used only at request/catalog presentation time. */
+  alias?: string;
+  /** Native model id -> short, slash-free request alias. */
+  modelAliases?: Record<string, string>;
+  /** Override the global built-in model-alias switch for this provider. */
+  defaultAliases?: boolean;
   adapter: string;
   /**
    * Codex tool calling mode for routed models.
@@ -266,6 +281,33 @@ export interface OcxProviderConfig {
    * full set so the user can pick). See devlog issue_052_provider-model-allowlist.
    */
   selectedModels?: string[];
+  /** Override for newly discovered models. Absent/"inherit" uses the install policy. */
+  newModelPolicy?: "on" | "off" | "inherit";
+  /**
+   * Model-preset marker for `selectedModels` (#2465). Absent means "all", exactly today's
+   * semantics — an existing provider is never narrowed by an upgrade.
+   *
+   * The preset is a SEED, not a lock: `selectedModels` holds concrete ids materialized from
+   * the shipped rules, so every existing consumer and older binaries keep working against a
+   * plain allowlist. Divergence is detected at the WRITE path rather than by diffing — any user
+   * edit while the mode is "preset" flips it to "custom", after which the proxy never
+   * re-materializes. That collapses upgrade reconciliation to a version compare.
+   *
+   * Deliberately distinct from `deriveProviderPresets`, which curates WHICH PROVIDERS to offer.
+   * This curates which MODELS a provider exposes; the code says "model preset" throughout.
+   */
+  modelPreset?: {
+    mode: "preset" | "all" | "custom";
+    /** MODEL_PRESETS version materialized into `selectedModels`. */
+    appliedVersion?: number;
+    appliedAt?: string;
+    /**
+     * Set when materialization matched nothing and the provider fell back to "all". A preset
+     * must never write an empty allowlist, because empty means ALL and would silently
+     * un-curate; the fallback marker lets the next convergence retry.
+     */
+    fallback?: "preset-empty";
+  };
   /** Provider-wide fallback when context metadata is absent; otherwise caps the reported window. */
   contextWindow?: number;
   /** Per-model fallback when context metadata is absent; otherwise caps the reported window. */
@@ -309,6 +351,16 @@ export interface OcxProviderConfig {
    * providers whose registry entry declares authKind "local" (management API enforces).
    */
   authMode?: "key" | "forward" | "oauth" | "local";
+  /**
+   * Per-provider override for generic OAuth multi-account 429 failover (#2568).
+   *
+   * Rotation is presence-driven by default — 2+ logged-in accounts activate it — so this exists
+   * for the operator who accepts rotation on one provider and refuses it on another. An explicit
+   * boolean here beats the global `oauthAccountFailover` and beats presence.
+   */
+  oauthAccountFailover?: {
+    enabled?: boolean;
+  };
   /** Allow an explicitly key/oauth provider to run without a credential (for keyless local proxies). */
   keyOptional?: boolean;
   /**
@@ -341,6 +393,18 @@ export interface OcxProviderConfig {
    * Responses backend rejects Codex summary-delivery fields for that model.
    */
   modelSupportsReasoningSummaries?: Record<string, boolean>;
+  /**
+   * Model-specific Codex Responses verbosity capability. Set false when the upstream ignores
+   * `text.verbosity`; the catalog hides the no-op picker and the Responses adapter strips stale
+   * or caller-supplied values while preserving other `text` fields.
+   */
+  modelSupportsVerbosity?: Record<string, boolean>;
+  /**
+   * Provider-wide Codex Responses verbosity capability, applied to models the per-model map
+   * does not enumerate (a live-discovered id, for example). Materialized from the registry at
+   * seed/enrich time so the catalog hint pass never has to read PROVIDER_REGISTRY.
+   */
+  supportsVerbosity?: boolean;
   /**
    * Per-model wire value for Responses `stream_options.reasoning_summary_delivery`.
    * Presence also advertises reasoning-summary support for that routed model.

package/src/types/request.ts

@@ -68,6 +68,8 @@ export interface OcxParsedRequest {
   _cursorConversationId?: string;
   /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
   _clientThreadId?: string;
+  /** Cursor-only thread owner; may be an opaque process-local Desktop session/thread identity. */
+  _cursorClientThreadId?: string;
   /** Conversation/provider/account/model-bound namespace for reasoning replay state. */
   _reasoningReplayScope?: OcxReasoningReplayScopeRef;
   /**
@@ -86,7 +88,7 @@ export interface OcxParsedRequest {
    */
   _cursorIsolateConversation?: boolean;
   /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
-  _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion">;
+  _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion" | "authType">;
   /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
   _providerContinuation?: OcxProviderContinuationState;
   /** Persisted continuation considered only after the final physical route is known. */
@@ -188,8 +190,14 @@ export interface OcxImageContent {
   detail?: string;
 }
 
-/** A user/developer message content part: text or an image (vision). */
-export type OcxContentPart = OcxTextContent | OcxImageContent;
+export interface OcxVideoContent {
+  type: "video";
+  /** A base64 `data:` URL from an OpenAI-compatible `video_url` part. */
+  videoUrl: string;
+}
+
+/** A user/developer message content part: text or native media. */
+export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent;
 
 export interface OcxThinkingContent {
   type: "thinking";

package/src/types/tools.ts

@@ -32,16 +32,17 @@ export function namespacedToolName(namespace: string | undefined, name: string):
 }
 
 /**
- * Codex 0.149 unified-exec name normalization.
+ * Codex unified-exec name normalization.
  *
  * Codex's code-mode shell tool is declared as `exec` (a freeform custom tool whose own
  * description mentions the nested `await tools.exec_command(...)` helper). Routed models —
  * DeepSeek in particular — sometimes echo that helper name as the tool-call name, emitting
- * `exec_command` instead of the declared `exec`. Accept the legacy shell bridge names only
- * when the request catalog actually declares `exec` and does not itself declare the legacy
- * name (an MCP server may legitimately advertise `exec_command` under its own namespace).
+ * `exec_command` or `apply_patch` instead of the declared `exec`. Accept these nested helper
+ * names only when the request catalog actually declares `exec` and does not itself declare the
+ * emitted name (an MCP server may legitimately advertise one under its own namespace).
  */
 const LEGACY_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
+const CODE_MODE_HELPER_TOOL_NAMES = [...LEGACY_SHELL_BRIDGE_TOOL_NAMES, "apply_patch"] as const;
 
 export function normalizeDeclaredToolName(
   name: string,
@@ -49,13 +50,14 @@ export function normalizeDeclaredToolName(
 ): string {
   if (!declared || !declared.has("exec")) return name;
   if (declared.has(name)) return name;
+  if (name === "apply_patch") return "exec";
   // When the catalog explicitly declares any legacy shell bridge name, the environment
   // genuinely exposes that tool — turn normalization off so a call is never mis-routed
   // to `exec`.
   if ((LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).some(legacy => declared.has(legacy))) {
     return name;
   }
-  return (LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(name) ? "exec" : name;
+  return (CODE_MODE_HELPER_TOOL_NAMES as readonly string[]).includes(name) ? "exec" : name;
 }
 
 export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {

package/src/types.ts

@@ -61,6 +61,7 @@ export type {
   OcxCustomModel,
   OcxApiKeyEntry,
   OcxClientIntegrationsConfig,
+  OcxConfigRebaseProvenance,
   OcxConfig,
   OcxAccountPoolRotationStrategy,
   OcxComboStrategy,

package/src/usage/expected-prices.ts

@@ -39,7 +39,7 @@ export interface ExpectedPriceOverlay {
 }
 
 const GEMINI_31_PRO: Cost4 = { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 };
-const GPT56_SOL: Cost4 = { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25 };
+const GPT56_SOL: Cost4 = { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 };
 /**
  * Daybreak aliases. `daybreak-*-latest` never appears in the pricing table itself — only its
  * current snapshot does — so these tuples are the snapshot's published rates and carry
@@ -126,6 +126,10 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   // Daybreak aliases: priced as their current snapshots (red -> gpt-5.6-cyber,
   // blue -> gpt-5.6-sol). The alias ids carry no rows of their own upstream, hence
   // verified-derived. Blue deliberately reuses GPT56_SOL rather than duplicating the tuple.
+  // The `gpt-` selector is native to ChatGPT/Codex accounts. The bare aliases below belong to
+  // the separately billed API-key catalog; keep those namespaces disjoint so pricing metadata
+  // cannot make an unroutable provider/model pair look supported.
+  { provider: "openai", modelId: "gpt-daybreak-blue-latest", cost4: GPT56_SOL, source: `alias of gpt-5.6-sol ${OPENAI_GPT56_PRICING}`, verifiedAt: "2026-08-11", status: "verified-derived" },
   { provider: "openai-apikey", modelId: "daybreak-red-latest", cost4: DAYBREAK_RED, source: `alias of gpt-5.6-cyber ${OPENAI_GPT56_PRICING}`, verifiedAt: "2026-08-11", status: "verified-derived" },
   { provider: "openai-apikey", modelId: "daybreak-blue-latest", cost4: GPT56_SOL, source: `alias of gpt-5.6-sol ${OPENAI_GPT56_PRICING}`, verifiedAt: "2026-08-11", status: "verified-derived" },
   { provider: "google-antigravity", modelId: "gemini-3.1-pro-low", cost4: GEMINI_31_PRO, source: `derived: gemini-3.1-pro (<=200k tier) ${GEMINI_PRICING}`, verifiedAt: "2026-07-20", status: "verified-derived" },
@@ -223,6 +227,8 @@ export function findExpectedPriceOverlay(
 /** OpenAI Fast price multipliers retained as a compatibility export. */
 export const PRIORITY_MULTIPLIERS: Readonly<Record<string, number>> = {
   "gpt-5.6-sol": 2,
+  "gpt-daybreak-blue-latest": 2,
+  "daybreak-blue-latest": 2,
   // Post-price-cut Fast tables (https://openai.com/api-fast-mode/, 2026-08-05):
   // Terra 4/24/0.40/5 and Luna 0.40/2.40/0.04/0.50 are both 2× the corrected
   // standard tuples; the stale bases made these look like 1.6/0.4 (#907).
@@ -257,13 +263,19 @@ const XAI_PRIORITY_PRICING = "https://docs.x.ai/developers/advanced-api-usage/pr
  */
 export const PRIORITY_PRICING_RULES: readonly PriorityPricingRule[] = [
   ...["openai", "openai-apikey"].flatMap(provider =>
-    Object.entries(PRIORITY_MULTIPLIERS).map(([modelId, multiplier]): PriorityPricingRule => ({
-      provider,
-      modelId,
-      multiplier,
-      source: OPENAI_FAST_PRICING,
-      verifiedAt: "2026-08-05",
-    })),
+    Object.entries(PRIORITY_MULTIPLIERS)
+      // Daybreak's `gpt-` selector belongs to ChatGPT/Codex accounts; its bare selector belongs
+      // to the separately billed API-key catalog. All ordinary GPT ids remain valid on both.
+      .filter(([modelId]) => provider === "openai"
+        ? modelId !== "daybreak-blue-latest"
+        : modelId !== "gpt-daybreak-blue-latest")
+      .map(([modelId, multiplier]): PriorityPricingRule => ({
+        provider,
+        modelId,
+        multiplier,
+        source: OPENAI_FAST_PRICING,
+        verifiedAt: "2026-08-05",
+      })),
   ),
   ...["grok-4.5", "grok-4.6"].map((modelId): PriorityPricingRule => ({
     provider: "xai",
@@ -349,6 +361,29 @@ export const CONTEXT_TIERS: readonly ContextTier[] = [
       verifiedAt: "2026-08-03",
     })),
   ),
+  {
+    // The native Codex selector aliases gpt-5.6-sol and shares its 272k long-context tier.
+    provider: "openai",
+    modelId: "gpt-daybreak-blue-latest",
+    thresholdInputTokens: 272_000,
+    inclusive: false,
+    multiplier: OPENAI_LONG_CONTEXT,
+    confirmedPriorityRelation: "exclusive",
+    source: OPENAI_PRICING_DOC,
+    verifiedAt: "2026-08-11",
+  },
+  {
+    // The bare selector is the separately billed API-key alias. Daybreak Red has no tier row:
+    // the cyber snapshot's four long-context cells are all "-" on the pricing page.
+    provider: "openai-apikey",
+    modelId: "daybreak-blue-latest",
+    thresholdInputTokens: 272_000,
+    inclusive: false,
+    multiplier: OPENAI_LONG_CONTEXT,
+    confirmedPriorityRelation: "exclusive",
+    source: OPENAI_PRICING_DOC,
+    verifiedAt: "2026-08-11",
+  },
   {
     provider: "xai",
     modelId: "grok-4.5",
@@ -371,22 +406,6 @@ export const CONTEXT_TIERS: readonly ContextTier[] = [
     source: "https://docs.x.ai/developers/pricing",
     verifiedAt: "2026-08-18",
   },
-  {
-    // daybreak-blue-latest aliases gpt-5.6-sol, which publishes the full long-context row
-    // ($10 / $1 / $12.50 / $45). Scoped to openai-apikey ON PURPOSE: Daybreak is not
-    // routable on the Codex-login `openai` provider, so adding the alias to the shared
-    // OPENAI_GPT56_CONTEXT_MODELS list (expanded across both providers above) would mint a
-    // tier for a provider/model pair that cannot exist.
-    // daybreak-red-latest has NO tier row: the cyber snapshot's four long-context cells are
-    // all "-" on the pricing page (verified 2026-08-11).
-    provider: "openai-apikey",
-    modelId: "daybreak-blue-latest",
-    thresholdInputTokens: 272_000,
-    inclusive: false,
-    multiplier: OPENAI_LONG_CONTEXT,
-    source: OPENAI_PRICING_DOC,
-    verifiedAt: "2026-08-11",
-  },
   ...["minimax", "minimax-cn"].map((provider): ContextTier => ({
     provider,
     modelId: "MiniMax-M3",

package/src/usage/log.ts

@@ -28,6 +28,7 @@ export type AttemptRecoveryKind =
   | "key-429"
   | "rate-limit-429"
   | "anthropic-oauth-429"
+  | "oauth-account-429"
   | "image-413"
   | "opaque-blob-rejection"
   | "empty-completion";
@@ -68,6 +69,7 @@ export interface PersistedUsageAttempt {
 }
 
 export interface PersistedUsageEntry {
+  requestedAlias?: string;
   requestId: string;
   timestamp: number;
   provider: string;
@@ -218,6 +220,7 @@ const ATTEMPT_RECOVERY_KINDS = new Set<AttemptRecoveryKind>([
   "key-429",
   "rate-limit-429",
   "anthropic-oauth-429",
+  "oauth-account-429",
   "image-413",
   "opaque-blob-rejection",
   "empty-completion",

package/src/web-search/exa-executor.ts

@@ -9,10 +9,11 @@
  * Never throws; every error string passes redactSecretString.
  */
 import { fetchWithResetRetry } from "../lib/upstream-retry";
-import { signalWithTimeout } from "../lib/abort";
+import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import { redactSecretString } from "../lib/redact";
-import type { WebSearchSource } from "./parse";
+import { MAX_SIDECAR_RESPONSE_BYTES, type WebSearchSource } from "./parse";
 import type { SidecarOutcome, SidecarSettings } from "./executor";
 
 const EXA_SEARCH_URL = "https://api.exa.ai/search";
@@ -47,14 +48,44 @@ export async function runExaWebSearch(
       }),
       { abortSignal: linkedSignal.signal, label: "exa-web-search-sidecar" },
     );
-    if (!res.ok) {
-      const t = await res.text().catch(() => "");
-      // Scrub BEFORE truncating: slicing first can cut the literal key at the
-      // boundary, leaving an unscrubbable key prefix in the surviving text.
-      return { text: "", sources: [], error: `exa sidecar HTTP ${res.status}: ${scrub(t).slice(0, 200)}` };
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      let bounded: Awaited<ReturnType<typeof readBoundedResponseBytes>> | null = null;
+      try {
+        bounded = await readBoundedResponseBytes(res, {
+          maxBytes: MAX_SIDECAR_RESPONSE_BYTES,
+          signal: linkedSignal.signal,
+        });
+      } catch {
+        const reason = linkedSignal.signal.reason;
+        if (linkedSignal.signal.aborted && reason instanceof Error && reason.name === "TimeoutError") {
+          throw reason;
+        }
+        // Preserve the previous status-only/shapeless fallback for body read
+        // failures; fetch/header failures are still classified by the outer catch.
+      }
+      if (bounded?.oversized) {
+        const prefix = res.ok ? "exa sidecar response" : `exa sidecar HTTP ${res.status} response`;
+        return { text: "", sources: [], error: `${prefix} exceeded byte bound` };
+      }
+      // Response.text()/json() replace malformed UTF-8, so preserve that
+      // behavior while moving the byte bound ahead of decoding and parsing.
+      const text = bounded ? new TextDecoder().decode(bounded.bytes) : "";
+      if (!res.ok) {
+        // Scrub BEFORE truncating: slicing first can cut the literal key at the
+        // boundary, leaving an unscrubbable key prefix in the surviving text.
+        return { text: "", sources: [], error: `exa sidecar HTTP ${res.status}: ${scrub(text).slice(0, 200)}` };
+      }
+      let payload: unknown = null;
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        // The mapper owns the stable malformed/empty JSON outcome.
+      }
+      return mapExaSearchResponse(payload);
+    } finally {
+      detachBodyGuard();
     }
-    const payload = await res.json().catch(() => null);
-    return mapExaSearchResponse(payload);
   } catch (e) {
     const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
     console.warn(`[web-search] exa sidecar ${kind} (${Date.now() - t0}ms)`);

package/src/web-search/loop.ts

@@ -304,10 +304,11 @@ export interface WebSearchLoopDeps {
   /** Called before each routed-model dispatch in the loop, for attempt telemetry. Same-target 429 replays pass the `rate-limit-429` recovery kind. */
   onAttemptSend?: (recovery?: AttemptRecoveryKind) => void;
   /**
-   * 429 key-failover hook: rotate the provider's active pool key and return a rebuilt adapter,
-   * or null when the pool is exhausted (same semantics as the normal routed path).
+   * 429 failover hook: rotate the provider's active credential and return a rebuilt adapter,
+   * or null when the pool is exhausted. Async hooks support OAuth refresh; existing synchronous
+   * key-pool hooks remain valid.
    */
-  on429?: (retryAfterHeader: string | null) => ProviderAdapter | null;
+  on429?: (retryAfterHeader: string | null) => ProviderAdapter | null | Promise<ProviderAdapter | null>;
   /** Opt-in same-target 429 policy (key-auth providers). When present, 429 replays on the SAME key before on429 rotation. */
   retryOn429Policy?: Required<RateLimitRetryPolicy> | null;
   /** Called only when the final bridged Responses stream reaches completed or incomplete. */
@@ -509,7 +510,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       // 429 key-failover parity with the normal routed path: rotate pool keys until one responds
       // or the pool is exhausted (deps.on429 returns null — cooldown map guarantees termination).
       while (prepared.response.status === 429 && deps.on429) {
-        const rotated = deps.on429(prepared.response.headers.get("retry-after"));
+        const rotated = await deps.on429(prepared.response.headers.get("retry-after"));
         if (!rotated) break;
         // Never let a broken body's cancel promise outlive the cumulative header deadline. Observe
         // it, but proceed immediately to the rotated fetch under the SAME deadline signal.