@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/vision/eligibility.ts

@@ -35,6 +35,54 @@ import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-dest
  */
 export type VisionSidecarBackend = "openai" | "anthropic" | "routed";
 
+/**
+ * Input modalities an explicit custom row declares for one routed model.
+ *
+ * A custom row is the operator's own definition of that model, so its declaration outranks the
+ * provider-level hints the predicates below read. Without this the two halves of one config
+ * disagreed in production: the catalog overlay in `src/codex/catalog/routed-gather.ts` copies
+ * `customModels[].inputModalities` onto the row and the dashboard showed "text, image", while
+ * the request path consulted only `providers[].noVisionModels` / `modelInputModalities` and
+ * stripped the image before dispatch. A model the operator had declared image-capable therefore
+ * received an omission marker instead of its attachment.
+ *
+ * Precedence, highest first: `modelCapabilities` (the documented per-model capability
+ * declaration), then this custom-row declaration, then `noVisionModels`, then
+ * `modelInputModalities`, then registry/vendor metadata. `modelCapabilities` stays on top
+ * because it is the dedicated capability axis and the CLI `--text-only` flag writes it; when the
+ * two explicit forms contradict each other the more specific axis wins.
+ *
+ * Matching is exact on the routed identity — provider name and native model id, the pair the
+ * custom-model API keys rows by. A row that declares no modalities returns `undefined` rather
+ * than `["text"]`, so it stays silent instead of turning into a text-only claim.
+ */
+export function customRowInputModalities(
+  config: Pick<OcxConfig, "customModels">,
+  providerName: string,
+  modelId: string,
+): string[] | undefined {
+  for (const row of config.customModels ?? []) {
+    if (row.provider !== providerName || row.modelId !== modelId) continue;
+    if (Array.isArray(row.inputModalities) && row.inputModalities.length > 0) {
+      return [...row.inputModalities];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The custom row's verdict for one model, in the shape the predicates need:
+ * `true`/`false` when the row declares modalities, `undefined` when it declares none.
+ */
+function customRowAcceptsImageInput(
+  config: Pick<OcxConfig, "customModels">,
+  providerName: string,
+  modelId: string,
+): boolean | undefined {
+  const declared = customRowInputModalities(config, providerName, modelId);
+  return declared === undefined ? undefined : declared.includes("image");
+}
+
 /** The two sides every deployment has; also the empty-auth fallback set. */
 export type UniversalVisionBackend = "openai" | "anthropic";
 
@@ -60,6 +108,14 @@ export interface VisionCandidateModel {
   native?: boolean;
 }
 
+/**
+ * The config slice the capability predicates need. `customModels` is optional so provider-only
+ * callers and unit tests keep compiling; a caller that omits it is simply silent about custom
+ * rows rather than wrong about them.
+ */
+export type VisionCapabilityConfig =
+  Pick<OcxConfig, "providers"> & { customModels?: OcxConfig["customModels"] };
+
 export interface VisionModelOption {
   value: string;
   label: string;
@@ -142,20 +198,31 @@ function enrichedProviderForVision(
 }
 
 function isVisionSidecarConsumerWithCache(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   providerName: string,
   modelId: string,
   cache: EnrichedProviderCache,
 ): boolean {
   const provider = enrichedProviderForVision(config, providerName, cache);
-  return provider !== undefined && isModelVisionSidecarConsumer(provider, modelId);
+  if (provider === undefined) return false;
+  // Documented precedence, highest first: the dedicated per-model capability axis, then the
+  // operator's own custom row, then the provider-level hints. Reading the custom row ahead of
+  // `modelCapabilities` would let it override the more specific axis.
+  const capabilityDeclared = Object.hasOwn(provider.modelCapabilities ?? {}, modelId)
+    ? provider.modelCapabilities?.[modelId]?.inputModalities : undefined;
+  if (capabilityDeclared !== undefined) {
+    return capabilityDeclared.includes("text") && !capabilityDeclared.includes("image");
+  }
+  const customDeclared = customRowInputModalities(config, providerName, modelId);
+  if (customDeclared !== undefined) return customDeclared.includes("text") && !customDeclared.includes("image");
+  return isModelVisionSidecarConsumer(provider, modelId);
 }
 
 /**
  * Is this model listed as one the sidecar describes FOR? Such a model cannot be
  * the describer, and its advertised modalities are untrustworthy.
  */
-export function isVisionSidecarConsumer(config: Pick<OcxConfig, "providers">, providerName: string, modelId: string): boolean {
+export function isVisionSidecarConsumer(config: VisionCapabilityConfig, providerName: string, modelId: string): boolean {
   return isVisionSidecarConsumerWithCache(config, providerName, modelId, new Map());
 }
 
@@ -165,23 +232,30 @@ export function isVisionSidecarConsumer(config: Pick<OcxConfig, "providers">, pr
  * which callers treat as eligible.
  */
 export function modelAcceptsImageInput(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
 ): boolean | undefined {
   return modelAcceptsImageInputWithCache(config, candidate, new Map());
 }
 
 function modelAcceptsImageInputWithCache(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
   cache: EnrichedProviderCache,
 ): boolean | undefined {
   if (candidate.native === true || (candidate.provider === "openai" && SUPPORTED_NATIVE_OPENAI_SLUGS.has(candidate.id))) {
     const nativeProvider = enrichedProviderForVision(config, candidate.provider, cache);
-    if (nativeProvider && isModelVisionSidecarConsumer(nativeProvider, candidate.id)) return false;
     const declared = Object.hasOwn(nativeProvider?.modelCapabilities ?? {}, candidate.id)
       ? nativeProvider?.modelCapabilities?.[candidate.id]?.inputModalities : undefined;
     if (declared !== undefined) return declared.includes("image");
+    // The catalog already lets an explicit custom row replace the native modality list for the
+    // same slug; consult it here too or the row would advertise what the request path ignores.
+    const fromCustomRow = customRowAcceptsImageInput(config, candidate.provider, candidate.id);
+    if (fromCustomRow !== undefined) return fromCustomRow;
+    // The sidecar hints come after both explicit declarations, matching the documented order.
+    // Ahead of them a `noVisionModels` membership would short-circuit to text-only before the
+    // operator's own row was read.
+    if (nativeProvider && isModelVisionSidecarConsumer(nativeProvider, candidate.id)) return false;
     return advertisesImageInput(nativeInputModalities(candidate.id)) ?? true;
   }
   if (isVisionSidecarConsumerWithCache(config, candidate.provider, candidate.id, cache)) return false;
@@ -189,6 +263,11 @@ function modelAcceptsImageInputWithCache(
   const declared = Object.hasOwn(provider?.modelCapabilities ?? {}, candidate.id)
     ? provider?.modelCapabilities?.[candidate.id]?.inputModalities : undefined;
   if (declared !== undefined) return declared.includes("image");
+  // Ahead of the provider's own hints: this row is the operator's definition of this exact model,
+  // and the catalog overlay reads the same field. Behind modelCapabilities, which is the dedicated
+  // capability axis the CLI `--text-only` writes.
+  const fromCustomRow = customRowAcceptsImageInput(config, candidate.provider, candidate.id);
+  if (fromCustomRow !== undefined) return fromCustomRow;
   const configuredModalities = provider ? modelRecordValue(provider.modelInputModalities, candidate.id) : undefined;
   const fromConfiguredModalities = advertisesImageInput(configuredModalities);
   if (fromConfiguredModalities !== undefined) return fromConfiguredModalities;
@@ -206,14 +285,14 @@ function modelAcceptsImageInputWithCache(
 
 /** Eligible = not a sidecar consumer, and not positively known to be text-only. */
 export function isVisionEligibleModel(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
 ): boolean {
   return isVisionEligibleModelWithCache(config, candidate, new Map());
 }
 
 function isVisionEligibleModelWithCache(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
   cache: EnrichedProviderCache,
 ): boolean {
@@ -274,7 +353,7 @@ function baselineCandidate(
  * backend, and only `value` reaches the client, so first-wins costs nothing.
  */
 export function visionEligibleModelOptions(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidates: readonly VisionCandidateModel[],
   enabledBackends: readonly VisionSidecarBackend[],
   anthropicProviderName?: string,

package/src/vision/plan.ts

@@ -5,7 +5,11 @@ import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import type { CodexAuthPolicyConfig } from "../codex/auth-context";
 import { isCodexReserveRequestEligible } from "../codex/loopback-target";
 import type { DataPlaneAdmission } from "../server/auth-cors";
-import { isModelVisionSidecarConsumer as isModelTextOnly, modelAcceptsImageInput } from "./eligibility";
+import {
+  customRowInputModalities,
+  isModelVisionSidecarConsumer as isModelTextOnly,
+  modelAcceptsImageInput,
+} from "./eligibility";
 import { normalizeVisionReasoningForModel } from "./reasoning";
 import { resolveSidecarAuth } from "../sidecar/auth";
 import { DEFAULT_VISION_TIMEOUT_MS, MAX_VISION_TIMEOUT_MS, MIN_VISION_TIMEOUT_MS } from "./timeout-bounds";
@@ -95,23 +99,40 @@ function messagesHaveImage(parsed: OcxParsedRequest): boolean {
 /**
  * Direct-image admission for a routed target. Returns true when capability evidence proves the
  * target cannot accept image input, so the caller must describe or strip the image first.
- * Explicit text-only config, an explicit per-model modality list without `image`, and
- * proven-negative registry/vendor metadata each require the vision preprocessor. A genuinely
- * unknown custom model is NOT guessed blind: it keeps the established pass-through behaviour.
- * The provider-only fallback keeps legacy unit callers stable; production dispatch always
- * supplies providerName so the complete capability chain is consulted.
+ * Evidence is consulted highest-first: `modelCapabilities` (the dedicated per-model capability
+ * axis), an explicit custom row for the same routed identity, `noVisionModels`, an explicit
+ * per-model modality list without `image`, and finally proven-negative registry/vendor metadata.
+ * Any of them can require the vision preprocessor. A genuinely unknown custom model is NOT
+ * guessed blind: it keeps the established pass-through behaviour. The provider-only fallback
+ * keeps legacy unit callers stable; production dispatch always supplies providerName so the
+ * complete capability chain is consulted.
  */
 export function requiresVisionPreprocessing(
-  config: Pick<OcxConfig, "providers">,
+  config: Pick<OcxConfig, "providers"> & { customModels?: OcxConfig["customModels"] },
   provider: Pick<OcxProviderConfig, "noVisionModels" | "modelInputModalities" | "modelCapabilities">,
   modelId: string,
   providerName?: string,
 ): boolean {
-  if (isModelTextOnly(provider, modelId)) return true;
   const runtimeDeclared = Object.hasOwn(provider.modelCapabilities ?? {}, modelId)
     ? provider.modelCapabilities?.[modelId]?.inputModalities
     : undefined;
+  // `modelCapabilities` is the dedicated per-model capability axis, so it outranks everything
+  // below — including an explicit custom row that disagrees. The CLI `--text-only` flag writes it.
   if (runtimeDeclared !== undefined) return !runtimeDeclared.includes("image");
+  // An explicit custom row outranks the provider-level hints below, mirroring the catalog overlay
+  // in `src/codex/catalog/routed-gather.ts` that already copies this same declaration onto the
+  // advertised row. Without it the dashboard advertised "text, image" from the operator's own row
+  // while this predicate stripped the image before dispatch.
+  const customDeclared = providerName === undefined
+    ? undefined
+    : customRowInputModalities(config, providerName, modelId);
+  // Same rule as the `modelCapabilities` branch above: the declaration answers "can this model
+  // take an image", not "is it a text model". A row that lists only `audio` or `video` excludes
+  // image input just as `["text"]` does, and `modelAcceptsImageInput` already answers "no image"
+  // for it; the narrower `includes("text")` test here made the two predicates disagree and sent
+  // the attachment to a model that cannot read it.
+  if (customDeclared !== undefined) return !customDeclared.includes("image");
+  if (isModelTextOnly(provider, modelId)) return true;
   const runtimeModalities = modelRecordValue(provider.modelInputModalities, modelId);
   if (Array.isArray(runtimeModalities) && runtimeModalities.length > 0) {
     return !runtimeModalities.includes("image");
@@ -129,9 +150,12 @@ function usableRoutedVisionModel(config: OcxConfig): string | undefined {
   if (!routedModel || sep <= 0) return undefined;
   const targetProvider = routedModel.slice(0, sep);
   const targetId = routedModel.slice(sep + 1);
-  const targetProviderConfig = config.providers?.[targetProvider];
+  // `modelAcceptsImageInput` is the one predicate here: it resolves the whole capability chain,
+  // custom row included. The provider-only `isModelTextOnly` that used to be ANDed in could only
+  // subtract — it never saw a custom row, so a describer the operator had declared image-capable
+  // was refused for a provider hint that same row overrides.
   return modelAcceptsImageInput(config, { provider: targetProvider, id: targetId }) !== false
-    && !(targetProviderConfig && isModelTextOnly(targetProviderConfig, targetId)) ? routedModel : undefined;
+    ? routedModel : undefined;
 }
 
 export function shouldResolveOpenAiVisionSidecar(

package/src/web-search/executor.ts

@@ -3,7 +3,14 @@ import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
 import { redactSecretString } from "../lib/redact";
 import { sidecarEnter } from "../lib/sidecar-tracker";
-import { applyUpstreamRecoveryInit, fetchWithResetRetry } from "../lib/upstream-retry";
+import {
+  applyUpstreamRecoveryInit,
+  fetchWithResetRetry,
+  releaseResponseBodyBestEffort,
+  retryBackoffDelayMs,
+  sleepWithAbort,
+  RETRY_AFTER_CEILING_MS,
+} from "../lib/upstream-retry";
 import { withUpstreamHttpVersion } from "../lib/upstream-http-version";
 import { parseSidecarSSE, type WebSearchResult } from "./parse";
 import type { CodexUpstreamOutcome } from "../codex/routing";
@@ -35,6 +42,22 @@ export const IMAGE_INSTRUCTION =
 
 /** A search result, or an `error` string when the search couldn't run (surfaced as a tool result). */
 export type SidecarOutcome = WebSearchResult & { error?: string };
+
+/**
+ * Bounded same-search 429 replays for the sidecar POST.
+ *
+ * The forward backend throttles burst sidecar traffic, and without a replay the 429 becomes a
+ * failed tool result that poisons the query for the whole turn (see failedQueries in loop.ts).
+ * 1 initial send + 2 replays; Retry-After is honored as a lower bound and capped by
+ * RETRY_AFTER_CEILING_MS (an instruction past the ceiling ends with the 429 instead of
+ * parking the search). Each wait releases the unread 429 body first so sockets do not
+ * accumulate under a rate-limit storm. Abort or timeout ends the wait through the existing
+ * catch, exactly like an abort during the SSE parse.
+ */
+const SIDECAR_429_MAX_ATTEMPTS = 3;
+const SIDECAR_429_BASE_DELAY_MS = 1_000;
+const SIDECAR_429_MAX_DELAY_MS = 10_000;
+
 export type SidecarOutcomeRecorder = (outcome: CodexUpstreamOutcome) => void;
 
 /**
@@ -79,7 +102,7 @@ export async function runWebSearch(
   const sidecarExit = sidecarEnter("web-search");
   const t0 = Date.now();
   try {
-    const res = await fetchWithResetRetry(
+    const sendOnce = () => fetchWithResetRetry(
       // Recovery nests INSIDE the version helper: applyUpstreamRecoveryInit then always receives a
       // defined init, and withUpstreamHttpVersion spreads the result, so `protocol` and the
       // recovery fields (`connection: close` + Bun's transport-level `keepalive: false`) survive
@@ -96,6 +119,22 @@ export async function runWebSearch(
       }, recovery), forwardProvider)),
       { replaySafe: true, abortSignal: linkedSignal.signal, label: "web-search-sidecar" },
     );
+    let res = await sendOnce();
+    for (let attempt = 0; res.status === 429 && attempt + 1 < SIDECAR_429_MAX_ATTEMPTS; attempt++) {
+      const delay = retryBackoffDelayMs(attempt, {
+        baseDelayMs: SIDECAR_429_BASE_DELAY_MS,
+        maxDelayMs: SIDECAR_429_MAX_DELAY_MS,
+        headers: res.headers,
+        retryAfterIsLowerBound: true,
+      });
+      // A deadline, not a clamp: an instruction past the ceiling ends the search with the
+      // 429 instead of parking it at a provider that already said it would refuse.
+      if (delay > RETRY_AFTER_CEILING_MS) break;
+      console.warn(`[web-search] sidecar HTTP 429 — retrying (${attempt + 2}/${SIDECAR_429_MAX_ATTEMPTS}) after ${delay}ms`);
+      await releaseResponseBodyBestEffort(res.body, linkedSignal.signal);
+      await sleepWithAbort(delay, linkedSignal.signal);
+      res = await sendOnce();
+    }
     // Attach the body guard before ANY branch reads it. The success path guarded itself below,
     // but the failure branch's `res.text()` runs first, so a cancel landing between fetch
     // resolution and reader attach orphaned the internal rejection (found investigating #1419).

package/src/web-search/loop.ts

@@ -333,10 +333,15 @@ export interface WebSearchLoopDeps {
    * 429 states the window's reset epoch even when it omits Retry-After -- and a rotation that
    * cannot see it cools the drained account for the short default instead of until the window
    * actually reopens. Optional so existing callers keep compiling.
+   *
+   * `retryParsed` is the exact iteration-local request the retry will be built from. The loop
+   * sends a shallow copy of the outer parsed request, so a rotation that rebinds only the outer
+   * object never reaches the wire. Optional so existing callers keep compiling.
    */
   on429?: (
     retryAfterHeader: string | null,
     responseHeaders?: Headers,
+    retryParsed?: OcxParsedRequest,
   ) => 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;
@@ -558,7 +563,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 = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers);
+        const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers, iterParsed);
         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.