@iislee/opencodex 2.11.0 → 2.31.0

package/src/vision/eligibility.ts

@@ -0,0 +1,250 @@
+/**
+ * Which models may serve AS the vision sidecar (the describer), as opposed to the
+ * models the sidecar describes FOR.
+ *
+ * Three rules make this non-obvious, and all are load-bearing:
+ *
+ * 1. `provider.noVisionModels` marks models the proxy describes images for, and
+ *    `applyProviderConfigHints` deliberately ADDS "image" to their advertised
+ *    input modalities so the Codex app does not block the attachment client-side.
+ *    A blind model therefore advertises image input. Membership in that list is a
+ *    hard disqualifier here, checked BEFORE the modality list it rewrote.
+ * 2. The catalog enriches configured providers from the registry before it
+ *    applies that rule. Eligibility must use the same effective provider policy,
+ *    including a `noVisionModels` list learned after the config was persisted.
+ * 3. Catalog rows frequently omit `inputModalities` entirely (the live
+ *    `/api/models` response carries none for either openai or anthropic rows).
+ *    Unknown is not zero: when no source can speak, the model stays eligible
+ *    rather than silently vanishing from the picker.
+ *    Native OpenAI metadata is likewise authoritative only for a native row or
+ *    the canonical OpenAI provider; a routed row with the same id owns its own
+ *    explicit modalities.
+ */
+import { modelInList, type OcxConfig, type OcxProviderConfig } from "../types";
+import { getModelMetadataCaseInsensitive, resolveMetadataProvider } from "../generated/model-metadata";
+import { nativeInputModalities } from "../codex/catalog/metadata";
+import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
+import { enrichProviderFromRegistry } from "../providers/derive";
+
+/**
+ * The wire protocols `planVisionSidecar` can dispatch to (#2188 roadmap 170
+ * REVISED). "routed" describes through the proxy's OWN router via loopback —
+ * one executor for every non-forward, non-OAuth-Anthropic provider row.
+ */
+export type VisionSidecarBackend = "openai" | "anthropic" | "routed";
+
+/** The two sides every deployment has; also the empty-auth fallback set. */
+export type UniversalVisionBackend = "openai" | "anthropic";
+
+/**
+ * Default entry per backend: cheap, image-capable, and present in every deployment. Offered
+ * whenever its side is enabled, and withheld only when that provider explicitly lists it as a
+ * model the sidecar describes FOR — never merely because a metadata table stayed silent.
+ *
+ * Keyed by the UNIVERSAL subset on purpose (roadmap 170, audit blocker A):
+ * xai/gemini are auth-gated sides whose catalogs are present whenever the side
+ * is, so they carry no baseline, and a narrow-key total record documents that
+ * without sprinkling non-null assertions at the consumers.
+ */
+export const BASELINE_VISION_MODELS: Record<UniversalVisionBackend, string> = {
+  openai: "gpt-5.6-luna",
+  anthropic: "claude-haiku-4-5",
+};
+
+export interface VisionCandidateModel {
+  provider: string;
+  id: string;
+  inputModalities?: string[];
+  native?: boolean;
+}
+
+export interface VisionModelOption {
+  value: string;
+  label: string;
+  backend: VisionSidecarBackend;
+  /** True when the row is a guaranteed baseline rather than a catalog discovery. */
+  baseline?: boolean;
+}
+
+type EnrichedProviderCache = Map<string, OcxProviderConfig>;
+
+function advertisesImageInput(modalities: readonly string[] | undefined): boolean | undefined {
+  if (!modalities || modalities.length === 0) return undefined;
+  return modalities.includes("image");
+}
+
+/** Vendor-table modalities for a routed row, or undefined when the table has no opinion. */
+function metadataImageInput(provider: string, modelId: string): boolean | undefined {
+  const resolved = resolveMetadataProvider(provider) ?? provider;
+  const meta = getModelMetadataCaseInsensitive(resolved, modelId);
+  return advertisesImageInput(meta?.input);
+}
+
+/**
+ * Mirrors the catalog's registry enrichment without mutating saved configuration. The picker
+ * checks many rows from one provider, so its caller shares this small call-local cache.
+ */
+function enrichedProviderForVision(
+  config: Pick<OcxConfig, "providers">,
+  providerName: string,
+  cache: EnrichedProviderCache,
+): OcxProviderConfig | undefined {
+  const cached = cache.get(providerName);
+  if (cached) return cached;
+  const configured = config.providers?.[providerName];
+  if (!configured) return undefined;
+  const enriched = structuredClone(configured);
+  enrichProviderFromRegistry(providerName, enriched);
+  cache.set(providerName, enriched);
+  return enriched;
+}
+
+function isVisionSidecarConsumerWithCache(
+  config: Pick<OcxConfig, "providers">,
+  providerName: string,
+  modelId: string,
+  cache: EnrichedProviderCache,
+): boolean {
+  return modelInList(enrichedProviderForVision(config, providerName, cache)?.noVisionModels, 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 {
+  return isVisionSidecarConsumerWithCache(config, providerName, modelId, new Map());
+}
+
+/**
+ * Can this model accept an image on the wire? Sources are consulted in descending
+ * trustworthiness; the first that speaks wins. `undefined` means nothing knows,
+ * which callers treat as eligible.
+ */
+export function modelAcceptsImageInput(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+): boolean | undefined {
+  return modelAcceptsImageInputWithCache(config, candidate, new Map());
+}
+
+function modelAcceptsImageInputWithCache(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+  cache: EnrichedProviderCache,
+): boolean | undefined {
+  if (isVisionSidecarConsumerWithCache(config, candidate.provider, candidate.id, cache)) return false;
+  if (candidate.native === true || (candidate.provider === "openai" && SUPPORTED_NATIVE_OPENAI_SLUGS.has(candidate.id))) {
+    return advertisesImageInput(nativeInputModalities(candidate.id)) ?? true;
+  }
+  const fromRow = advertisesImageInput(candidate.inputModalities);
+  if (fromRow !== undefined) return fromRow;
+  return metadataImageInput(candidate.provider, candidate.id);
+}
+
+/** Eligible = not a sidecar consumer, and not positively known to be text-only. */
+export function isVisionEligibleModel(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+): boolean {
+  return isVisionEligibleModelWithCache(config, candidate, new Map());
+}
+
+function isVisionEligibleModelWithCache(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+  cache: EnrichedProviderCache,
+): boolean {
+  return modelAcceptsImageInputWithCache(config, candidate, cache) !== false;
+}
+
+/** Which executor can describe through this row. */
+export function visionBackendForCandidate(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+  anthropicProviderName?: string,
+): VisionSidecarBackend | undefined {
+  if (candidate.native || candidate.provider === "openai") return "openai";
+  // The runtime dispatches through exactly ONE Anthropic provider — the enabled OAuth row
+  // with a healthy active account that `findAnthropicVisionProvider` picks. Speaking the
+  // Messages wire is not enough: a key-auth row of the same adapter is unreachable, and an
+  // option that cannot be dispatched is worse than a missing one, because selecting it fails
+  // at describe time rather than at pick time.
+  if (anthropicProviderName !== undefined && candidate.provider === anthropicProviderName) {
+    return "anthropic";
+  }
+  // EVERY other provider row describes through the proxy's own router
+  // (roadmap 170 revised): the loopback executor covers all provider wires,
+  // so no row is left without an executor.
+  return "routed";
+}
+
+function baselineCandidate(
+  backend: UniversalVisionBackend,
+  anthropicProviderName: string | undefined,
+): VisionCandidateModel {
+  return {
+    provider: backend === "openai" ? "openai" : anthropicProviderName ?? "anthropic",
+    id: BASELINE_VISION_MODELS[backend],
+    // Both baselines are known image-capable. This makes their only exclusion path the
+    // provider's explicit consumer list, never a silent or stale metadata table.
+    inputModalities: ["text", "image"],
+  };
+}
+
+/**
+ * The picker's option list: every eligible row reachable by an enabled
+ * executor, plus each enabled universal side's baseline unless that baseline
+ * is explicitly excluded, de-duplicated and stably ordered (side rank order,
+ * baselines first within a side). Anthropic rows must belong to the OAuth
+ * provider that would actually execute them, so `anthropicProviderName` is
+ * what makes that side's catalog rows eligible at all; xai/gemini rows map by
+ * provider identity and appear only when the caller enabled those backends.
+ *
+ * This is the SUGGESTION list (narrow): it emits only rows an executor can reach
+ * and some source has heard of. It is deliberately NOT the same set as the write
+ * gate. `modelAcceptsImageInput` answers "can we prove this model cannot see?"
+ * and is the only input to rejection. Absence from this list must never imply
+ * rejection — an unknown id stays eligible via the undefined → eligible fallback.
+ *
+ * De-duplication is by BARE model id, first eligible row wins. Two providers of
+ * the same adapter family can expose the same id; they resolve to the same
+ * backend, and only `value` reaches the client, so first-wins costs nothing.
+ */
+export function visionEligibleModelOptions(
+  config: Pick<OcxConfig, "providers">,
+  candidates: readonly VisionCandidateModel[],
+  enabledBackends: readonly VisionSidecarBackend[],
+  anthropicProviderName?: string,
+): VisionModelOption[] {
+  const enabled = new Set(enabledBackends);
+  const byValue = new Map<string, VisionModelOption>();
+  const enrichedProviders: EnrichedProviderCache = new Map();
+
+  for (const backend of Object.keys(BASELINE_VISION_MODELS) as UniversalVisionBackend[]) {
+    if (!enabled.has(backend)) continue;
+    const candidate = baselineCandidate(backend, anthropicProviderName);
+    if (!isVisionEligibleModelWithCache(config, candidate, enrichedProviders)) continue;
+    const id = candidate.id;
+    byValue.set(id, { value: id, label: id, backend, baseline: true });
+  }
+  for (const candidate of candidates) {
+    const backend = visionBackendForCandidate(config, candidate, anthropicProviderName);
+    if (!backend || !enabled.has(backend)) continue;
+    if (!isVisionEligibleModelWithCache(config, candidate, enrichedProviders)) continue;
+    // Routed rows carry NAMESPACED values ("provider/model") so the loopback
+    // dispatch is unambiguous under routeModel; the legacy sides keep bare ids
+    // (GUI current-value compatibility, and the forward/OAuth executors POST
+    // the string verbatim). De-dup stays keyed by the emitted value.
+    const value = backend === "routed" ? `${candidate.provider}/${candidate.id}` : candidate.id;
+    if (byValue.has(value)) continue;
+    byValue.set(value, { value, label: value, backend });
+  }
+
+  // Two slots per side (baseline first), ranked openai < anthropic < routed
+  // so widening the union appends rather than interleaves (roadmap 170).
+  const sideRank: Record<VisionSidecarBackend, number> = { openai: 0, anthropic: 2, routed: 4 };
+  const order = (option: VisionModelOption) =>
+    sideRank[option.backend] + (option.baseline ? 0 : 1);
+  return [...byValue.values()].sort((a, b) => order(a) - order(b) || a.value.localeCompare(b.value));
+}

package/src/vision/index.ts

@@ -1,22 +1,62 @@
 import { createHash } from "node:crypto";
 import type { OcxConfig, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent } from "../types";
 import { modelInList } from "../types";
+import { modelRecordValue } from "../reasoning-effort";
+import type { VisionReasoningEffort } from "../reasoning-effort";
 import { describeImage, type DescribeOutcome, type VisionSettings } from "./describe";
 import { describeImageAnthropic } from "./anthropic-describe";
+import { describeImageRouted } from "./routed-describe";
+import { modelAcceptsImageInput } from "./eligibility";
+import { normalizeVisionReasoningForModel } from "./reasoning";
 import type { CodexAuthContext } from "../codex/auth-context";
-import { getAccountSet } from "../oauth/store";
+import { resolveSidecarAuth } from "../sidecar/auth";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import type { SidecarOutcomeRecorder } from "../web-search/executor";
 import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 import type { TranslatorBudget } from "../lib/translator-budget";
+import {
+  DEFAULT_VISION_TIMEOUT_MS,
+  MAX_VISION_TIMEOUT_MS,
+  MIN_VISION_TIMEOUT_MS,
+} from "./timeout-bounds";
 
 export { describeImage } from "./describe";
+
+/**
+ * True when the model is explicitly known to be text-only — either listed in
+ * `noVisionModels` or declared with `modelInputModalities` that exclude "image".
+ * Returns false for unknown models (no evidence either way) so they fall through
+ * to native image passthrough, which is the safe default for an unclassified model.
+ */
+export function isModelTextOnly(
+  provider: OcxProviderConfig,
+  modelId: string,
+): boolean {
+  if (modelInList(provider.noVisionModels, modelId)) return true;
+  const modalities = modelRecordValue(provider.modelInputModalities, modelId);
+  if (Array.isArray(modalities) && modalities.length > 0 && !modalities.includes("image")) return true;
+  return false;
+}
 export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
+export {
+  BASELINE_VISION_MODELS,
+  isVisionEligibleModel,
+  isVisionSidecarConsumer,
+  modelAcceptsImageInput,
+  visionBackendForCandidate,
+  visionEligibleModelOptions,
+} from "./eligibility";
+export type { VisionCandidateModel, VisionModelOption, VisionSidecarBackend } from "./eligibility";
+export {
+  DEFAULT_VISION_TIMEOUT_MS,
+  MAX_VISION_TIMEOUT_MS,
+  MIN_VISION_TIMEOUT_MS,
+};
 
 const DEFAULT_VISION_MODEL = "gpt-5.4-mini";
 const DEFAULT_ANTHROPIC_VISION_MODEL = "claude-sonnet-5";
-const DEFAULT_TIMEOUT_MS = 45_000;
-const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
+const DEFAULT_REASONING: VisionReasoningEffort = "low";
+export const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
 const DESCRIPTION_CACHE_MAX_ENTRIES = 256;
 export const VISION_DESCRIPTION_CACHE_MAX_BYTES = 1024 * 1024;
 const descriptionEncoder = new TextEncoder();
@@ -142,6 +182,18 @@ export function resolveMaxDescriptionsPerTurn(value: unknown): number {
     : DEFAULT_MAX_DESCRIPTIONS_PER_TURN;
 }
 
+export function isValidVisionTimeoutMs(value: unknown): value is number {
+  return typeof value === "number"
+    && Number.isInteger(value)
+    && value >= MIN_VISION_TIMEOUT_MS
+    && value <= MAX_VISION_TIMEOUT_MS;
+}
+
+/** Runtime config is permissive: malformed or out-of-range values fall back to the default. */
+export function resolveVisionTimeoutMs(value: unknown): number {
+  return isValidVisionTimeoutMs(value) ? value : DEFAULT_VISION_TIMEOUT_MS;
+}
+
 /** Run `worker` over `items` with bounded concurrency, preserving input order in the result array. */
 async function runBounded<T, R>(items: T[], limit: number, worker: (item: T) => Promise<R>): Promise<R[]> {
   const results = new Array<R>(items.length);
@@ -165,25 +217,52 @@ export interface AnthropicVisionProvider {
   provider: OcxProviderConfig;
 }
 
-/** First enabled Anthropic OAuth provider whose active stored account is not marked for reauth. */
+/**
+ * First enabled Anthropic OAuth provider whose active stored account is not marked for reauth.
+ * Delegates to the shared sidecar auth module (#2188) — same predicate as web-search.
+ */
 export function findAnthropicVisionProvider(config: OcxConfig): AnthropicVisionProvider | undefined {
-  for (const [providerName, provider] of Object.entries(config.providers)) {
-    if (provider.disabled === true || provider.adapter !== "anthropic" || provider.authMode !== "oauth") continue;
-    const accountSet = getAccountSet(providerName);
-    const active = accountSet?.accounts.find(account => account.id === accountSet.activeAccountId);
-    if (active && active.needsReauth !== true) return { providerName, provider };
-  }
-  return undefined;
+  const auth = resolveSidecarAuth(config);
+  if (!auth.isAnthropicAuth || !auth.anthropicProviderName || !auth.anthropicProvider) return undefined;
+  return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider };
 }
 
 export function resolveVisionBackend(
-  explicit: "openai" | "anthropic" | undefined,
+  explicit: "openai" | "anthropic" | "routed" | undefined,
   anthropicSidecar: AnthropicVisionProvider | undefined,
 ): "openai" | "anthropic" {
   if (explicit === "openai" || explicit === "anthropic") return explicit;
+  // "routed" collapses to the legacy default order until its describe executor
+  // lands (roadmap 170 → 180 revised): a persisted routed backend without a
+  // dispatchable arm degrades exactly like unset rather than crashing. wp3
+  // replaces this collapse with the real routed arm in planVisionSidecar.
   return anthropicSidecar ? "anthropic" : "openai";
 }
 
+/** Native model used by the OpenAI vision helper, including its bounded default. */
+export function resolveOpenAiVisionModel(config: Pick<OcxConfig, "visionSidecar">): string {
+  const configured = config.visionSidecar?.model;
+  // Namespaced routed ids never reach the forward executor (see
+  // resolveEffectiveVisionModel).
+  return configured && !configured.includes("/") ? configured : DEFAULT_VISION_MODEL;
+}
+
+/** Effective describer model for the backend `planVisionSidecar` selected. */
+export function resolveEffectiveVisionModel(
+  config: Pick<OcxConfig, "visionSidecar">,
+  backend: "openai" | "anthropic",
+): string {
+  const configured = config.visionSidecar?.model;
+  // A namespaced "provider/model" id belongs to the routed backend only; the
+  // forward/OAuth executors POST the model string verbatim, so it falls back
+  // to the side's default here (PUT coherence rejects new writes of this
+  // shape, but a legacy or hand-edited config must not break the executor).
+  const usable = configured && !configured.includes("/") ? configured : undefined;
+  return backend === "anthropic"
+    ? usable || DEFAULT_ANTHROPIC_VISION_MODEL
+    : usable || DEFAULT_VISION_MODEL;
+}
+
 /** A user/developer/toolResult message can carry images (toolResult: e.g. Codex view_image output). */
 function carriesImages(role: string): boolean {
   return role === "user" || role === "developer" || role === "toolResult";
@@ -197,19 +276,23 @@ function messagesHaveImage(parsed: OcxParsedRequest): boolean {
 export function shouldResolveOpenAiVisionSidecar(
   config: OcxConfig,
   provider: OcxProviderConfig,
-  modelId: string,
-  parsed: OcxParsedRequest,
+ modelId: string,
+ parsed: OcxParsedRequest,
 ): boolean {
-  if (!modelInList(provider.noVisionModels, modelId) || !messagesHaveImage(parsed)) return false;
+  if (!isModelTextOnly(provider, modelId) || !messagesHaveImage(parsed)) return false;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return false;
   return resolveVisionBackend(cfg.backend, findAnthropicVisionProvider(config)) === "openai";
 }
 
 export interface VisionPlan {
-  backend: "openai" | "anthropic";
+  backend: "openai" | "anthropic" | "routed";
   forwardSidecar?: ResolvedOpenAiForwardSidecar;
   anthropicSidecar?: AnthropicVisionProvider;
+  /** Namespaced "provider/model" describer for the routed backend (roadmap 180). */
+  routedModel?: string;
+  /** Loopback dispatch inputs for the routed backend. */
+  routedConfig?: Pick<OcxConfig, "port" | "apiKeys">;
   settings: VisionSettings;
   maxDescriptionsPerTurn: number;
 }
@@ -227,12 +310,50 @@ export function planVisionSidecar(
   parsed: OcxParsedRequest,
   openAiSidecar?: ResolvedOpenAiForwardSidecar,
 ): VisionPlan | undefined {
-  if (!modelInList(provider.noVisionModels, modelId)) return undefined;
+  if (!isModelTextOnly(provider, modelId)) return undefined;
   if (!messagesHaveImage(parsed)) return undefined;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return undefined;
+
+  // Routed arm (roadmap 180 revised): explicit backend + NAMESPACED explicit
+  // model only — never inferred from credential availability. Plan-time
+  // fence: the target must not be provably blind, and must not itself be a
+  // model this planner would re-enter for (belt; the terminal marker on the
+  // loopback request is the braces).
+  if (cfg.backend === "routed") {
+    const routedModel = cfg.model;
+    const sep = routedModel ? routedModel.indexOf("/") : -1;
+    if (routedModel && sep > 0) {
+      const targetProvider = routedModel.slice(0, sep);
+      const targetId = routedModel.slice(sep + 1);
+      const targetProviderConfig = config.providers?.[targetProvider];
+      const targetVisible = modelAcceptsImageInput(config, { provider: targetProvider, id: targetId }) !== false
+        && !(targetProviderConfig && isModelTextOnly(targetProviderConfig, targetId));
+      if (targetVisible) {
+        return {
+          backend: "routed",
+          routedModel,
+          routedConfig: { port: config.port, ...(config.apiKeys ? { apiKeys: config.apiKeys } : {}) },
+          settings: {
+            model: routedModel,
+            reasoning: DEFAULT_REASONING,
+            timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
+          },
+          maxDescriptionsPerTurn: resolveMaxDescriptionsPerTurn(cfg.maxDescriptionsPerTurn),
+        };
+      }
+    }
+    // Misconfigured routed backend (bare id, unknown provider, or provably
+    // blind target): fall through to the legacy default order below rather
+    // than dispatching a describe that cannot work.
+  }
+
   const anthropicSidecar = findAnthropicVisionProvider(config);
   const backend = resolveVisionBackend(cfg.backend, anthropicSidecar);
+  // A namespaced routed model must never reach the forward/OAuth executors
+  // (they POST the string verbatim); the effective-model resolver falls back
+  // to each side's default in that case.
+  const model = resolveEffectiveVisionModel(config, backend);
   const maxDescriptionsPerTurn = resolveMaxDescriptionsPerTurn(cfg.maxDescriptionsPerTurn);
 
   if (backend === "anthropic") {
@@ -240,7 +361,11 @@ export function planVisionSidecar(
     return {
       backend,
       anthropicSidecar,
-      settings: { model: cfg.model ?? DEFAULT_ANTHROPIC_VISION_MODEL, timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+      settings: {
+        model,
+        reasoning: normalizeVisionReasoningForModel(model, cfg.reasoning) ?? DEFAULT_REASONING,
+        timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
+      },
       maxDescriptionsPerTurn,
     };
   }
@@ -249,7 +374,11 @@ export function planVisionSidecar(
   return {
     backend,
     forwardSidecar: openAiSidecar,
-    settings: { model: cfg.model ?? DEFAULT_VISION_MODEL, timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+    settings: {
+      model,
+      reasoning: normalizeVisionReasoningForModel(model, cfg.reasoning) ?? DEFAULT_REASONING,
+        timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
+    },
     maxDescriptionsPerTurn,
   };
 }
@@ -270,6 +399,72 @@ function renderDescription(out: { text: string; error?: string }): OcxTextConten
   };
 }
 
+const IMAGE_OMITTED_TEXT = "[image omitted: this model is text-only and the vision sidecar is unavailable (no ChatGPT login)]";
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Keep the native Responses passthrough body aligned with image replacements made in the parsed
+ * message graph. The passthrough adapter serializes `_rawBody`, while translated adapters serialize
+ * `context.messages`; updating only the latter would send the original pixels to a text-only
+ * Responses upstream even after the vision sidecar produced a caption.
+ *
+ * Rewrites only image-bearing user/developer messages and tool outputs. All other native Responses
+ * items (reasoning, calls, ids, compaction, and provider-specific metadata) remain byte-structurally
+ * untouched.
+ */
+function syncRawBodyImageDescriptions(parsed: OcxParsedRequest, descriptions: readonly string[]): void {
+  const rawBody = parsed._rawBody;
+  if (!isPlainRecord(rawBody) || !Array.isArray(rawBody.input)) return;
+
+  let nextDescription = 0;
+  const rewriteImages = (value: unknown, nonEmptyImageUrlsOnly: boolean): unknown => {
+    if (Array.isArray(value)) {
+      let changed = false;
+      const rewritten = value.map(entry => {
+        const next = rewriteImages(entry, nonEmptyImageUrlsOnly);
+        if (next !== entry) changed = true;
+        return next;
+      });
+      return changed ? rewritten : value;
+    }
+    if (!isPlainRecord(value)) return value;
+    if (value.type === "input_image" && typeof value.image_url === "string") {
+      if (nonEmptyImageUrlsOnly && value.image_url.length === 0) {
+        return { type: "input_text", text: IMAGE_OMITTED_TEXT };
+      }
+      const description = descriptions[nextDescription++];
+      return { type: "input_text", text: description ?? IMAGE_OMITTED_TEXT };
+    }
+    return value;
+  };
+
+  let changed = false;
+  const input = rawBody.input.map(item => {
+    if (!isPlainRecord(item)) return item;
+    const type = typeof item.type === "string" ? item.type : (typeof item.role === "string" ? "message" : "");
+    const role = typeof item.role === "string" ? item.role : "";
+    const isMessageContent = (
+      (type === "message" && (role === "user" || role === "developer"))
+      || type === "agent_message"
+    );
+    const field = isMessageContent
+      ? "content"
+      : (type === "function_call_output" || type === "custom_tool_call_output")
+        ? "output"
+        : undefined;
+    if (!field) return item;
+    const rewritten = rewriteImages(item[field], isMessageContent);
+    if (rewritten === item[field]) return item;
+    changed = true;
+    return { ...item, [field]: rewritten };
+  });
+
+  if (changed) rawBody.input = input;
+}
+
 function sha256(value: string | Uint8Array): string {
   return createHash("sha256").update(value).digest("hex");
 }
@@ -292,6 +487,7 @@ function descriptionIdentity(job: ImageJob, plan: VisionPlan): { key: string; pe
     key: JSON.stringify([
       plan.backend,
       plan.settings.model,
+      ...(plan.backend === "openai" ? [plan.settings.reasoning] : []),
       job.detail ?? "high",
       imageHash,
       sha256(normalizedContext(job.contextText)),
@@ -307,6 +503,18 @@ async function executeDescription(
   abortSignal?: AbortSignal,
   recordSidecarOutcome?: SidecarOutcomeRecorder,
 ): Promise<DescribeOutcome> {
+  if (plan.backend === "routed") {
+    if (!plan.routedModel || !plan.routedConfig) return { text: "", error: "routed vision sidecar is unavailable" };
+    return describeImageRouted(
+      job.imageUrl,
+      job.detail,
+      job.contextText,
+      plan.routedModel,
+      plan.routedConfig,
+      plan.settings,
+      abortSignal,
+    );
+  }
   if (plan.backend === "anthropic") {
     const sidecar = plan.anthropicSidecar;
     if (!sidecar) return { text: "", error: "anthropic vision sidecar is unavailable" };
@@ -347,7 +555,6 @@ export async function describeImagesInPlace(
   recordSidecarOutcome?: SidecarOutcomeRecorder,
   translatorBudget?: TranslatorBudget,
 ): Promise<void> {
-  // 1. Gather every image part across messages, each with its own message's text as context.
   const jobs: ImageJob[] = [];
   const targets: { msg: OcxMessage; parts: OcxContentPart[] }[] = [];
   for (const msg of parsed.context.messages) {
@@ -364,9 +571,11 @@ export async function describeImagesInPlace(
     }
     targets.push({ msg, parts });
   }
-  if (jobs.length === 0) return;
+  if (jobs.length === 0) {
+    syncRawBodyImageDescriptions(parsed, []);
+    return;
+  }
 
-  // 2. Admit misses in source order. Cache hits and same-turn waiters do not consume the cap.
   const inFlight = new Map<string, Promise<DescribeOutcome>>();
   const executions: Array<() => Promise<void>> = [];
   const outcomePromises: Array<Promise<DescribeOutcome>> = [];
@@ -418,8 +627,8 @@ export async function describeImagesInPlace(
   await runBounded(executions, VISION_CONCURRENCY, execute => execute());
   const outcomes = await Promise.all(outcomePromises);
 
-  // 3. Rebuild each message, replacing image parts with their descriptions in order.
   let oi = 0;
+  const descriptions: string[] = [];
   for (const { msg, parts } of targets) {
     const newParts: OcxContentPart[] = [];
     for (const p of parts) {
@@ -428,6 +637,7 @@ export async function describeImagesInPlace(
         continue;
       }
       const replacement = renderDescription(outcomes[oi++]);
+      descriptions.push(replacement.text);
       const reservation = translatorBudget?.reserveTransient(
         descriptionEncoder.encode(replacement.text).byteLength,
         { kind: "request_copies" },
@@ -437,6 +647,7 @@ export async function describeImagesInPlace(
     }
     msg.content = newParts;
   }
+  syncRawBodyImageDescriptions(parsed, descriptions);
 }
 
 /**
@@ -447,13 +658,15 @@ export async function describeImagesInPlace(
  */
 export function stripImagesInPlace(parsed: OcxParsedRequest, translatorBudget?: TranslatorBudget): boolean {
   let stripped = false;
+  const descriptions: string[] = [];
   for (const msg of parsed.context.messages) {
     if (!carriesImages(msg.role) || !Array.isArray(msg.content)) continue;
     const parts = msg.content as OcxContentPart[];
     if (!parts.some(p => p.type === "image")) continue;
     msg.content = parts.map(p => {
       if (p.type !== "image") return p;
-      const replacement = { type: "text", text: "[image omitted: this model is text-only and the vision sidecar is unavailable (no ChatGPT login)]" } as OcxContentPart;
+      const replacement = { type: "text", text: IMAGE_OMITTED_TEXT } as OcxContentPart;
+      descriptions.push((replacement as OcxTextContent).text);
       const reservation = translatorBudget?.reserveTransient(
         descriptionEncoder.encode((replacement as OcxTextContent).text).byteLength,
         { kind: "request_copies" },
@@ -463,5 +676,6 @@ export function stripImagesInPlace(parsed: OcxParsedRequest, translatorBudget?:
     });
     stripped = true;
   }
+  syncRawBodyImageDescriptions(parsed, descriptions);
   return stripped;
 }