@iislee/opencodex 2.11.0 → 2.35.0

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;
 }

package/src/vision/reasoning.ts

@@ -0,0 +1,55 @@
+import { NATIVE_OPENAI_MODELS, nativeReasoningEfforts } from "../codex/catalog/metadata";
+import {
+  VISION_REASONING_EFFORTS,
+  sanitizeVisionReasoning,
+  type VisionReasoningEffort,
+} from "../reasoning-effort";
+
+/** Keep the public config type aligned without replacing the heavily-changed shared types file. */
+declare module "../types" {
+  interface OcxVisionSidecarConfig {
+    /** OpenAI Responses reasoning effort used by the vision describer. Default: low. */
+    reasoning?: VisionReasoningEffort;
+  }
+}
+
+const NATIVE_VISION_MODELS = new Set(NATIVE_OPENAI_MODELS);
+
+/**
+ * Return the known vision reasoning ladder for a native OpenAI model.
+ * Unknown/custom models deliberately return undefined so callers stay permissive when reliable
+ * capability metadata is unavailable.
+ */
+export function nativeVisionReasoningEfforts(modelId: string): VisionReasoningEffort[] | undefined {
+  if (!NATIVE_VISION_MODELS.has(modelId)) return undefined;
+  const advertised = new Set(nativeReasoningEfforts(modelId));
+  const supported = VISION_REASONING_EFFORTS.filter(effort => advertised.has(effort));
+  return supported.length > 0 ? [...supported] : undefined;
+}
+
+/**
+ * Normalize one configured effort against a model's known ladder. Invalid enum values degrade to
+ * undefined; valid values on unknown/custom models are preserved. A known native model clamps to
+ * the highest supported rung at or below the requested value.
+ */
+export function normalizeVisionReasoningForModel(
+  modelId: string,
+  value: unknown,
+): VisionReasoningEffort | undefined {
+  const requested = sanitizeVisionReasoning(value);
+  if (!requested) return undefined;
+  const supported = nativeVisionReasoningEfforts(modelId);
+  if (!supported || supported.includes(requested)) return requested;
+
+  const requestedRank = VISION_REASONING_EFFORTS.indexOf(requested);
+  let best = supported[0];
+  let bestRank = VISION_REASONING_EFFORTS.indexOf(best);
+  for (const effort of supported) {
+    const rank = VISION_REASONING_EFFORTS.indexOf(effort);
+    if (rank <= requestedRank && rank >= bestRank) {
+      best = effort;
+      bestRank = rank;
+    }
+  }
+  return best;
+}

package/src/vision/routed-describe.ts

@@ -0,0 +1,175 @@
+/**
+ * Describe ONE image via a ROUTED model through the proxy's own
+ * /v1/chat/completions on loopback (#2188 roadmap 180 revised).
+ *
+ * One executor for every provider the router can reach: the chat inbound
+ * translates image_url parts and each adapter compiles its own wire
+ * (Anthropic blocks, Antigravity inlineData, xai Responses input_image, plain
+ * openai-chat), so provider coverage is the router's job, not this file's.
+ *
+ * Recursion fence: the request carries `x-opencodex-vision-describe: 1`.
+ * The Chat surface detects the raw header before its bridge rebuilds headers
+ * and carries it into handleResponses as `visionDescribeTerminal`; a marked
+ * request STRIPS images instead of planning another describe (depth cap 1,
+ * holds under predicate drift and combo re-resolution — audit rounds 2-4).
+ *
+ * Admission ladder (audit round 3): configuredApiAuthToken() (env token) ||
+ * service token file || first config.apiKeys entry, sent as
+ * `x-opencodex-api-key` — never Authorization (gateway-cache.ts rule: an
+ * admission secret in a forwardable header is a forwarding hazard). Loopback
+ * binds require no token at all (resolveApiAuth admits loopback).
+ *
+ * Known limitation (recorded in roadmap 170): a bindHost where 127.0.0.1
+ * does not answer cannot reach its own loopback — same latent limitation
+ * gateway-cache has.
+ */
+import type { OcxConfig } from "../types";
+import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
+import { redactSecretString } from "../lib/redact";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import { configuredApiAuthToken, configuredPort } from "../server/auth-cors";
+import { loadServiceTokenFromFile } from "../lib/service-secrets";
+import type { DescribeOutcome, VisionSettings } from "./describe";
+
+export const VISION_DESCRIBE_TERMINAL_HEADER = "x-opencodex-vision-describe";
+
+const ALLOWED_IMAGE_MIME = new Set(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]);
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Bound the loopback JSON response; descriptions are clamped to ~2k chars by the caller anyway. */
+const MAX_ROUTED_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+const DESCRIBE_INSTRUCTION =
+  "You are a vision describer for a text-only model that cannot see the image. Describe the image "
+  + "thoroughly and factually so that model can fully reason about it: transcribe any visible text "
+  + "verbatim, and note UI/layout, colors, branding/logos, charts, and notable details. Focus on "
+  + "what's relevant to the user's request. Output only the description.";
+
+function validateImageUrl(url: string): string | null {
+  if (url.startsWith("data:")) {
+    const match = /^data:([^;,]+?)(;base64)?,(.*)$/s.exec(url);
+    if (!match) return "malformed data URL";
+    const mime = match[1].toLowerCase();
+    if (!ALLOWED_IMAGE_MIME.has(mime)) return `unsupported image type "${mime}"`;
+    if (match[2]) {
+      const bytes = Math.floor((match[3].length * 3) / 4);
+      if (bytes > MAX_IMAGE_BYTES) return `image too large (~${Math.round(bytes / 1024 / 1024)}MB)`;
+    }
+    return null;
+  }
+  if (url.startsWith("https://")) return null;
+  return "unsupported image URL scheme (expected data: or https:)";
+}
+
+/** The admission ladder: env token, service token file, first configured API key. */
+export function routedDescribeAdmissionToken(config: Pick<OcxConfig, "apiKeys">): string | undefined {
+  const envToken = configuredApiAuthToken();
+  if (envToken) return envToken;
+  const fileToken = loadServiceTokenFromFile(process.env);
+  if (fileToken) return fileToken;
+  const first = config.apiKeys?.[0]?.key?.trim();
+  return first || undefined;
+}
+
+/** Base URL seam for tests; production always self-fetches loopback. */
+export function routedDescribeBaseUrl(config: Pick<OcxConfig, "port">): string {
+  // config.port can be 0 (ephemeral bind, tests) or stale after a live port
+  // override; the server records its ACTUAL bound port via setCorsOrigin at
+  // startup, so prefer that when config carries no positive port.
+  const port = config.port && config.port > 0 ? String(config.port) : configuredPort();
+  return `http://127.0.0.1:${port}`;
+}
+
+export async function describeImageRouted(
+  imageUrl: string,
+  _detail: string | undefined,
+  contextText: string,
+  routedModel: string,
+  config: Pick<OcxConfig, "port" | "apiKeys">,
+  settings: VisionSettings,
+  abortSignal?: AbortSignal,
+  baseUrlOverride?: string,
+): Promise<DescribeOutcome> {
+  const invalid = validateImageUrl(imageUrl);
+  if (invalid) return { text: "", error: invalid };
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    [VISION_DESCRIBE_TERMINAL_HEADER]: "1",
+  };
+  const admission = routedDescribeAdmissionToken(config);
+  if (admission) headers["x-opencodex-api-key"] = admission;
+
+  const requestBody = {
+    model: routedModel,
+    stream: false,
+    messages: [
+      { role: "system", content: DESCRIBE_INSTRUCTION },
+      {
+        role: "user",
+        content: [
+          ...(contextText ? [{ type: "text", text: `User's request context: ${contextText}` }] : []),
+          { type: "image_url", image_url: { url: imageUrl } },
+        ],
+      },
+    ],
+  };
+
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("vision");
+  const t0 = Date.now();
+  try {
+    const res = await fetch(`${baseUrlOverride ?? routedDescribeBaseUrl(config)}/v1/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+      signal: linkedSignal.signal,
+      redirect: "manual",
+    });
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      const raw = await res.text();
+      if (raw.length > MAX_ROUTED_RESPONSE_BYTES) {
+        return { text: "", error: "routed describe response exceeded byte bound" };
+      }
+      if (!res.ok) {
+        return { text: "", error: `routed describe HTTP ${res.status}: ${redactSecretString(raw.slice(0, 200))}` };
+      }
+      let payload: unknown;
+      try { payload = JSON.parse(raw); } catch {
+        return { text: "", error: "routed describe returned non-JSON" };
+      }
+      const content = extractChatContent(payload);
+      if (!content) return { text: "", error: "routed describe returned no text" };
+      return { text: content };
+    } finally {
+      detachBodyGuard();
+    }
+  } catch (e) {
+    const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    console.warn(`[vision] routed describe ${kind} (${Date.now() - t0}ms)`);
+    return { text: "", error: redactSecretString(e instanceof Error ? e.message : String(e)) };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}
+
+function extractChatContent(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const choices = (payload as { choices?: unknown }).choices;
+  if (!Array.isArray(choices) || choices.length === 0) return undefined;
+  const message = (choices[0] as { message?: unknown })?.message;
+  if (!message || typeof message !== "object") return undefined;
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string" && content.trim().length > 0) return content;
+  // Some adapters emit content parts; join text parts.
+  if (Array.isArray(content)) {
+    const joined = content
+      .map(part => (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string"
+        ? (part as { text: string }).text
+        : ""))
+      .join("");
+    if (joined.trim().length > 0) return joined;
+  }
+  return undefined;
+}

package/src/vision/timeout-bounds.ts

@@ -0,0 +1,9 @@
+/**
+ * Inclusive integer bounds for `visionSidecar.timeoutMs`.
+ * The ceiling is the 32-bit timer delay used by `signalWithTimeout` / `setTimeout`.
+ * This module is the single authority: the runtime, management API, and Dashboard
+ * import these numbers rather than restating them.
+ */
+export const DEFAULT_VISION_TIMEOUT_MS = 45_000;
+export const MIN_VISION_TIMEOUT_MS = 1;
+export const MAX_VISION_TIMEOUT_MS = 2_147_483_647;