From 1f45cf885c698b74f561ef0bf444a77ec0975365 Mon Sep 17 00:00:00 2001
From: rinseaid <richardjhunt@gmail.com>
Date: Tue, 11 Aug 2026 03:30:10 -0400
Subject: [PATCH] fix(vision): preserve images for text-only routes (#9037)

* fix(vision): preserve images for text-only routes

* fix(i18n): complete Vietnamese vision bridge copy

* fix(ci): drain prerelease tag input

---------

Co-authored-by: rinseaid <rinseaid@rinseaid.net>
---
 scripts/ci/should-promote-latest.sh           |  3 +
 .../ModalityBridgeVisionTab.tsx               |  9 +++
 src/i18n/messages/en.json                     |  2 +
 src/i18n/messages/pt-BR.json                  |  2 +
 src/i18n/messages/vi.json                     |  2 +
 src/lib/guardrails/visionBridge.ts            |  9 ++-
 src/shared/constants/visionBridgeDefaults.ts  |  3 +
 src/shared/validation/settingsSchemas.ts      |  1 +
 tests/unit/guardrails/visionBridge.test.ts    | 40 ++++++++++++
 .../unit/ui/visionBridgeSettingsTab.test.tsx  | 64 +++++++++++++++++++
 tests/unit/visionBridgeDefaults.test.ts       |  1 +
 11 files changed, 134 insertions(+), 2 deletions(-)
 create mode 100644 tests/unit/ui/visionBridgeSettingsTab.test.tsx

diff --git a/scripts/ci/should-promote-latest.sh b/scripts/ci/should-promote-latest.sh
index e118086c88..e1e9745782 100755
--- a/scripts/ci/should-promote-latest.sh
+++ b/scripts/ci/should-promote-latest.sh
@@ -26,6 +26,9 @@ VERSION="${1:?version required}"
 # `main` and `next`, plus every pre-release identifier, fail closed here even if
 # a caller forgets to short-circuit them first.
 if ! printf '%s' "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  # Consume the caller's tag stream before exiting. A pre-release decision is
+  # immediate, but closing stdin early can give a piped producer EPIPE.
+  cat >/dev/null
   echo "false"
   exit 0
 fi
diff --git a/src/app/(dashboard)/dashboard/settings/components/modalityBridge/ModalityBridgeVisionTab.tsx b/src/app/(dashboard)/dashboard/settings/components/modalityBridge/ModalityBridgeVisionTab.tsx
index 9079578bbb..55a2a78591 100644
--- a/src/app/(dashboard)/dashboard/settings/components/modalityBridge/ModalityBridgeVisionTab.tsx
+++ b/src/app/(dashboard)/dashboard/settings/components/modalityBridge/ModalityBridgeVisionTab.tsx
@@ -19,6 +19,7 @@ interface VisionState {
   modalityBridgeVisionMode: VisionBridgeMode;
   modalityBridgeVisionModel: string;
   modalityBridgeVisionTaskAware: boolean;
+  visionBridgeRerouteTextOnly: boolean;
   modalityBridgeVisionPrompt: string;
   modalityBridgeVisionTimeout: number;
   modalityBridgeVisionMaxImages: number;
@@ -34,6 +35,7 @@ function fromApi(data: Record<string, unknown>): VisionState {
     modalityBridgeVisionMode: runtime.mode,
     modalityBridgeVisionModel: runtime.model,
     modalityBridgeVisionTaskAware: runtime.taskAware,
+    visionBridgeRerouteTextOnly: data.visionBridgeRerouteTextOnly === true,
     modalityBridgeVisionPrompt: runtime.prompt,
     modalityBridgeVisionTimeout: runtime.timeoutMs,
     modalityBridgeVisionMaxImages: runtime.maxImages,
@@ -119,6 +121,13 @@ export default function ModalityBridgeVisionTab() {
           description={t("visionBridgeEnabledDesc")}
         />
 
+        <Toggle
+          checked={settings.visionBridgeRerouteTextOnly}
+          onChange={(checked) => void update({ visionBridgeRerouteTextOnly: checked })}
+          label={t("visionBridgeRerouteTextOnlyLabel")}
+          description={t("visionBridgeRerouteTextOnlyDesc")}
+        />
+
         <div>
           <label className="text-sm font-medium" htmlFor="modality-bridge-mode">
             {t("modalityBridgeMode")}
diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json
index 775be32a19..5c93cde028 100644
--- a/src/i18n/messages/en.json
+++ b/src/i18n/messages/en.json
@@ -7250,6 +7250,8 @@
     "visionBridgeDesc": "Run an automatic vision-to-text fallback before routing image requests to text-only models.",
     "visionBridgeEnabledLabel": "Enabled",
     "visionBridgeEnabledDesc": "Toggle the pre-call bridge that replaces image parts with extracted text.",
+    "visionBridgeRerouteTextOnlyLabel": "Reroute text-only models",
+    "visionBridgeRerouteTextOnlyDesc": "Send the complete request, including images, to the bridge model when the selected model has no image input.",
     "visionBridgeModel": "Bridge Model",
     "visionBridgeModelPlaceholder": "openai/gpt-4o-mini",
     "visionBridgeModelHint": "Any OmniRoute model ID that supports vision can be used here.",
diff --git a/src/i18n/messages/pt-BR.json b/src/i18n/messages/pt-BR.json
index 8c81d1acbd..fe5e5b7048 100644
--- a/src/i18n/messages/pt-BR.json
+++ b/src/i18n/messages/pt-BR.json
@@ -7237,6 +7237,8 @@
     "visionBridgeDesc": "Executa um fallback automático de visão para texto antes de rotear solicitações de imagem para modelos que aceitam apenas texto.",
     "visionBridgeEnabledLabel": "Ativado",
     "visionBridgeEnabledDesc": "Ativa a ponte pré-chamada que substitui partes de imagem pelo texto extraído.",
+    "visionBridgeRerouteTextOnlyLabel": "Redirecionar modelos somente de texto",
+    "visionBridgeRerouteTextOnlyDesc": "Envia a solicitação completa, incluindo imagens, ao modelo de ponte quando o modelo selecionado não aceita entrada de imagem.",
     "visionBridgeModel": "Modelo de ponte",
     "visionBridgeModelPlaceholder": "openai/gpt-4o-mini",
     "visionBridgeModelHint": "Qualquer ID de modelo OmniRoute que suporte visão pode ser usado aqui.",
diff --git a/src/i18n/messages/vi.json b/src/i18n/messages/vi.json
index 38db83b8c3..f89774945b 100644
--- a/src/i18n/messages/vi.json
+++ b/src/i18n/messages/vi.json
@@ -7231,6 +7231,8 @@
     "visionBridgeDesc": "Tự động chạy phương án dự phòng chuyển đổi hình ảnh sang văn bản trước khi định tuyến các yêu cầu hình ảnh đến các mô hình chỉ hỗ trợ văn bản.",
     "visionBridgeEnabledLabel": "Đã bật",
     "visionBridgeEnabledDesc": "Bật/tắt cầu nối trước cuộc gọi để thay thế các phần hình ảnh bằng văn bản được trích xuất.",
+    "visionBridgeRerouteTextOnlyLabel": "Định tuyến lại các mô hình chỉ có văn bản",
+    "visionBridgeRerouteTextOnlyDesc": "Gửi yêu cầu hoàn chỉnh, bao gồm hình ảnh, tới mô hình cầu nối khi mô hình được chọn không hỗ trợ đầu vào hình ảnh.",
     "visionBridgeModel": "Mô hình cầu nối",
     "visionBridgeModelPlaceholder": "openai/gpt-4o-mini",
     "visionBridgeModelHint": "Có thể sử dụng bất kỳ ID mô hình OmniRoute nào hỗ trợ xử lý hình ảnh ở đây.",
diff --git a/src/lib/guardrails/visionBridge.ts b/src/lib/guardrails/visionBridge.ts
index bc7f7efd86..82c751c65d 100644
--- a/src/lib/guardrails/visionBridge.ts
+++ b/src/lib/guardrails/visionBridge.ts
@@ -258,8 +258,13 @@ export class VisionBridgeGuardrail extends BaseGuardrail {
     // request with model=auto would land on a text-only model (#7871). Keeping
     // "auto" is never the answer there, so the keep-credentialed-model skip
     // below does not apply to auto — only the reroute-target credential guard.
+    const rerouteTextOnly = settings.visionBridgeRerouteTextOnly === true;
+    // Reroute when the operator opted in to direct VLM routing for every text-only
+    // route (keeps image bytes instead of a lossy bridge description), or when the
+    // auto heuristic deems the request eligible.
     const rerouteEligible =
-      (comboVisionBridgeDecision === "not-combo" || isAuto) && !forceVisionBridge;
+      rerouteTextOnly ||
+      ((comboVisionBridgeDecision === "not-combo" || isAuto) && !forceVisionBridge);
     // Forced modes short-circuit BEFORE the auto heuristic (#6640/#7204 untouched):
     // - "describe" skips the whole reroute block → straight to the describe path.
     // - "reroute" skips only the keep-credentialed-model guard; the reroute-target
@@ -269,7 +274,7 @@ export class VisionBridgeGuardrail extends BaseGuardrail {
       const checkCreds = this.deps.hasUsableCredentials ?? hasUsableCredentialsForModel;
       const originalUsable = runtime.mode === "reroute" ? false : await checkCreds(model);
 
-      if (originalUsable === true && !isAuto) {
+      if (originalUsable === true && !isAuto && !rerouteTextOnly) {
         // Keep the credentialed model; describe images below if needed.
         context.log?.debug?.(
           "VISION_BRIDGE",
diff --git a/src/shared/constants/visionBridgeDefaults.ts b/src/shared/constants/visionBridgeDefaults.ts
index 869e4dee8f..967aa42b8f 100644
--- a/src/shared/constants/visionBridgeDefaults.ts
+++ b/src/shared/constants/visionBridgeDefaults.ts
@@ -53,6 +53,7 @@ export const VISION_BRIDGE_SETTINGS_KEYS = [
   "visionBridgePrompt",
   "visionBridgeTimeout",
   "visionBridgeMaxImages",
+  "visionBridgeRerouteTextOnly",
 ] as const;
 
 export type VisionBridgeSettings = {
@@ -61,6 +62,8 @@ export type VisionBridgeSettings = {
   visionBridgePrompt?: string;
   visionBridgeTimeout?: number;
   visionBridgeMaxImages?: number;
+  /** Route text-only image requests to the configured VLM instead of describing them. */
+  visionBridgeRerouteTextOnly?: boolean;
 };
 
 export type VisionBridgeConfig = {
diff --git a/src/shared/validation/settingsSchemas.ts b/src/shared/validation/settingsSchemas.ts
index 32a2d1cebb..57598774bd 100644
--- a/src/shared/validation/settingsSchemas.ts
+++ b/src/shared/validation/settingsSchemas.ts
@@ -347,6 +347,7 @@ export const updateSettingsSchema = z.object({
   modalityBridgeCacheEnabled: z.boolean().optional(),
   modalityBridgeCacheTtlMinutes: z.number().int().min(1).max(1440).optional(),
   modalityBridgeCacheMaxEntries: z.number().int().min(10).max(5000).optional(),
+  visionBridgeRerouteTextOnly: z.boolean().optional(),
   // Missing settings
   lkgpEnabled: z.boolean().optional(),
   // #1311: echo the requested alias/combo name in the response model field (opt-in)
diff --git a/tests/unit/guardrails/visionBridge.test.ts b/tests/unit/guardrails/visionBridge.test.ts
index d5dc848881..64a2b3a40b 100644
--- a/tests/unit/guardrails/visionBridge.test.ts
+++ b/tests/unit/guardrails/visionBridge.test.ts
@@ -761,6 +761,46 @@ test("VB-CRED-01: does NOT whole-request-reroute when original model has usable
   assert.notStrictEqual(meta?.rerouted, true, "must not set rerouted meta for credentialed model");
 });
 
+test("VB-CRED-01A: reroutes a credentialed text-only model when configured to preserve images", async () => {
+  mockSettings.visionBridgeRerouteTextOnly = true;
+  const guardrail = createGuardrail({
+    deps: {
+      hasUsableCredentials: async (m: string) =>
+        m === "zai/glm-5.2" || m === "openai/gpt-4o-mini" ? true : null,
+    },
+  });
+
+  const payload = createPayload({
+    model: "zai/glm-5.2",
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "What is in this screenshot?" },
+          {
+            type: "image_url",
+            image_url: { url: "https://example.com/shot.png" },
+          },
+        ],
+      },
+    ],
+  });
+
+  const result = await guardrail.preCall(payload, createContext({ model: "zai/glm-5.2" }));
+  assert.strictEqual(result.block, false);
+
+  const modified = result.modifiedPayload as {
+    model?: string;
+    messages: Array<{ content: Array<{ type: string; image_url?: { url: string } }> }>;
+  };
+  assert.strictEqual(modified.model, "openai/gpt-4o-mini");
+  assert.deepStrictEqual(modified.messages[0].content[1], {
+    type: "image_url",
+    image_url: { url: "https://example.com/shot.png" },
+  });
+  assert.strictEqual(visionCallCount, 0, "the bridge must not replace the image with text");
+});
+
 test("VB-CRED-02: does NOT reroute to a vision model known to lack credentials", async () => {
   mockSettings.visionBridgeModel = "opencode-zen/gpt-5.4";
   const guardrail = createGuardrail({
diff --git a/tests/unit/ui/visionBridgeSettingsTab.test.tsx b/tests/unit/ui/visionBridgeSettingsTab.test.tsx
new file mode 100644
index 0000000000..6cb85a6318
--- /dev/null
+++ b/tests/unit/ui/visionBridgeSettingsTab.test.tsx
@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import ModalityBridgeVisionTab from "@/app/(dashboard)/dashboard/settings/components/modalityBridge/ModalityBridgeVisionTab";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key }));
+
+function jsonResponse(data: unknown) {
+  return { ok: true, json: async () => data } as Response;
+}
+
+describe("VisionBridgeSettingsTab (Modality Bridge vision tab)", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  const fetchMock = vi.fn();
+
+  beforeEach(async () => {
+    (
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = true;
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.includes("/api/models")) {
+        return jsonResponse({ models: [] });
+      }
+      if (url.includes("/api/modality-bridge/stats")) {
+        return jsonResponse({ vision: { bridged: 0, cacheHits: 0, failures: 0 }, audio: {} });
+      }
+      if (init?.method === "PATCH") return jsonResponse({});
+      return jsonResponse({});
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    await act(async () => {
+      root.render(<ModalityBridgeVisionTab />);
+    });
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it("exposes the text-only reroute setting and persists a toggle", async () => {
+    expect(container.textContent).toContain("visionBridgeRerouteTextOnlyLabel");
+    const toggles = container.querySelectorAll('[role="switch"]');
+    const rerouteToggle = toggles.item(1) as HTMLButtonElement;
+    await act(async () => {
+      rerouteToggle.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/settings",
+      expect.objectContaining({
+        method: "PATCH",
+        body: JSON.stringify({ visionBridgeRerouteTextOnly: true }),
+      })
+    );
+  });
+});
diff --git a/tests/unit/visionBridgeDefaults.test.ts b/tests/unit/visionBridgeDefaults.test.ts
index 690da33c0d..f5cbf9bfdc 100644
--- a/tests/unit/visionBridgeDefaults.test.ts
+++ b/tests/unit/visionBridgeDefaults.test.ts
@@ -30,6 +30,7 @@ test("VISION_BRIDGE_SETTINGS_KEYS exports all expected keys", () => {
     "visionBridgePrompt",
     "visionBridgeTimeout",
     "visionBridgeMaxImages",
+    "visionBridgeRerouteTextOnly",
   ]);
 });