fix(catalog): advertise image input for modalities-declared sidecar rows

The runtime vision gate (isModelTextOnly) covers models listed in noVisionModels OR declared text-only via modelInputModalities (upstream fde2a95, #1024), but both catalog advertise sites only checked noVisionModels. A sidecar-covered model - and every combo built from it - stayed advertised text-only in /v1/models, so the Codex app blocked image attachments client-side before the sidecar could run ('This model does not support image inputs').

Mirror isModelTextOnly in applyProviderConfigHints and the custom-model override: a declared text-only modelInputModalities entry now advertises image on top of its configured base. Discovery-derived text-only rows stay untouched (the runtime predicate does not cover those), and declared-image rows are never duplicated. Combos inherit the fix through their hinted members; no config hand-editing needed.

Update the three tests that encoded the old drift and add regressions for the hint pass, the custom-model override, and combo derivation.

Author: x3M3x

docs-site/src/content/docs/guides/sidecars.md

@@ -123,8 +123,11 @@ failures after response headers have started are delivered as `response.failed`
 
 ## Vision sidecar
 
-When the routed model is listed in its provider's `noVisionModels` and a request carries an image,
-opencodex describes each image **before** the main call and replaces it with text. When
+When the routed model is listed in its provider's `noVisionModels` — or declared text-only for
+that model via `modelInputModalities` — and a request carries an image, opencodex describes each
+image **before** the main call and replaces it with text. The model catalog advertises image input
+for every sidecar-covered model (combos advertise image when every member is covered), so clients
+such as the Codex app allow attachments instead of blocking them before the sidecar runs. When
 `visionSidecar.model` is absent or blank, the OpenAI execution path, Dashboard, and management API
 use the `gpt-5.4-mini` fallback. Startup still migrates an explicitly persisted legacy
 `gpt-5.4-mini` value to `gpt-5.6-luna`; that migration applies to a stored value, not to an absent

src/codex/catalog/provider-fetch.ts

@@ -669,11 +669,16 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
   const configuredMaxInput = configuredMaxInputTokens(prov, model.id);
   const configuredAutoCompact = configuredAutoCompactTokenLimit(prov, model.id);
   let inputModalities = configuredInputModalities(prov, model.id);
-  // Vision-sidecar coverage: `noVisionModels` marks models whose images the PROXY describes
-  // (src/vision/index.ts). The catalog must still advertise image input for them — the Codex app
+  // Vision-sidecar coverage mirrors isModelTextOnly (src/vision/index.ts): `noVisionModels` OR
+  // a `modelInputModalities` declaration excluding "image" both mean the PROXY describes images
+  // for this model at request time. The catalog must still advertise image input — the Codex app
   // gates attachments client-side on input_modalities, and a text-only entry would block images
-  // before the sidecar ever runs ("This model does not support image inputs").
-  if (modelInList(prov.noVisionModels, model.id)) {
+  // before the sidecar ever runs ("This model does not support image inputs"). Discovery-derived
+  // text-only rows stay untouched: the runtime predicate only reads these two config sources, so
+  // it would not convert those.
+  const sidecarCovered = modelInList(prov.noVisionModels, model.id)
+    || (Array.isArray(inputModalities) && inputModalities.length > 0 && !inputModalities.includes("image"));
+  if (sidecarCovered) {
     const base = inputModalities ?? model.inputModalities ?? ["text"];
     inputModalities = base.includes("image") ? [...base] : [...base, "image"];
   }
@@ -2140,7 +2145,15 @@ async function gatherRoutedModelsUncached(
       }
       : mergedWithHardBounds;
     const enrichedProvider = enrichedByName.get(cm.provider) ?? rawProvider;
-    if (enrichedProvider && modelInList(enrichedProvider.noVisionModels, mergedWithAutoCompact.id)) {
+    // Same vision-sidecar coverage rule as applyProviderConfigHints (isModelTextOnly parity):
+    // noVisionModels OR a text-only modelInputModalities declaration means the sidecar converts
+    // images at request time, so the custom row must advertise image input.
+    const declaredModalities = enrichedProvider
+      ? modelRecordValue(enrichedProvider.modelInputModalities, mergedWithAutoCompact.id)
+      : undefined;
+    if (enrichedProvider
+      && (modelInList(enrichedProvider.noVisionModels, mergedWithAutoCompact.id)
+        || (Array.isArray(declaredModalities) && declaredModalities.length > 0 && !declaredModalities.includes("image")))) {
       const current = mergedWithAutoCompact.inputModalities ?? ["text"];
       if (!current.includes("image")) {
         return { ...mergedWithAutoCompact, inputModalities: [...current, "image"] };

tests/catalog-vision-sidecar-modalities.test.ts

@@ -48,6 +48,40 @@ describe("vision-sidecar catalog modalities", () => {
     expect(hinted.inputModalities).toEqual(["text", "image"]);
   });
 
+  test("modelInputModalities-declared text-only models advertise image without a noVisionModels entry", () => {
+    // Regression: isModelTextOnly (the RUNTIME sidecar gate) treats a text-only
+    // modelInputModalities declaration exactly like a noVisionModels entry, but the catalog hint
+    // pass only checked noVisionModels — so sidecar-covered models stayed advertised text-only
+    // and the Codex app blocked image paste before the sidecar could run.
+    const prov: OcxProviderConfig = {
+      adapter: "openai-chat",
+      baseUrl: "https://api.example/v1",
+      modelInputModalities: { "deepseek-chat": ["text"] },
+    };
+    const hinted = applyProviderConfigHints("azu-lab2", prov, { id: "deepseek-chat", provider: "azu-lab2" });
+    expect(hinted.inputModalities).toEqual(["text", "image"]);
+  });
+
+  test("modelInputModalities declaring image stays untouched (no duplication)", () => {
+    const prov: OcxProviderConfig = {
+      adapter: "openai-chat",
+      baseUrl: "https://api.example/v1",
+      modelInputModalities: { "glm-5.3": ["text", "image"] },
+    };
+    const hinted = applyProviderConfigHints("vdi", prov, { id: "glm-5.3", provider: "vdi" });
+    expect(hinted.inputModalities).toEqual(["text", "image"]);
+  });
+
+  test("discovery-derived text-only rows are NOT advertised image (the runtime would not convert them)", () => {
+    // Only the two config sources the runtime predicate reads (noVisionModels,
+    // modelInputModalities) may widen the catalog; a listing that merely reports
+    // ["text"] without either must stay text-only.
+    const hinted = applyProviderConfigHints("opencode-go", base, {
+      id: "listing-text-model", provider: "opencode-go", inputModalities: ["text"],
+    });
+    expect(hinted.inputModalities).toEqual(["text"]);
+  });
+
   test("MiMo token-plan sends only the Pro model through the sidecar (#1927)", () => {
     const canonical: OcxProviderConfig = {
       adapter: "openai-chat",
@@ -173,6 +207,39 @@ describe("vision-sidecar custom-model override (#349/#344)", () => {
       globalThis.fetch = originalFetch;
     }
   });
+
+  test("a custom row whose modelId is declared text-only via modelInputModalities still advertises image", async () => {
+    // Same isModelTextOnly parity as the hint pass, applied to the custom-model override path:
+    // the registry/config text-only declaration covers the row at request time, so the catalog
+    // must let images through to the sidecar here too.
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (() => { throw new Error("fetch should not be called"); }) as typeof fetch;
+    try {
+      const models = await gatherRoutedModels({
+        port: 10100,
+        defaultProvider: "text-sidecar-provider",
+        providers: {
+          "text-sidecar-provider": {
+            baseUrl: "https://text-sidecar.example/v1",
+            adapter: "openai-chat",
+            authMode: "key",
+            liveModels: false,
+            models: ["baseline-model"],
+            modelInputModalities: { "glm-5.2": ["text"] },
+          },
+        },
+        customModels: [
+          { id: "cm-4", provider: "text-sidecar-provider", modelId: "glm-5.2", displayName: "GLM 5.2", addedAt: "2026-01-01T00:00:00.000Z" },
+        ],
+      });
+      const custom = models.find(m => m.provider === "text-sidecar-provider" && m.id === "glm-5.2");
+      expect(custom).toBeDefined();
+      expect(custom?.inputModalities).toEqual(["text", "image"]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      clearModelCache("text-sidecar-provider");
+    }
+  });
 });
 
 describe("vision-capable provider models feed combo modalities", () => {
@@ -258,6 +325,31 @@ describe("vision-capable provider models feed combo modalities", () => {
     const hinted = applyProviderConfigHints("xai", prov, { provider: "xai", id: "grok-4.5" });
     expect(hinted.inputModalities).toEqual(["text", "image"]);
   });
+
+  test("a combo of modelInputModalities-declared text-only members advertises image through the hints", () => {
+    // End-to-end shape of the /planners bug: every member is sidecar-covered via
+    // modelInputModalities (not noVisionModels). The hinted members all carry image, so the
+    // derived combo keeps image input instead of collapsing to text-only.
+    const memberFor = (provider: string, id: string): CatalogModel => applyProviderConfigHints(provider, {
+      adapter: "openai-chat",
+      baseUrl: `https://${provider}.example/v1`,
+      modelInputModalities: { [id]: ["text"] },
+    }, { id, provider, contextWindow: 200_000 });
+    const memberA = memberFor("azu-lab2", "deepseek-chat");
+    const memberB = memberFor("vdi", "glm-5.2");
+    const derived = deriveComboCatalogModel(
+      "planners",
+      {
+        targets: [
+          { provider: "azu-lab2", model: "deepseek-chat" },
+          { provider: "vdi", model: "glm-5.2" },
+        ],
+        defaultEffort: "high",
+      } as never,
+      [memberA, memberB],
+    );
+    expect(derived?.inputModalities).toEqual(["text", "image"]);
+  });
 });
 
 describe("Cursor native vs sidecar vision registry", () => {

tests/codex-catalog.test.ts

@@ -1061,7 +1061,9 @@ describe("combo catalog capability intersection", () => {
           liveModels: false,
           models: ["m2"],
           modelContextWindows: { m2: 128_000 },
-          modelInputModalities: { m2: ["text"] },
+          // No declaration: text-only by catalog default, NOT sidecar-covered. A declared
+          // text-only member would widen to image (isModelTextOnly parity) and the pair
+          // would no longer be disjoint.
         },
       },
       combos: {
@@ -1202,7 +1204,9 @@ describe("combo catalog capability intersection", () => {
       contextWindow: 128_000,
       contextCapped: false,
       maxInputTokens: 100_000,
-      inputModalities: ["text"],
+      // The text-only modelInputModalities declaration is sidecar-covered at runtime
+      // (isModelTextOnly), so the combo advertises image input like its member does.
+      inputModalities: ["text", "image"],
       reasoningEfforts: ["high"],
     });
     expect(rows.find(row => row.provider === "combo" && row.id === "nova-sol"))
@@ -1515,7 +1519,7 @@ describe("combo catalog capability intersection", () => {
           liveModels: false,
           models: ["m1"],
           modelContextWindows: { m1: 128_000 },
-          // Disjoint modalities with b → empty intersection (incompatible_modalities).
+          // Image-only member. An image-only declaration is not sidecar-covered.
           modelInputModalities: { m1: ["image"] },
         },
         b: {
@@ -1524,7 +1528,10 @@ describe("combo catalog capability intersection", () => {
           liveModels: false,
           models: ["m2"],
           modelContextWindows: { m2: 128_000 },
-          modelInputModalities: { m2: ["audio"] },
+          // No modality declaration: the member is text-only by catalog default and the
+          // sidecar does not cover it, so text and image stay genuinely disjoint
+          // (incompatible_modalities). A DECLARED text-only member would be widened to
+          // image (isModelTextOnly parity) and no longer be disjoint.
         },
       },
       combos: {
@@ -5185,7 +5192,9 @@ describe("Codex catalog routed normalization", () => {
     expect(models.find(m => m.id === "wide-model")).toMatchObject({
       contextWindow: 100_000,
       maxInputTokens: 100_000,
-      inputModalities: ["text"],
+      // Declared text-only modalities are sidecar-covered at runtime (isModelTextOnly),
+      // so the catalog advertises image on top of the configured base.
+      inputModalities: ["text", "image"],
     });
     expect(models.find(m => m.id === "small-model")?.contextWindow).toBe(64_000);
   });