@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/types/provider.ts

@@ -356,6 +356,22 @@ export interface OcxProviderConfig {
    * `ocxr1` envelopes are still stripped because no upstream can decrypt them.
    */
   preserveResponsesReasoningContent?: boolean;
+  /**
+   * Treat this provider's `modelReasoningEfforts` as authoritative at the wire, not only in the
+   * catalog. Adapters that ship their own per-model effort table (currently `command-code`)
+   * otherwise let that table win for models it knows, so a widened row is advertised in the
+   * picker and then stripped on the way out. Opt-in because presets are SEEDED with the shipped
+   * table: without a declared flag there is no way to tell an operator's row from a copy an
+   * older release persisted. A rung the upstream then refuses is returned as that error rather
+   * than silently retried without the effort, since the operator asked for it.
+   */
+  modelReasoningEffortsAuthoritative?: boolean;
+  /**
+   * Drop replayed Responses `reasoning` items from input history before forwarding.
+   * Some OpenAI-compatible Responses upstreams accept tool-call replay but reject
+   * reasoning output items when they are sent back on a continuation.
+   */
+  dropResponsesReasoningItems?: boolean;
   /**
    * Explicit opt-in for a relay that genuinely fronts OpenAI and can decode native
    * compaction blobs. Absent or false degrades foreign blobs to an opaque note.
@@ -618,6 +634,8 @@ export interface OcxProviderConfig {
   reasoningEfforts?: string[];
   /** Model-specific Codex-visible reasoning tiers. An empty array means “do not expose effort”. */
   modelReasoningEfforts?: Record<string, string[]>;
+  /** Catalog-only: do not synthesize a missing max rung for matching routed models. */
+  modelSuppressSyntheticMax?: Record<string, boolean>;
   /** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
   modelDefaultReasoningEfforts?: Record<string, string>;
   /** Operator-owned effort override; none omits effort and uses the provider default. */
@@ -677,6 +695,23 @@ export interface OcxProviderConfig {
    * apply_patch passthrough compatibility for OpenAI and unclassified gateways.
    */
   supportsResponsesCustomTools?: boolean;
+  /**
+   * Hosted tool declarations this Responses destination rejects, so they are stripped from
+   * the request instead of being forwarded and 400'd.
+   *
+   * This is how an OpenAI-compatible gateway with a narrower capability set than OpenAI
+   * describes itself. Before it existed, a destination that accepted plain Responses and
+   * `function` tools but rejected hosted `web_search` could only be handled by adding a
+   * hard-coded baseUrl rule to `src/responses/hosted-tool-policy.ts`, so every such gateway
+   * needed a proxy release; a text-only prompt like "Reply exactly with OK" failed before
+   * the model answered because the hosted declaration travelled with it (#5002).
+   *
+   * Values come from `DECLARABLE_HOSTED_TOOL_TYPES`. Spelling variants of one capability
+   * are aliased, so `["web_search"]` also denies `web_search_preview`. Pair this with
+   * `supportsResponsesCustomTools: false` for a gateway that also rejects native custom
+   * tools; the two capabilities are independent and denied independently.
+   */
+  unsupportedHostedTools?: string[];
   /**
    * Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
    * fields or closing events (#893). Disabled by default and applied only to client-facing
@@ -882,6 +917,8 @@ export interface OcxProviderConfig {
    * "cloud-code-assist" = Google Antigravity (Cloud Code Assist) OAuth + CCA envelope.
    */
   googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
+  /** Google tool-schema compatibility policy. Omitted preserves compatible report-only behavior. */
+  googleToolSchemaPolicy?: "compatible" | "reject-lossy";
   /** Vertex AI GCP project id (or GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env). */
   project?: string;
   /** Vertex AI location, e.g. "us-central1" or "global" (or GOOGLE_CLOUD_LOCATION env). */

package/src/types/request.ts

@@ -68,6 +68,12 @@ export interface OcxParsedRequest {
   _cursorConversationId?: string;
   /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
   _clientThreadId?: string;
+  /**
+   * This request's OWN Codex thread id (`thread-id`), as opposed to `_clientThreadId`, which
+   * carries `x-codex-parent-thread-id` and is therefore shared by every parallel child of one
+   * parent. Only a surface that must distinguish siblings should read it.
+   */
+  _codexOwnThreadId?: string;
   /** True when promptCacheKey identifies a shared cache cohort rather than one conversation. */
   _promptCacheKeyIsSharedCohort?: boolean;
   /** Cursor-only thread owner; may be an opaque process-local Desktop session/thread identity. */
@@ -120,6 +126,8 @@ export interface OcxParsedRequest {
    * (see src/responses/compaction.ts).
    */
   _compactionRequest?: boolean;
+  /** Manual compaction moved to another provider: summarize portably even on a canonical ChatGPT target. */
+  _portableCompaction?: boolean;
   /**
    * True when the current request newly introduced a stored compaction summary/marker. Historical
    * markers restored by previous_response_id expansion were already acknowledged and do not reset
@@ -312,7 +320,7 @@ export interface OcxProviderContinuationState {
 }
 
 export type AdapterEvent =
-  | { type: "heartbeat" }
+  | { type: "heartbeat"; replayUnsafe?: true }
   | { type: "text_delta"; text: string; phase?: OcxMessagePhase }
   | { type: "thinking_delta"; thinking: string }
   // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and

package/src/types/tools.ts

@@ -67,6 +67,20 @@ const CODE_MODE_HELPER_TOOL_NAMES = [
  */
 export const CODE_MODE_EXEC_TOOL_NAME = "exec";
 
+/**
+ * The nested-helper spellings, as a membership view of the same list.
+ *
+ * A code-mode catalog never DECLARES any of them — they exist only as `tools.<helper>(...)` inside
+ * `exec` — so a recorded call under one of these names can only have come from a provider echoing
+ * the helper, which is what makes the set usable as a bounded recovery vocabulary for stored
+ * history (#5095). Kept beside the tuple it is built from so the two can never drift; this is a
+ * different question from `NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES` below, which also covers `exec`
+ * itself because declaring THAT name is what turns normalization on.
+ */
+export const CODE_MODE_HELPER_WIRE_NAMES: ReadonlySet<string> = new Set<string>(
+  CODE_MODE_HELPER_TOOL_NAMES,
+);
+
 /**
  * Spellings that may never be MANUFACTURED as a bare alias for a namespaced tool.
  *

package/src/types/wire.ts

@@ -46,7 +46,15 @@ export const MODEL_ADAPTER_OVERRIDE_ALLOWED: ReadonlySet<string> = new Set([
  * Anthropic for these models.
  */
 const ANTHROPIC_WIRE_MODELS: Record<string, ReadonlySet<string>> = {
-  "opencode-go": new Set(["minimax-m2.5", "minimax-m2.7", "minimax-m3"]),
+  "opencode-go": new Set([
+    "minimax-m2.5",
+    "minimax-m2.7",
+    "minimax-m3",
+    // OpenCode's catalog identifies Union Alpha as @ai-sdk/anthropic while the
+    // provider defaults to OpenAI-compatible; direct Chat returns 500 and direct
+    // Messages reaches the session check (#4847).
+    "union-alpha",
+  ]),
 };
 
 function anthropicWireModelsForProvider(providerName: string): ReadonlySet<string> | undefined {

package/src/types.ts

@@ -4,6 +4,7 @@
 export type { OcxTool, OcxToolChoice } from "./types/tools";
 export {
   CODE_MODE_EXEC_TOOL_NAME,
+  CODE_MODE_HELPER_WIRE_NAMES,
   dottedToolName,
   namespacedToolName,
   normalizeDeclaredToolName,

package/src/usage/expected-prices.ts

@@ -124,6 +124,16 @@ const META_MUSE_SPARK_13_CONTRIBUTOR: Cost4 = { input: 0.1, output: 0.2, cacheRe
 const META_SPARK_SOURCE = `Meta Model API published price ${META_MODEL_PRICING}`;
 const META_SPARK_CONTRIBUTOR_SOURCE = `Meta Model API published Contributor-tier price ${META_MODEL_PRICING}; data-sharing discount tier`;
 const DEEPSEEK_PRICING = "https://api-docs.deepseek.com/quick_start/pricing-details-usd; V4 Flash alias transition scheduled 2026-07-24 — re-verify after";
+/*
+ * DeepSeek V4.1-Flash list prices (USD / 1M tokens), verified 2026-09-17 against
+ * https://api-docs.deepseek.com/quick_start/pricing. The page prices a peak window
+ * (09:30-24:00 Beijing) and an off-peak window; the tuple below is the peak-window
+ * list rate and the off-peak discount (0.15 / 0.60, cache-hit 0.003) is deliberately
+ * not baked in — the same rule as the Devin time-boxed promos. cacheWrite=0 follows
+ * the existing deepseek-chat / deepseek-reasoner rows: DeepSeek publishes no
+ * cache-write charge.
+ */
+const DEEPSEEK_V41_FLASH: Cost4 = { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 };
 // Kimi official tables publish input/output/cache-hit only; cacheWrite is mapped to the
 // cache-miss input price (Kimi auto-caches with no separate write billing). 2026-07-20 re-verified.
 const KIMI_PRICING = "https://platform.kimi.ai/docs/pricing (official table; cacheWrite derived = input, Kimi auto-cache has no write billing)";
@@ -142,6 +152,14 @@ const BIGMODEL_NOTE = "z.ai international list price shown as estimate; domestic
 // anywhere. Cache stays 0 rather than inheriting the reseller's 0.15 — a reseller number
 // under a vendor-price label would be a wrong value wearing a verified badge.
 const QWEN38_MAX_PRICING = "https://qwen.ai/blog?id=qwen3.8 (Qwen release announcement; no Model Studio billing row yet; cache rates unpublished -> 0)";
+// Qwen-published qwen3.8-flash rate ($0.16 in / $0.47 out per 1M tokens) via the
+// Qwen3.8 release announcement, corroborated by API-vendor price tables. No cache
+// rate is published anywhere, so cache stays 0 rather than borrowing a reseller's
+// number — the same hold QWEN38_MAX takes. The announcement marks API availability
+// as coming soon, but the id is already served (and logged) on OpenCode Go, so the
+// estimate applies to real usage rows now.
+const QWEN38_FLASH: Cost4 = { input: 0.16, output: 0.47, cacheRead: 0, cacheWrite: 0 };
+const QWEN38_FLASH_PRICING = "https://qwen.ai/blog?id=qwen3.8-2026 (Qwen release announcement; API marked coming soon at announcement; cache rates unpublished -> 0; input/output corroborated by https://docs.b.ai/guides/models/qwen/qwen3.8-flash)";
 
 /*
  * Cognition/Devin list prices (USD / 1M tokens), verified 2026-09-13 against the
@@ -289,6 +307,16 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   // for what that source does and does not cover.
   { provider: "alibaba-token-plan", modelId: "qwen3.8-max", cost4: QWEN38_MAX, source: QWEN38_MAX_PRICING, verifiedAt: "2026-08-04", status: "verified" },
   { provider: "alibaba-token-plan-intl", modelId: "qwen3.8-max", cost4: QWEN38_MAX, source: QWEN38_MAX_PRICING, verifiedAt: "2026-08-04", status: "verified" },
+  // OpenCode Go — five served ids with no jawcode bundle row and no vendor-level
+  // fallback (the fallback only searches jawcode metadata, never overlays), so the
+  // Usage estimated-cost column and the per-model breakdown rendered an em dash for
+  // every request through them. Each row reuses the vendor's own published list
+  // price as an estimate: Go itself is subscription-billed, hence verified-derived.
+  { provider: "opencode-go", modelId: "qwen3.8-max", cost4: QWEN38_MAX, source: `vendor list price applied to the OpenCode Go surface; ${QWEN38_MAX_PRICING}`, verifiedAt: "2026-09-17", status: "verified-derived" },
+  { provider: "opencode-go", modelId: "qwen3.8-flash", cost4: QWEN38_FLASH, source: `vendor list price applied to the OpenCode Go surface; ${QWEN38_FLASH_PRICING}`, verifiedAt: "2026-09-17", status: "verified-derived" },
+  { provider: "opencode-go", modelId: "deepseek-v4.1-flash", cost4: DEEPSEEK_V41_FLASH, source: `peak-window list rate applied to the OpenCode Go surface (off-peak 0.15/0.60 + cache-hit 0.003 not baked in); ${DEEPSEEK_PRICING}`, verifiedAt: "2026-09-17", status: "verified-derived" },
+  { provider: "opencode-go", modelId: "glm-5.3-flash", cost4: GLM_53_FLASH, source: `z.ai list price applied to the OpenCode Go surface as an estimate; ${ZAI_PRICING}`, verifiedAt: "2026-09-17", status: "verified-derived" },
+  { provider: "opencode-go", modelId: "muse-spark-1.3-contributor", cost4: META_MUSE_SPARK_13_CONTRIBUTOR, source: `Meta Model API Contributor-tier price applied to the OpenCode Go surface as an estimate; ${META_SPARK_CONTRIBUTOR_SOURCE}`, verifiedAt: "2026-09-17", status: "verified-derived" },
   // Cursor Auto router — Cursor's published fixed token price (verified).
   { 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" },
   // Z.AI GLM family — the zai bundle's rows are all-zero upstream, and the four

package/src/usage/log.ts

@@ -77,6 +77,26 @@ export type AttemptRecoveryKind =
   | "empty-completion"
   | "reasoning-effort-downgrade";
 
+/**
+ * Why a recovery this request was otherwise willing to make did not happen.
+ *
+ * Recorded separately from `recoveryKinds` and from `sendCount`, because the question it
+ * answers is different from either. A log showing one physical send and no recovery kind used
+ * to be ambiguous: it could mean nothing was eligible, or that something was eligible and the
+ * send budget withheld it. Those need opposite follow-ups, and the second one was invisible
+ * (#5044).
+ *
+ * `sendCount` deliberately does not move for these. A refused attempt is not a physical send,
+ * and inflating the count to signal the refusal would corrupt the one number that means
+ * "requests this proxy actually made".
+ *
+ * Bounded vocabulary on purpose: it is a wire value a maintainer reads, never a credential, an
+ * account id, an upstream body, prompt content, or exception text.
+ */
+export type AttemptRecoveryWithheld =
+  | "retry-send-budget"
+  | "rotation-send-budget";
+
 /** Request-time upstream credential class, never a credential or account identifier. */
 export type UsageCredentialSource = "grok-oauth" | "xai-api-key";
 
@@ -139,6 +159,11 @@ export interface PersistedUsageAttempt {
   firstOutputMs?: number;
   sendCount: number;
   recoveryKinds: AttemptRecoveryKind[];
+  /**
+   * Recoveries this attempt was eligible for and did not make. Absent on ordinary attempts so
+   * old rows keep their exact shape.
+   */
+  recoveryWithheld?: AttemptRecoveryWithheld[];
   usageStatus: UsageStatus;
   /**
    * True when the proxy answered this turn locally and issued no upstream request. It travels on
@@ -487,6 +512,10 @@ const ATTEMPT_RECOVERY_KINDS = new Set<AttemptRecoveryKind>([
   "empty-completion",
   "reasoning-effort-downgrade",
 ]);
+const ATTEMPT_RECOVERY_WITHHELD = new Set<AttemptRecoveryWithheld>([
+  "retry-send-budget",
+  "rotation-send-budget",
+]);
 const USAGE_STATUSES = new Set<UsageStatus>([
   "reported",
   "unreported",
@@ -620,6 +649,14 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
         && ATTEMPT_RECOVERY_KINDS.has(value as AttemptRecoveryKind),
     ))]
     : [];
+  // Same shape as `recoveryKinds`: unknown values are dropped rather than failing the row, so a
+  // log written by a newer build stays readable by an older one.
+  const recoveryWithheld = Array.isArray(attempt.recoveryWithheld)
+    ? [...new Set(attempt.recoveryWithheld.filter(
+      (value): value is AttemptRecoveryWithheld => typeof value === "string"
+        && ATTEMPT_RECOVERY_WITHHELD.has(value as AttemptRecoveryWithheld),
+    ))]
+    : [];
   return {
     ordinal: attempt.ordinal as number,
     provider: attempt.provider,
@@ -639,6 +676,7 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
       : {}),
     sendCount: attempt.sendCount as number,
     recoveryKinds,
+    ...(recoveryWithheld.length ? { recoveryWithheld } : {}),
     usageStatus: attempt.usageStatus as UsageStatus,
     ...(isCodexUsageAccountLogLabel(attempt.accountLogLabel)
       ? { accountLogLabel: attempt.accountLogLabel }
@@ -852,18 +890,61 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
   };
 }
 
-function ensureUsageLogDir(): void {
+// Bound hot-path filesystem hardening to once per second while ensuring an external mode
+// widening cannot suppress write-triggered repair for the lifetime of the process.
+const USAGE_LOG_PERMISSION_RECHECK_MS = 1_000;
+
+type UsageLogPermissionCheck = {
+  path: string;
+  checkedAt: number;
+};
+
+let ensuredUsageLogDir: UsageLogPermissionCheck | null = null;
+let ensuredUsageLogFile: UsageLogPermissionCheck | null = null;
+
+function usageLogPermissionCheckIsCurrent(
+  check: UsageLogPermissionCheck | null,
+  path: string,
+  now: number,
+): boolean {
+  return check?.path === path
+    && now >= check.checkedAt
+    && now - check.checkedAt < USAGE_LOG_PERMISSION_RECHECK_MS;
+}
+
+function ensureUsageLogDir(now: number): void {
   const dir = getConfigDir();
+  if (usageLogPermissionCheckIsCurrent(ensuredUsageLogDir, dir, now)) return;
   recordOwnedConfigPath(dir, usageLogPath());
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   try { chmodSync(dir, 0o700); } catch { /* best-effort on platforms that ignore chmod */ }
+  ensuredUsageLogDir = { path: dir, checkedAt: now };
 }
 
 export function appendUsageEntry(entry: PersistedUsageEntry): void {
-  ensureUsageLogDir();
+  const line = `${JSON.stringify(normalizeUsageEntry(entry))}\n`;
   const path = usageLogPath();
-  appendFileSync(path, `${JSON.stringify(normalizeUsageEntry(entry))}\n`, { encoding: "utf-8", mode: 0o600 });
-  try { chmodSync(path, 0o600); } catch { /* best-effort on platforms that ignore chmod */ }
+  const now = Date.now();
+  const doAppend = (): void => {
+    ensureUsageLogDir(now);
+    const filePermissionsCurrent = usageLogPermissionCheckIsCurrent(ensuredUsageLogFile, path, now);
+    appendFileSync(path, line, { encoding: "utf-8", mode: 0o600 });
+    if (!filePermissionsCurrent) {
+      try { chmodSync(path, 0o600); } catch { /* best-effort on platforms that ignore chmod */ }
+      ensuredUsageLogFile = { path, checkedAt: now };
+    }
+  };
+  try {
+    doAppend();
+  } catch (error: any) {
+    if (error?.code === "ENOENT") {
+      ensuredUsageLogDir = null;
+      ensuredUsageLogFile = null;
+      doAppend();
+      return;
+    }
+    throw error;
+  }
 }
 
 export type UsageLogRevision = {
@@ -1057,6 +1138,8 @@ export function resetUsageReadCacheForTests(): void {
   managementUsageReadInflight?.abort.abort();
   managementUsageReadInflight = null;
   retainedUsageSnapshot = null;
+  ensuredUsageLogDir = null;
+  ensuredUsageLogFile = null;
 }
 
 function readExactly(fd: number, length: number, position: number): Buffer | null {

package/src/vision/eligibility.ts

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

package/src/vision/plan.ts

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