@bitkyc08/opencodex 2.54.0-preview.20260914 → 2.55.0-preview.20260914

package/src/usage/log.ts

@@ -2,6 +2,7 @@ import { createHash, type Hash } from "node:crypto";
 import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
+import type { CodexAffinityMove, CodexAffinityReason } from "../codex/routing";
 import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { sanitizeLogMetadataString } from "../lib/redact";
@@ -187,6 +188,13 @@ export interface PersistedUsageEntry {
   transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
   /** Whether the terminal came from upstream or a proxy-generated tail. */
   terminalSource?: "upstream" | "synthetic";
+  /**
+   * What happened to this request's Codex pool binding, and why (#4546). A move discards the
+   * prompt-cache prefix warmed on the previous account, so it is recorded as an event rather
+   * than left to be inferred from account labels across rows. Additive; older rows omit it.
+   */
+  affinity?: CodexAffinityMove;
+  affinityReason?: CodexAffinityReason;
   /**
    * Bounded route-decision trace (RI-01): why this provider/model/account was
    * selected. Additive field; old rows without it parse unchanged. Never
@@ -248,6 +256,28 @@ export function isKnownTerminalSource(value: unknown): value is NonNullable<Pers
   return typeof value === "string" && KNOWN_TERMINAL_SOURCES.has(value as NonNullable<PersistedUsageEntry["terminalSource"]>);
 }
 
+/**
+ * The persisted entry is built by an explicit whitelist, so a field the writer sets but this
+ * normalizer does not name is dropped without a word. #4592 added the affinity record at the
+ * call site and it never reached disk for exactly that reason.
+ */
+const KNOWN_AFFINITY_MOVES = new Set<NonNullable<PersistedUsageEntry["affinity"]>>([
+  "reused", "held", "detour", "rebound", "new_bind", "cleared",
+]);
+const KNOWN_AFFINITY_REASONS = new Set<NonNullable<PersistedUsageEntry["affinityReason"]>>([
+  "healthy", "quota_headroom", "quota_refusal", "transient", "transient_hold_expired",
+  "unusable", "paused", "plan_excluded", "cooldown", "quota_avoided", "generation",
+  "expired", "model_lane",
+]);
+
+export function isKnownAffinityMove(value: unknown): value is NonNullable<PersistedUsageEntry["affinity"]> {
+  return typeof value === "string" && KNOWN_AFFINITY_MOVES.has(value as NonNullable<PersistedUsageEntry["affinity"]>);
+}
+
+export function isKnownAffinityReason(value: unknown): value is NonNullable<PersistedUsageEntry["affinityReason"]> {
+  return typeof value === "string" && KNOWN_AFFINITY_REASONS.has(value as NonNullable<PersistedUsageEntry["affinityReason"]>);
+}
+
 export function usageLogPath(configDir?: string): string {
   return join(configDir ?? getConfigDir(), "usage.jsonl");
 }
@@ -590,6 +620,11 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
   const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
   const transportPhase = isKnownTransportPhase(entry.transportPhase) ? entry.transportPhase : undefined;
   const terminalSource = isKnownTerminalSource(entry.terminalSource) ? entry.terminalSource : undefined;
+  const affinity = isKnownAffinityMove(entry.affinity) ? entry.affinity : undefined;
+  // A reason without a move describes nothing, so it is only kept alongside one.
+  const affinityReason = affinity !== undefined && isKnownAffinityReason(entry.affinityReason)
+    ? entry.affinityReason
+    : undefined;
   const routeDecision = entry.routeDecision
     ? normalizeRouteDecisionTrace(entry.routeDecision)
     : undefined;
@@ -660,6 +695,8 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
     ...(Array.isArray(entry.attempts) ? { attempts } : {}),
     ...(transportPhase ? { transportPhase } : {}),
     ...(terminalSource ? { terminalSource } : {}),
+    ...(affinity ? { affinity } : {}),
+    ...(affinityReason ? { affinityReason } : {}),
     ...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
     ...(entry.terminalStatus ? { terminalStatus: entry.terminalStatus } : {}),
     ...(entry.closeReason ? { closeReason: entry.closeReason } : {}),

package/src/vision/eligibility.ts

@@ -26,6 +26,7 @@ import { getModelMetadataCaseInsensitive, resolveMetadataProvider } from "../gen
 import { nativeInputModalities } from "../codex/catalog/metadata";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
 import { enrichProviderFromRegistry } from "../providers/derive";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-destination";
 
 /**
  * The wire protocols `planVisionSidecar` can dispatch to (#2188 roadmap 170
@@ -113,7 +114,28 @@ function enrichedProviderForVision(
   if (cached) return cached;
   const configured = config.providers?.[providerName];
   if (!configured) return undefined;
-  const enriched = structuredClone(configured);
+  // Runtime providers may carry non-cloneable hooks (for example a provider-scoped fetch).
+  // Enrichment mutates top-level fields but does not mutate nested provider values in place, so
+  // a shallow copy plus private copies of the vision-capability containers is sufficient and
+  // avoids both config mutation and structuredClone(DataCloneError) on runtime functions.
+  const enriched: OcxProviderConfig = {
+    ...configured,
+    ...(configured.noVisionModels ? { noVisionModels: [...configured.noVisionModels] } : {}),
+    ...(configured.modelInputModalities ? {
+      modelInputModalities: Object.fromEntries(
+        Object.entries(configured.modelInputModalities).map(([id, modalities]) => [id, [...modalities]]),
+      ),
+    } : {}),
+    ...(configured.modelCapabilities ? {
+      modelCapabilities: Object.fromEntries(Object.entries(configured.modelCapabilities).map(([id, capability]) => [
+        id,
+        {
+          ...capability,
+          ...(capability.inputModalities ? { inputModalities: [...capability.inputModalities] } : {}),
+        },
+      ])),
+    } : {}),
+  };
   enrichProviderFromRegistry(providerName, enriched);
   cache.set(providerName, enriched);
   return enriched;
@@ -156,9 +178,10 @@ function modelAcceptsImageInputWithCache(
 ): 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({
-      noVisionModels: nativeProvider.noVisionModels, modelInputModalities: nativeProvider.modelInputModalities,
-    }, candidate.id)) return false;
+    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");
     return advertisesImageInput(nativeInputModalities(candidate.id)) ?? true;
   }
   if (isVisionSidecarConsumerWithCache(config, candidate.provider, candidate.id, cache)) return false;
@@ -166,6 +189,16 @@ function modelAcceptsImageInputWithCache(
   const declared = Object.hasOwn(provider?.modelCapabilities ?? {}, candidate.id)
     ? provider?.modelCapabilities?.[candidate.id]?.inputModalities : undefined;
   if (declared !== undefined) return declared.includes("image");
+  const configuredModalities = provider ? modelRecordValue(provider.modelInputModalities, candidate.id) : undefined;
+  const fromConfiguredModalities = advertisesImageInput(configuredModalities);
+  if (fromConfiguredModalities !== undefined) return fromConfiguredModalities;
+  const canonicalCodex = candidate.provider === "openai"
+    && provider !== undefined
+    && isCanonicalOpenAiForwardProvider(provider);
+  if (canonicalCodex) {
+    const fromCodexBackend = metadataImageInput("openai-codex", candidate.id);
+    if (fromCodexBackend !== undefined) return fromCodexBackend;
+  }
   const fromRow = advertisesImageInput(candidate.inputModalities);
   if (fromRow !== undefined) return fromRow;
   return metadataImageInput(candidate.provider, candidate.id);

package/src/vision/index.ts

@@ -35,6 +35,7 @@ export {
   resolveEffectiveVisionModel,
   shouldResolveOpenAiVisionSidecar,
   planVisionSidecar,
+  requiresVisionPreprocessing,
 } from "./plan";
 export type { AnthropicVisionProvider, VisionPlan } from "./plan";
 export { stripImagesInPlace } from "./image-rewrite";

package/src/vision/plan.ts

@@ -1,5 +1,5 @@
 import type { OcxConfig, OcxContentPart, OcxParsedRequest, OcxProviderConfig } from "../types";
-import type { VisionReasoningEffort } from "../reasoning-effort";
+import { modelRecordValue, type VisionReasoningEffort } from "../reasoning-effort";
 import type { VisionSettings } from "./describe";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import type { CodexAuthPolicyConfig } from "../codex/auth-context";
@@ -92,6 +92,34 @@ function messagesHaveImage(parsed: OcxParsedRequest): boolean {
     carriesImages(m.role) && Array.isArray(m.content) && (m.content as OcxContentPart[]).some(p => p.type === "image"));
 }
 
+/**
+ * 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.
+ */
+export function requiresVisionPreprocessing(
+  config: Pick<OcxConfig, "providers">,
+  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;
+  if (runtimeDeclared !== undefined) return !runtimeDeclared.includes("image");
+  const runtimeModalities = modelRecordValue(provider.modelInputModalities, modelId);
+  if (Array.isArray(runtimeModalities) && runtimeModalities.length > 0) {
+    return !runtimeModalities.includes("image");
+  }
+  if (!providerName) return false;
+  return modelAcceptsImageInput(config, { provider: providerName, id: modelId }) === false;
+}
+
 /** Shared by auth admission and planning so a routed describer never borrows OpenAI auth. */
 function usableRoutedVisionModel(config: OcxConfig): string | undefined {
   const cfg = config.visionSidecar;
@@ -109,10 +137,11 @@ function usableRoutedVisionModel(config: OcxConfig): string | undefined {
 export function shouldResolveOpenAiVisionSidecar(
   config: OcxConfig,
   provider: OcxProviderConfig,
- modelId: string,
- parsed: OcxParsedRequest,
+  modelId: string,
+  parsed: OcxParsedRequest,
+  providerName?: string,
 ): boolean {
-  if (!isModelTextOnly(provider, modelId) || !messagesHaveImage(parsed)) return false;
+  if (!requiresVisionPreprocessing(config, provider, modelId, providerName) || !messagesHaveImage(parsed)) return false;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return false;
   if (usableRoutedVisionModel(config)) return false;
@@ -132,10 +161,12 @@ export interface VisionPlan {
 }
 
 /**
- * Decide whether the vision sidecar should pre-describe images for this request, returning the plan
- * if so. Active when: the routed model is in `provider.noVisionModels`, the request actually carries
- * an image, the sidecar isn't disabled, and the selected backend has usable auth. Returns undefined
- * otherwise (the caller strips images before sending to a text-only model).
+ * Decide whether the vision sidecar should pre-describe images for this request. Raw image
+ * delivery is capability-driven: targets proven text-only are preprocessed, targets proven
+ * image-capable bypass this planner, and genuinely unknown custom targets retain legacy behavior.
+ * The request must
+ * carry an image, the sidecar must be enabled, and the selected backend must be dispatchable.
+ * Returns undefined otherwise; the caller strips images before any unverified upstream send.
  */
 export function planVisionSidecar(
   config: OcxConfig,
@@ -143,9 +174,13 @@ export function planVisionSidecar(
   modelId: string,
   parsed: OcxParsedRequest,
   openAiSidecar?: ResolvedOpenAiForwardSidecar,
-  options: { admission?: Pick<DataPlaneAdmission, "source">; codexAuthPolicy?: CodexAuthPolicyConfig } = {},
+  options: {
+    admission?: Pick<DataPlaneAdmission, "source">;
+    codexAuthPolicy?: CodexAuthPolicyConfig;
+    providerName?: string;
+  } = {},
 ): VisionPlan | undefined {
-  if (!isModelTextOnly(provider, modelId)) return undefined;
+  if (!requiresVisionPreprocessing(config, provider, modelId, options.providerName)) return undefined;
   if (!messagesHaveImage(parsed)) return undefined;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return undefined;

package/src/web-search/alpha-search.ts

@@ -0,0 +1,324 @@
+/**
+ * Serve Codex's built-in `/v1/alpha/search` when no ChatGPT forward provider exists.
+ *
+ * The ChatGPT relay in src/server/search.ts is byte-identical on purpose: the client talks an
+ * unpublished alpha envelope, and the only honest answer while a forward provider is configured
+ * is to copy bytes. That leaves API-key-only and routed-provider deployments with a 400 even
+ * when they already paid for a web-search sidecar. This module is the empty-candidates branch
+ * of that handler — it never runs when a forward provider is present, and it never borrows a
+ * different paid backend than the one the operator named.
+ *
+ * Do not import `./index.ts` from here. The barrel is still evaluating when search.ts loads,
+ * and pulling it in recreates the cycle sidecar-providers.ts exists to avoid.
+ */
+import { formatErrorResponse } from "../bridge";
+import { redactSecretString } from "../lib/redact";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import type { OcxConfig, OcxProviderConfig, OcxWebSearchSidecarConfig } from "../types";
+import { runAnthropicWebSearch } from "./anthropic-executor";
+import { runExaWebSearch } from "./exa-executor";
+import type { SidecarOutcome, SidecarSettings } from "./executor";
+import { runGeminiWebSearch } from "./gemini-executor";
+import {
+  findAnthropicSidecarProvider,
+  findGeminiSidecarProvider,
+  findXaiSidecarProvider,
+  resolveSidecarBackend,
+  xaiSearchOptionsFromConfig,
+} from "./sidecar-providers";
+import { safeWebSearchSources } from "./sources";
+import { runXaiWebSearch } from "./xai-executor";
+
+/**
+ * Same total-search budget the ChatGPT relay uses in src/server/search.ts. The sidecar loop's
+ * 60s default is a different contract (a helper turn beside a routed model); alpha/search is
+ * the whole request, so it keeps the relay's 200s ceiling unless config.search.timeoutMs says
+ * otherwise.
+ */
+const SEARCH_UPSTREAM_TIMEOUT_MS = 200_000;
+/** Queries honored from one alpha/search body; the rest are ignored rather than billed. */
+const MAX_QUERIES_PER_CALL = 3;
+const MAX_QUERY_CHARS = 1_000;
+const DEFAULT_REASONING = "low";
+
+/**
+ * Search model each sidecar backend runs when the operator did not name one for THIS backend.
+ * Copied from the passthrough bridge's table on purpose: sending a ChatGPT slug to Anthropic
+ * is the failure that table exists to prevent, and alpha/search would reproduce it if it
+ * trusted `webSearchSidecar.model` unconditionally.
+ */
+const DEFAULT_BACKEND_MODELS = {
+  anthropic: "claude-sonnet-5",
+  xai: "grok-4.6",
+  gemini: "gemini-3.8-flash",
+  // Exa ignores model; the placeholder only satisfies SidecarSettings.
+  exa: "gpt-5.6-luna",
+} as const;
+
+export type AlphaSearchSidecarBackend = keyof typeof DEFAULT_BACKEND_MODELS;
+
+type ResolvedAlphaSearchSidecar =
+  | { backend: "anthropic"; providerName: string; provider: OcxProviderConfig }
+  | { backend: "xai"; providerName: string; provider: OcxProviderConfig }
+  | { backend: "gemini"; providerName: string; provider: OcxProviderConfig }
+  | { backend: "exa"; apiKey: string };
+
+/**
+ * Why this path cannot serve the request, kept distinct from "nobody asked for it".
+ *
+ * The two refusals read identically to the operator but mean opposite things: `unconfigured` is
+ * a deployment that never named a backend, while `missing-credential` is one that named a
+ * backend the proxy cannot authenticate. Answering both with the ChatGPT-auth sentence is the
+ * behaviour the feature request called out — it tells an operator who already chose Exa to go
+ * set up ChatGPT OAuth, which is the one thing they were trying to avoid.
+ */
+export type AlphaSearchSidecarResolution =
+  | { status: "ready"; sidecar: ResolvedAlphaSearchSidecar }
+  | { status: "unconfigured" }
+  | { status: "missing-credential"; backend: AlphaSearchSidecarBackend };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Only the operator's explicit sidecar backend can serve this path, and only with THAT
+ * backend's own credential. `openai` is the ChatGPT forward path, which is absent by the
+ * time we are here; auto-selecting a different paid backend from leftover keys is how an
+ * anthropic-named config would silently spend Exa.
+ */
+export function resolveAlphaSearchSidecar(config: OcxConfig): AlphaSearchSidecarResolution {
+  const sidecar = config.webSearchSidecar;
+  // The master switch is the operator saying this sidecar may not run. planWebSearch honors it the
+  // same way, and ignoring it here would make `enabled: false` mean "off for the routed loop, on
+  // for alpha/search" — the one reading under which a disabled backend still spends money.
+  if (sidecar?.enabled === false) return { status: "unconfigured" };
+  const backend = resolveSidecarBackend(sidecar?.backend);
+  if (backend === "openai") return { status: "unconfigured" };
+  switch (backend) {
+    case "anthropic": {
+      const found = findAnthropicSidecarProvider(config);
+      return found
+        ? { status: "ready", sidecar: { backend, providerName: found.providerName, provider: found.provider } }
+        : { status: "missing-credential", backend };
+    }
+    case "xai": {
+      const found = findXaiSidecarProvider(config);
+      return found
+        ? { status: "ready", sidecar: { backend, providerName: found.providerName, provider: found.provider } }
+        : { status: "missing-credential", backend };
+    }
+    case "gemini": {
+      const found = findGeminiSidecarProvider(config);
+      return found
+        ? { status: "ready", sidecar: { backend, providerName: found.providerName, provider: found.provider } }
+        : { status: "missing-credential", backend };
+    }
+    case "exa": {
+      const apiKey = sidecar?.exaApiKey;
+      return typeof apiKey === "string" && apiKey.length > 0
+        ? { status: "ready", sidecar: { backend, apiKey } }
+        : { status: "missing-credential", backend };
+    }
+  }
+}
+
+function pushQuery(queries: string[], value: unknown): void {
+  if (typeof value !== "string") return;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || queries.includes(trimmed)) return;
+  if (queries.length < MAX_QUERIES_PER_CALL) queries.push(trimmed.slice(0, MAX_QUERY_CHARS));
+}
+
+/**
+ * Codex's live-search client sends a Responses-shaped envelope whose primary operation is
+ * `commands.search_query: [{ q }]`. Top-level `query` / `q` / `search_query` strings are the
+ * fallback for tests and any thinner client; they are consulted only when the envelope form
+ * produced nothing usable, so a present-but-empty `search_query` array cannot hide a
+ * top-level query the operator actually sent.
+ */
+export function extractAlphaSearchQueries(body: unknown): string[] {
+  const queries: string[] = [];
+  if (!isRecord(body)) return queries;
+  const searchQuery = isRecord(body.commands) ? body.commands.search_query : undefined;
+  if (Array.isArray(searchQuery)) {
+    for (const entry of searchQuery) {
+      if (isRecord(entry)) pushQuery(queries, entry.q);
+    }
+  }
+  if (queries.length === 0) {
+    pushQuery(queries, body.query);
+    if (queries.length === 0) pushQuery(queries, body.q);
+    if (queries.length === 0) pushQuery(queries, body.search_query);
+  }
+  return queries;
+}
+
+function modelForAlphaSearchBackend(
+  backend: AlphaSearchSidecarBackend,
+  sidecar: Pick<OcxWebSearchSidecarConfig, "backend" | "model"> | undefined,
+): string {
+  const backendDefault = DEFAULT_BACKEND_MODELS[backend];
+  if (resolveSidecarBackend(sidecar?.backend) !== backend) return backendDefault;
+  return sidecar?.model ?? backendDefault;
+}
+
+function sidecarSettingsForAlphaSearch(
+  backend: AlphaSearchSidecarBackend,
+  config: OcxConfig,
+): SidecarSettings {
+  const sidecar = config.webSearchSidecar;
+  return {
+    model: modelForAlphaSearchBackend(backend, sidecar),
+    reasoning: sidecar?.reasoning ?? DEFAULT_REASONING,
+    timeoutMs: config.search?.timeoutMs ?? SEARCH_UPSTREAM_TIMEOUT_MS,
+  };
+}
+
+async function runAlphaSearchQuery(
+  query: string,
+  resolved: ResolvedAlphaSearchSidecar,
+  settings: SidecarSettings,
+  config: OcxConfig,
+  signal?: AbortSignal,
+): Promise<SidecarOutcome> {
+  switch (resolved.backend) {
+    case "anthropic":
+      return runAnthropicWebSearch(query, resolved.providerName, resolved.provider, settings, signal);
+    case "xai":
+      return runXaiWebSearch(
+        query,
+        resolved.providerName,
+        resolved.provider,
+        settings,
+        xaiSearchOptionsFromConfig(config.webSearchSidecar ?? {}),
+        signal,
+      );
+    case "gemini":
+      return runGeminiWebSearch(query, resolved.providerName, resolved.provider, settings, signal);
+    case "exa":
+      return runExaWebSearch(query, resolved.apiKey, settings, signal);
+  }
+}
+
+function formatAlphaSearchBody(text: string, sources: SidecarOutcome["sources"]): {
+  encrypted_output: null;
+  output: string;
+  results: Array<{ title: string; url: string }>;
+} {
+  // Title falls back to the URL so the client always sees both fields; unsafe URLs are
+  // dropped entirely rather than echoed into `results`.
+  return {
+    encrypted_output: null,
+    output: text,
+    results: safeWebSearchSources(sources).map(source => ({
+      url: source.url,
+      title: source.title ?? source.url,
+    })),
+  };
+}
+
+const NO_FORWARD_PROVIDER_MESSAGE =
+  "Built-in web search needs a ChatGPT forward provider, but none is configured in opencodex. "
+  + "Routed and OpenAI API-key providers cannot serve /v1/alpha/search. "
+  + "Configure webSearchSidecar.backend (anthropic, xai, gemini, or exa) with that backend's credential instead.";
+
+/**
+ * What a named backend is missing, said in the operator's own terms.
+ *
+ * An operator who already chose a backend does not need to be told to configure ChatGPT auth —
+ * that answer is what the request asked this path to stop giving. They need to know which
+ * credential the backend they named could not find.
+ */
+function missingCredentialMessage(backend: AlphaSearchSidecarBackend): string {
+  const detail: Record<AlphaSearchSidecarBackend, string> = {
+    anthropic: "no usable stored Anthropic OAuth account was found",
+    xai: "no usable stored Grok OAuth account was found",
+    gemini: "no usable stored Antigravity OAuth account with a discovered project was found",
+    exa: "webSearchSidecar.exaApiKey is not set",
+  };
+  return "Built-in web search is configured to use the " + backend + " backend, but "
+    + detail[backend] + ". Restore that backend's credential, or choose another "
+    + "webSearchSidecar.backend. This request was not sent to any other backend.";
+}
+
+/**
+ * Run the named sidecar backend against an alpha/search body. Callers must already know there
+ * is no ChatGPT forward candidate — this function does not re-check that, so a mis-call would
+ * spend the sidecar even when the relay could have copied bytes.
+ */
+export async function handleAlphaSearchSidecarFallback(
+  body: unknown,
+  config: OcxConfig,
+  signal?: AbortSignal,
+  logCtx?: { provider: string },
+): Promise<Response> {
+  const resolution = resolveAlphaSearchSidecar(config);
+  if (resolution.status === "missing-credential") {
+    // Never the ChatGPT-auth sentence here: the operator already named a backend, so the honest
+    // answer names what that backend is missing.
+    if (logCtx) logCtx.provider = resolution.backend;
+    return formatErrorResponse(400, "invalid_request_error", missingCredentialMessage(resolution.backend));
+  }
+  if (resolution.status !== "ready") {
+    return formatErrorResponse(400, "invalid_request_error", NO_FORWARD_PROVIDER_MESSAGE);
+  }
+  const resolved = resolution.sidecar;
+  if (logCtx) logCtx.provider = resolved.backend;
+
+  const queries = extractAlphaSearchQueries(body);
+  if (queries.length === 0) {
+    return formatErrorResponse(
+      400,
+      "invalid_request_error",
+      "Built-in web search request is missing a usable query (commands.search_query, query, q, or search_query).",
+    );
+  }
+
+  const settings = sidecarSettingsForAlphaSearch(resolved.backend, config);
+  const sidecarExit = sidecarEnter("search");
+  try {
+    const texts: string[] = [];
+    const sources: SidecarOutcome["sources"] = [];
+    const errors: string[] = [];
+    for (const query of queries) {
+      if (signal?.aborted) break;
+      const outcome = await runAlphaSearchQuery(query, resolved, settings, config, signal);
+      if (outcome.error) {
+        errors.push(outcome.error);
+        continue;
+      }
+      texts.push(queries.length > 1 ? `Results for "${query}":\n${outcome.text}` : outcome.text);
+      for (const source of outcome.sources) {
+        if (!sources.some(existing => existing.url === source.url)) sources.push(source);
+      }
+    }
+    if (signal?.aborted) {
+      return formatErrorResponse(499, "client_closed_request", "search request canceled by client");
+    }
+    if (texts.length === 0) {
+      const detail = redactSecretString(errors[0] ?? "web search produced no results");
+      return formatErrorResponse(
+        502,
+        "upstream_error",
+        resolved.backend + " web search failed: " + detail,
+      );
+    }
+    return new Response(JSON.stringify(formatAlphaSearchBody(texts.join("\n\n"), sources)), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  } catch (err) {
+    if (signal?.aborted) {
+      return formatErrorResponse(499, "client_closed_request", "search request canceled by client");
+    }
+    const detail = redactSecretString(err instanceof Error ? err.message : String(err));
+    return formatErrorResponse(
+      502,
+      "upstream_error",
+      resolved.backend + " web search failed: " + detail,
+    );
+  } finally {
+    sidecarExit();
+  }
+}

package/src/web-search/index.ts

@@ -1,6 +1,6 @@
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
 import { modelInList, toolChoiceToolPredicate } from "../types";
-import { isModelTextOnly } from "../vision";
+import { requiresVisionPreprocessing } from "../vision";
 import type { SidecarSettings } from "./executor";
 import type { CodexAuthPolicyConfig } from "../codex/auth-context";
 import { isCodexReserveRequestEligible } from "../codex/loopback-target";
@@ -15,8 +15,10 @@ import {
   findAnthropicSidecarProvider,
   findGeminiSidecarProvider,
   findXaiSidecarProvider,
+  resolveSidecarBackend,
   xaiSearchOptionsFromConfig,
   type AnthropicSidecarProvider,
+  type WebSearchBackendId,
 } from "./sidecar-providers";
 
 export { runWithWebSearch } from "./loop";
@@ -29,8 +31,10 @@ export {
   findAnthropicSidecarProvider,
   findGeminiSidecarProvider,
   findXaiSidecarProvider,
+  resolveSidecarBackend,
   xaiSearchOptionsFromConfig,
   type AnthropicSidecarProvider,
+  type WebSearchBackendId,
 };
 
 const DEFAULT_SIDECAR_MODEL = "gpt-5.6-luna";
@@ -98,24 +102,6 @@ export function webSearchStallTimeoutSec(
   return Math.min(Number.MAX_VALUE, Math.ceil(largestUnitSec) + STALL_MARGIN_SEC);
 }
 
-/** Every backend id the config union admits. New ids are explicit-only and inert until their executor ships. */
-export type WebSearchBackendId = "openai" | "anthropic" | "xai" | "gemini" | "exa";
-
-/**
- * Precedence: explicit config wins; unset defaults to "openai" (ChatGPT forward path). The
- * anthropic backend (web_search_20250305) is only used when explicitly configured — auto-selecting
- * it from credential availability caused the sidecar to send incompatible models (e.g. gpt-5.6-luna)
- * to the Anthropic API.
- * The 2188 follow-up ids (xai/gemini/exa) resolve to themselves the same explicit-only way; their
- * planWebSearch arms stay fail-closed until each executor layer lands.
- */
-export function resolveSidecarBackend(
-  explicit: WebSearchBackendId | undefined,
-): WebSearchBackendId {
-  if (explicit === "anthropic" || explicit === "xai" || explicit === "gemini" || explicit === "exa") return explicit;
-  return "openai";
-}
-
 export interface SidecarPlan {
   /** Which executor runs the search. Anthropic does not require a forward provider. */
   backend: WebSearchBackendId;
@@ -166,7 +152,11 @@ export function planWebSearch(
   provider: OcxProviderConfig,
   modelId: string,
   openAiSidecar?: ResolvedOpenAiForwardSidecar,
-  options: { admission?: Pick<DataPlaneAdmission, "source">; codexAuthPolicy?: CodexAuthPolicyConfig } = {},
+  options: {
+    admission?: Pick<DataPlaneAdmission, "source">;
+    codexAuthPolicy?: CodexAuthPolicyConfig;
+    providerName?: string;
+  } = {},
 ): SidecarPlan | undefined {
   if (!parsed._webSearch || isPassthrough) return undefined;
   if (!toolChoiceToolPredicate(parsed.options.toolChoice)(buildWebSearchTool())) return undefined;
@@ -190,8 +180,9 @@ export function planWebSearch(
     routedModelStallTimeoutMs,
     timeoutMs,
   );
-  // The routed model being text-only means the search model must verbalize image results (either backend).
-  const describeImages = isModelTextOnly(provider, modelId);
+  // A target proven unable to accept image input receives verbalized image results instead of
+  // search-result images. A genuinely unknown custom target keeps the established pass-through.
+  const describeImages = requiresVisionPreprocessing(config, provider, modelId, options.providerName);
   const reasoning = cfg.reasoning ?? DEFAULT_SIDECAR_REASONING;
   const streamRoutedModelOutput = cfg.streamRoutedModelOutput === true;