@bitkyc08/opencodex 2.30.0-preview.20260821 → 2.31.0

package/src/usage/expected-prices.ts

@@ -181,6 +181,30 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "cursor", modelId: "auto", cost4: { input: 1.25, output: 6, cacheRead: 0.25, cacheWrite: 1.25 }, source: "https://docs.cursor.com/account/pricing + https://cursor.com/blog/aug-2025-pricing", verifiedAt: "2026-07-20", status: "verified" },
 ];
 
+/**
+ * Exact official corrections for stale nonzero catalog rows. These are intentionally separate
+ * from fallback overlays: they win over the bundled row only for the declared provider/model and
+ * therefore cannot reprice routed resellers that reuse the same model slug.
+ */
+export const VERIFIED_PRICE_OVERRIDES: readonly ExpectedPriceOverlay[] = [
+  {
+    provider: "xai",
+    modelId: "grok-4.6",
+    cost4: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    source: "https://docs.x.ai/developers/pricing",
+    verifiedAt: "2026-08-18",
+    status: "verified",
+  },
+];
+
+export function findVerifiedPriceOverride(
+  provider: string,
+  modelId: string,
+  overrides: readonly ExpectedPriceOverlay[] = VERIFIED_PRICE_OVERRIDES,
+): ExpectedPriceOverlay | undefined {
+  return overrides.find(row => row.provider === provider && row.modelId === modelId);
+}
+
 /**
  * Exact-key overlay lookup. Returns verified first, then verified-derived.
  * NEVER returns "unverified" rows — fail-closed is enforced in code, not just docs.
@@ -196,12 +220,7 @@ export function findExpectedPriceOverlay(
     ?? exact.find(row => row.status === "verified-derived");
 }
 
-/**
- * OpenAI Fast mode (`service_tier=priority`) price multipliers by model slug.
- * Source: https://openai.com/api-fast-mode/ (2026-07-31).
- * Fast pricing applies uniformly to all token types (input, output, cache).
- * Models not listed here fall back to 1× (no multiplier).
- */
+/** OpenAI Fast price multipliers retained as a compatibility export. */
 export const PRIORITY_MULTIPLIERS: Readonly<Record<string, number>> = {
   "gpt-5.6-sol": 2,
   // Post-price-cut Fast tables (https://openai.com/api-fast-mode/, 2026-08-05):
@@ -219,6 +238,52 @@ export function resolvePriorityMultiplier(modelId: string): number {
   return PRIORITY_MULTIPLIERS[modelId] ?? 1;
 }
 
+export interface PriorityPricingRule {
+  provider: string;
+  modelId: string;
+  multiplier: number;
+  /** Apply the premium only after the upstream response confirms this tier. */
+  requiresResponseConfirmation?: true;
+  source: string;
+  verifiedAt: string;
+}
+
+const OPENAI_FAST_PRICING = "https://openai.com/api-fast-mode/";
+const XAI_PRIORITY_PRICING = "https://docs.x.ai/developers/advanced-api-usage/priority-processing";
+
+/**
+ * Exact provider/model priority premiums. Routed resellers never inherit a vendor rule merely
+ * because they reuse its model slug. Multipliers apply uniformly after cache discounts.
+ */
+export const PRIORITY_PRICING_RULES: readonly PriorityPricingRule[] = [
+  ...["openai", "openai-apikey"].flatMap(provider =>
+    Object.entries(PRIORITY_MULTIPLIERS).map(([modelId, multiplier]): PriorityPricingRule => ({
+      provider,
+      modelId,
+      multiplier,
+      source: OPENAI_FAST_PRICING,
+      verifiedAt: "2026-08-05",
+    })),
+  ),
+  ...["grok-4.5", "grok-4.6"].map((modelId): PriorityPricingRule => ({
+    provider: "xai",
+    modelId,
+    multiplier: 2,
+    requiresResponseConfirmation: true,
+    source: XAI_PRIORITY_PRICING,
+    verifiedAt: "2026-08-18",
+  })),
+];
+
+/** Exact provider/model priority-pricing lookup. */
+export function findPriorityPricingRule(
+  provider: string,
+  modelId: string,
+  rules: readonly PriorityPricingRule[] = PRIORITY_PRICING_RULES,
+): PriorityPricingRule | undefined {
+  return rules.find(rule => rule.provider === provider && rule.modelId === modelId);
+}
+
 /**
  * Long-context pricing tiers (#908). Several vendors reprice the ENTIRE request
  * once the prompt crosses a published input-token threshold, so a flat Cost4
@@ -244,6 +309,8 @@ export interface ContextTier {
   inclusive: boolean;
   /** Per-field factor from the short rate to the published long rate. */
   multiplier: Cost4;
+  /** Published relationship between confirmed priority and long-context bands. */
+  confirmedPriorityRelation?: "exclusive" | "lower-bound";
   source: string;
   verifiedAt: string;
 }
@@ -277,6 +344,7 @@ export const CONTEXT_TIERS: readonly ContextTier[] = [
       thresholdInputTokens: 272_000,
       inclusive: false,
       multiplier: OPENAI_LONG_CONTEXT,
+      confirmedPriorityRelation: "exclusive",
       source: OPENAI_PRICING_DOC,
       verifiedAt: "2026-08-03",
     })),
@@ -287,19 +355,21 @@ export const CONTEXT_TIERS: readonly ContextTier[] = [
     thresholdInputTokens: 200_000,
     inclusive: true,
     multiplier: UNIFORM_DOUBLE,
+    confirmedPriorityRelation: "lower-bound",
     source: "https://docs.x.ai/developers/pricing",
     verifiedAt: "2026-08-03",
   },
   {
-    // 260813: grok-4.6 long-context tier mirrored from grok-4.5; the official pricing row
-    // was not yet published when the model page went up, so treat as provisional.
+    // xAI publishes the whole-request >=200k band for grok-4.6. Its combination with
+    // Priority Processing is not published, so confirmed priority uses this row as a lower bound.
     provider: "xai",
     modelId: "grok-4.6",
     thresholdInputTokens: 200_000,
     inclusive: true,
     multiplier: UNIFORM_DOUBLE,
+    confirmedPriorityRelation: "lower-bound",
     source: "https://docs.x.ai/developers/pricing",
-    verifiedAt: "2026-08-13",
+    verifiedAt: "2026-08-18",
   },
   {
     // daybreak-blue-latest aliases gpt-5.6-sol, which publishes the full long-context row

package/src/vision/backends.ts

@@ -0,0 +1,97 @@
+/**
+ * Which backends may DESCRIBE images for the vision sidecar, and which
+ * candidate rows each can describe through (#2188 vision rules; roadmap 170
+ * REVISED: the "routed" backend).
+ *
+ * A SIBLING of WEB_SEARCH_BACKENDS, not a shared table: vision has no
+ * per-model probe (rule 2 is "− provably text-only", enforced by
+ * modelAcceptsImageInput, not here), carries per-side baseline models, and
+ * excludes non-LLM backends like exa.
+ *
+ * Three backends, not one per provider: "openai" and "anthropic" carry auth
+ * semantics loopback routing cannot replicate (forwarded ChatGPT headers,
+ * OAuth beta fences) and their defaults must not drift. Every OTHER
+ * picker-visible provider row reaches the describer through "routed" — a
+ * loopback self-fetch of the proxy's own /v1/chat/completions, where the
+ * router and adapters already speak each provider's wire. That is what makes
+ * this table closed under provider growth: a new provider needs no new
+ * describe executor.
+ */
+import type { OcxConfig } from "../types";
+import type { SidecarAuthState } from "../sidecar/auth";
+import { listOpenAiForwardSidecarCandidates } from "../providers/openai-sidecar";
+import type { VisionCandidateModel, VisionSidecarBackend } from "./eligibility";
+
+export interface VisionBackendDescriptor {
+  backend: VisionSidecarBackend;
+  /** Liveness signal for this backend. */
+  isActive(auth: SidecarAuthState, config: OcxConfig): boolean;
+  /** Which candidate rows this backend's describe executor can actually run. */
+  candidateMatch(candidate: VisionCandidateModel, auth: SidecarAuthState): boolean;
+  /**
+   * Default entry for this side: cheap, image-capable, present in every
+   * deployment. Only the two universal sides carry one — "routed" has no
+   * universal model to name.
+   */
+  baseline?: string;
+  /** Stable option ordering (baselines first within a side). */
+  rank: number;
+}
+
+export const VISION_BACKENDS: readonly VisionBackendDescriptor[] = [
+  {
+    backend: "openai",
+    // The OpenAI describer needs a CANONICAL ChatGPT forward provider, not
+    // merely a provider keyed "openai" — same predicate the runtime sidecar
+    // resolver uses. Deliberately NOT auth.isCodexAuth: tightening to a live
+    // credential here would change which options a fresh install sees, and
+    // the options list is a suggestion surface, not the write gate.
+    isActive: (_auth, config) => listOpenAiForwardSidecarCandidates(config).length > 0,
+    candidateMatch: candidate => candidate.native === true || candidate.provider === "openai",
+    baseline: "gpt-5.6-luna",
+    rank: 0,
+  },
+  {
+    backend: "anthropic",
+    isActive: auth => auth.isAnthropicAuth,
+    // The runtime dispatches through exactly ONE Anthropic provider — the
+    // resolved OAuth row. Same-adapter keyed rows are unreachable (see
+    // visionBackendForCandidate's original stance).
+    candidateMatch: (candidate, auth) => candidate.provider === auth.anthropicProviderName,
+    baseline: "claude-haiku-4-5",
+    rank: 1,
+  },
+  {
+    backend: "routed",
+    // Always offered: options only materialize when a matching picker row
+    // exists, and the row's own provider config is the liveness signal — the
+    // loopback request fails closed through ordinary routing errors.
+    isActive: () => true,
+    // Any row the other two executors do NOT own. Auth-slot rows are
+    // entitlements of the openai/anthropic sides and never route here.
+    candidateMatch: (candidate, auth) =>
+      candidate.native !== true
+      && candidate.provider !== "openai"
+      && candidate.provider !== auth.anthropicProviderName,
+    rank: 2,
+  },
+];
+
+export function visionBackendDescriptor(backend: VisionSidecarBackend): VisionBackendDescriptor {
+  const descriptor = VISION_BACKENDS.find(entry => entry.backend === backend);
+  if (!descriptor) throw new Error(`unknown vision backend "${backend}"`);
+  return descriptor;
+}
+
+/**
+ * The active backend set for option generation. Falls back to the two
+ * UNIVERSAL sides when neither is active (fresh install: picker stays
+ * populated, permissive-unknown rule); "routed" is active by construction.
+ */
+export function activeVisionBackends(auth: SidecarAuthState, config: OcxConfig): VisionSidecarBackend[] {
+  const active = VISION_BACKENDS.filter(entry => entry.isActive(auth, config)).map(entry => entry.backend);
+  return active.includes("openai") || active.includes("anthropic")
+    ? active
+    : ["openai", "anthropic", ...active.filter(backend => backend === "routed")];
+}
+

package/src/vision/eligibility.ts

@@ -26,15 +26,27 @@ import { nativeInputModalities } from "../codex/catalog/metadata";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
 import { enrichProviderFromRegistry } from "../providers/derive";
 
-/** The two wire protocols `planVisionSidecar` can actually dispatch to. */
-export type VisionSidecarBackend = "openai" | "anthropic";
+/**
+ * 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<VisionSidecarBackend, string> = {
+export const BASELINE_VISION_MODELS: Record<UniversalVisionBackend, string> = {
   openai: "gpt-5.6-luna",
   anthropic: "claude-haiku-4-5",
 };
@@ -146,7 +158,7 @@ function isVisionEligibleModelWithCache(
   return modelAcceptsImageInputWithCache(config, candidate, cache) !== false;
 }
 
-/** Which executor can describe through this row, or undefined when neither can. */
+/** Which executor can describe through this row. */
 export function visionBackendForCandidate(
   config: Pick<OcxConfig, "providers">,
   candidate: VisionCandidateModel,
@@ -158,17 +170,17 @@ export function visionBackendForCandidate(
   // 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.
-  //
-  // So the executor's name is REQUIRED for an Anthropic suggestion. When the caller has no
-  // executor to name, no catalog row qualifies; the side's baseline is added separately and
-  // keeps the picker populated. Narrowing here never widens the write gate, which is a
-  // different predicate (`modelAcceptsImageInput`) and still treats unknown as allowed.
-  if (anthropicProviderName === undefined) return undefined;
-  return candidate.provider === anthropicProviderName ? "anthropic" : undefined;
+  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: VisionSidecarBackend,
+  backend: UniversalVisionBackend,
   anthropicProviderName: string | undefined,
 ): VisionCandidateModel {
   return {
@@ -181,12 +193,13 @@ function baselineCandidate(
 }
 
 /**
- * The picker's option list: every eligible row reachable by one of the two
- * executors, plus each enabled side's baseline unless that baseline is explicitly
- * excluded, de-duplicated and stably ordered (openai side first, 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.
+ * 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
@@ -208,7 +221,7 @@ export function visionEligibleModelOptions(
   const byValue = new Map<string, VisionModelOption>();
   const enrichedProviders: EnrichedProviderCache = new Map();
 
-  for (const backend of ["openai", "anthropic"] as const) {
+  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;
@@ -219,11 +232,19 @@ export function visionEligibleModelOptions(
     const backend = visionBackendForCandidate(config, candidate, anthropicProviderName);
     if (!backend || !enabled.has(backend)) continue;
     if (!isVisionEligibleModelWithCache(config, candidate, enrichedProviders)) continue;
-    if (byValue.has(candidate.id)) continue;
-    byValue.set(candidate.id, { value: candidate.id, label: candidate.id, backend });
+    // 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) =>
-    (option.backend === "openai" ? 0 : 2) + (option.baseline ? 0 : 1);
+    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

@@ -5,6 +5,8 @@ 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 { resolveSidecarAuth } from "../sidecar/auth";
@@ -226,16 +228,23 @@ export function findAnthropicVisionProvider(config: OcxConfig): AnthropicVisionP
 }
 
 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 {
-  return config.visionSidecar?.model || DEFAULT_VISION_MODEL;
+  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. */
@@ -243,9 +252,15 @@ 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"
-    ? config.visionSidecar?.model || DEFAULT_ANTHROPIC_VISION_MODEL
-    : resolveOpenAiVisionModel(config);
+    ? usable || DEFAULT_ANTHROPIC_VISION_MODEL
+    : usable || DEFAULT_VISION_MODEL;
 }
 
 /** A user/developer/toolResult message can carry images (toolResult: e.g. Codex view_image output). */
@@ -271,9 +286,13 @@ export function shouldResolveOpenAiVisionSidecar(
 }
 
 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;
 }
@@ -295,8 +314,45 @@ export function planVisionSidecar(
   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);
 
@@ -447,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" };

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