feat(vision): add chat and Google sidecars

gui/src/i18n/de.ts

@@ -287,6 +287,7 @@ export const de: Record<TKey, string> = {
   "dash.backendAuto": "Automatisch",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Chat API",
   "dash.sidecarSaved": "Sidecar-Einstellungen gespeichert. Angewendet bei der nächsten Anfrage.",
   "dash.sidecarSaveFailed": "Sidecar-Einstellungen konnten nicht gespeichert werden.",
   "dash.injectionLabel": "Sub-Agent-Delegation",

gui/src/i18n/en.ts

@@ -305,6 +305,7 @@ export const en = {
   "dash.backendAuto": "Auto",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Chat API",
   "dash.sidecarSaved": "Sidecar settings saved. Applied on the next request.",
   "dash.sidecarSaveFailed": "Failed to save sidecar settings.",
   "dash.injectionLabel": "Sub-agent delegation",

gui/src/i18n/ja.ts

@@ -296,6 +296,7 @@ export const ja: Record<TKey, string> = {
   "dash.backendAuto": "自動",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Chat API",
   "dash.sidecarSaved": "サイドカー設定を保存しました。次回リクエスト時に適用されます。",
   "dash.sidecarSaveFailed": "サイドカー設定の保存に失敗しました。",
   "dash.injectionLabel": "サブエージェント委任",

gui/src/i18n/ko.ts

@@ -291,6 +291,7 @@ export const ko: Record<TKey, string> = {
   "dash.backendAuto": "자동",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Chat API",
   "dash.sidecarSaved": "사이드카 설정이 저장됐습니다. 다음 요청부터 적용됩니다.",
   "dash.sidecarSaveFailed": "사이드카 설정 저장에 실패했습니다.",
   "dash.injectionLabel": "서브에이전트 위임",

gui/src/i18n/ru.ts

@@ -296,6 +296,7 @@ export const ru: Record<TKey, string> = {
   "dash.backendAuto": "Авто",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Chat API",
   "dash.sidecarSaved": "Настройки сайдкара сохранены. Вступят в силу со следующего запроса.",
   "dash.sidecarSaveFailed": "Не удалось сохранить настройки сайдкара.",
   "dash.injectionLabel": "Делегирование подагентам",

gui/src/i18n/tr.ts

@@ -297,6 +297,7 @@ export const tr: Record<TKey, string> = {
   "dash.backendAuto": "Otomatik",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Sohbet API",
   "dash.sidecarSaved": "Yan araç ayarları kaydedildi. Sonraki istekte uygulanacak.",
   "dash.sidecarSaveFailed": "Yan araç ayarları kaydedilemedi.",
   "dash.injectionLabel": "Alt ajan devri",

gui/src/i18n/zh-TW.ts

@@ -190,6 +190,7 @@ export const zhTW: Record<TKey, string> = {
   "dash.backendAuto": "自動",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "聊天 API",
   "dash.sidecarSaved": "附屬設定已儲存。將在下一個請求時生效。",
   "dash.sidecarSaveFailed": "儲存附屬設定失敗。",
   "dash.injectionLabel": "子代理委託",

gui/src/i18n/zh.ts

@@ -291,6 +291,7 @@ export const zh: Record<TKey, string> = {
   "dash.backendAuto": "自动",
   "dash.backendOpenAI": "OpenAI",
   "dash.backendAnthropic": "Anthropic",
+  "dash.backendChat": "Chat API",
   "dash.sidecarSaved": "附属设置已保存。将在下一个请求时生效。",
   "dash.sidecarSaveFailed": "保存附属设置失败。",
   "dash.injectionLabel": "子代理委托",

gui/src/pages/claude-code-sections.tsx

@@ -170,6 +170,7 @@ export function ClaudeCodeSettingsCard({
                   { value: "auto", label: t("dash.backendAuto") },
                   { value: "openai", label: t("dash.backendOpenAI") },
                   { value: "anthropic", label: t("dash.backendAnthropic") },
+                  ...(key === "visionSidecar" ? [{ value: "chat", label: t("dash.backendChat") }] : []),
                 ]}
                 onChange={value => {
                   // Auto may exist as an empty in-memory draft so the model input

gui/src/pages/claude-manual-env.ts

@@ -4,7 +4,7 @@
  * copy-paste shell block is directly unit-testable (tests/claude-manual-env.test.ts).
  */
 
-export type SidecarBackend = "openai" | "anthropic";
+export type SidecarBackend = "openai" | "anthropic" | "chat";
 export interface SidecarOverride { backend?: SidecarBackend; model?: string }
 
 export interface ClaudeManualEnvState {

gui/src/pages/dashboard-overview-sections.tsx

@@ -515,7 +515,11 @@ export function DashboardSidecarPanels({ d }: { d: Dash }) {
             <Select
               value={sidecar?.webSearch.model ?? "gpt-5.6-luna"}
               options={sidecarModels}
-              onChange={model => { void saveSidecar({ webSearch: { model, backend: sidecarBackendForModel(models, model) } }); }}
+              onChange={model => {
+                const backend = sidecarBackendForModel(models, model);
+                const webSearchBackend = backend === "openai" || backend === "anthropic" ? backend : undefined;
+                void saveSidecar({ webSearch: { model, ...(webSearchBackend ? { backend: webSearchBackend } : {}) } });
+              }}
               disabled={!sidecar || sidecarSaving}
               label={t("dash.sidecarModel")}
               align="right"
@@ -555,7 +559,8 @@ export function DashboardSidecarPanels({ d }: { d: Dash }) {
                   }
                   const ladder = visionReasoningLadder(models, model);
                   const reasoning = clampVisionReasoningToLadder(ladder, visionReasoning);
-                  const patch: SidecarPatch = { vision: { model, backend: visionSidecarBackendForModel(models, visionModels, model), reasoning } };
+                  const backend = visionSidecarBackendForModel(models, visionModels, model);
+                  const patch: SidecarPatch = { vision: { model, ...(backend === "unresolved" ? {} : { backend }), reasoning } };
                   // Choosing a model is the activation control: turning Vision back on from Off.
                   if (!visionEnabled) patch.vision = { ...patch.vision, enabled: true };
                   void saveSidecar(patch);

gui/src/pages/dashboard-shared.ts

@@ -59,10 +59,12 @@ export interface SettingsData {
     diagnosticStale: boolean;
   };
 }
-export type SidecarBackend = "openai" | "anthropic";
+export type SidecarBackend = "openai" | "anthropic" | "chat";
+/** Web-search sidecars accept only OpenAI/Anthropic — `chat` is vision-only. */
+export type WebSearchBackend = "openai" | "anthropic";
 export type VisionReasoning = "low" | "medium" | "high" | "xhigh" | "max";
-export interface SidecarSetting {
-  backend?: SidecarBackend;
+export interface SidecarSetting<B extends SidecarBackend = SidecarBackend> {
+  backend?: B;
   model: string;
   reasoning?: VisionReasoning;
   streamRoutedModelOutput?: boolean;
@@ -72,15 +74,15 @@ export interface SidecarSetting {
 }
 export interface VisionModelOption { value: string; label: string; backend: SidecarBackend; baseline?: boolean }
 export interface SidecarData {
-  webSearch: SidecarSetting;
+  webSearch: SidecarSetting<WebSearchBackend>;
   vision: SidecarSetting;
   /** Server-computed eligible describers. Optional: an older server omits it and
    *  the client falls back to the legacy provider-name list rather than showing
    *  an empty picker. */
   visionModels?: VisionModelOption[];
 }
 export interface SidecarPatch {
-  webSearch?: { backend?: SidecarBackend | null; model?: string; streamRoutedModelOutput?: boolean };
+  webSearch?: { backend?: WebSearchBackend | null; model?: string; streamRoutedModelOutput?: boolean };
   vision?: {
     backend?: SidecarBackend | null;
     model?: string;
@@ -169,18 +171,18 @@ export function updateJobLabel(status: UpdateJobStatus, t: (key: TKey) => string
   }
 }
 
-export function mergeSidecarSetting(
-  current: SidecarSetting,
+export function mergeSidecarSetting<B extends SidecarBackend = SidecarBackend>(
+  current: SidecarSetting<B>,
   update?: {
-    backend?: SidecarBackend | null;
+    backend?: B | null;
     model?: string;
     reasoning?: VisionReasoning;
     streamRoutedModelOutput?: boolean;
     enabled?: boolean;
     maxDescriptionsPerTurn?: number;
     timeoutMs?: number;
   },
-): SidecarSetting {
+): SidecarSetting<B> {
   const merged = { ...current };
   if (update?.model !== undefined) merged.model = update.model;
   if (update?.backend === null) delete merged.backend;
@@ -317,16 +319,30 @@ export function shadowCallModelOptions(models: ModelInfo[], current: string | un
   return out;
 }
 
-export function sidecarBackendForModel(models: ModelInfo[], modelId: string): SidecarBackend {
-  return models.find(model => model.id === modelId)?.provider === "anthropic" ? "anthropic" : "openai";
+export type SidecarBackendResolution = SidecarBackend | "unresolved";
+
+export function sidecarBackendForModel(models: ModelInfo[], modelId: string): SidecarBackendResolution {
+  // Exact namespaced matches win; otherwise a bare id must match EXACTLY one
+  // catalog row. Ambiguity (two providers exposing the same bare id) is an
+  // unresolved state, never a guessed first match — persisting the wrong
+  // backend would route images to the wrong provider.
+  const qualifiedMatches = models.filter(item => item.namespaced === modelId);
+  const matches = qualifiedMatches.length > 0
+    ? qualifiedMatches
+    : models.filter(item => item.id === modelId);
+  const model = matches[0];
+  if (matches.length !== 1 || !model) return "unresolved";
+  if (model.provider === "anthropic") return "anthropic";
+  if (model.provider === "openai") return "openai";
+  return "chat";
 }
 
 /** Server eligibility is authoritative; catalog inference only supports legacy picker entries. */
 export function visionSidecarBackendForModel(
   models: ModelInfo[],
   options: Array<{ value: string; backend?: SidecarBackend }>,
   modelId: string,
-): SidecarBackend {
+): SidecarBackendResolution {
   return options.find(option => option.value === modelId)?.backend ?? sidecarBackendForModel(models, modelId);
 }
 

gui/tests/vision-model-options.test.ts

@@ -68,9 +68,11 @@ test("a server-supplied vision backend wins when the catalog cannot identify its
     { value: model, label: model, backend: "anthropic" },
   ], [], undefined);
 
-  // This documents the old save-path result: catalog inference alone defaults
-  // to OpenAI when there is no matching model row.
-  expect(sidecarBackendForModel([], model)).toBe("openai");
+  // Catalog inference alone cannot name a backend for an unknown model: an
+  // unresolved result must never be silently mislabelled "chat" (or "openai"),
+  // because the save path would then persist a backend for a model it never
+  // resolved. The server-supplied option carries the real backend instead.
+  expect(sidecarBackendForModel([], model)).toBe("unresolved");
   expect(visionSidecarBackendForModel([], options, model)).toBe("anthropic");
 });
 
@@ -83,7 +85,9 @@ test("an older server with no option list cannot rewrite the persisted anthropic
 
   expect(options[0]).toMatchObject({ value: model, backend: "anthropic" });
   expect(visionSidecarBackendForModel([], options, model)).toBe("anthropic");
-  expect(sidecarBackendForModel([], model)).toBe("openai");
+  // The unresolved fallback exists precisely so this compatibility path cannot
+  // silently downgrade the persisted backend to a guessed one.
+  expect(sidecarBackendForModel([], model)).toBe("unresolved");
 });
 
 test("an authoritative empty list still keeps the configured model and its backend", () => {
@@ -95,3 +99,16 @@ test("an authoritative empty list still keeps the configured model and its backe
   expect(options.map(option => option.value)).toEqual([model]);
   expect(visionSidecarBackendForModel([], options, model)).toBe("anthropic");
 });
+
+test("an ambiguous bare id shared by two providers is unresolved, not a first-match guess", () => {
+  // Two catalog rows expose the same bare id under different namespaces. The
+  // old `find` took the first row and could persist the wrong backend; the
+  // contract is that ambiguity stays unresolved.
+  const shared: ModelInfo[] = [
+    { id: "shared", provider: "openai", namespaced: "openai/shared" },
+    { id: "shared", provider: "anthropic", namespaced: "anthropic/shared" },
+  ];
+  expect(sidecarBackendForModel(shared, "shared")).toBe("unresolved");
+  // An exact namespaced id still resolves deterministically.
+  expect(sidecarBackendForModel(shared, "anthropic/shared")).toBe("anthropic");
+});

src/cli/agent.ts

@@ -20,7 +20,8 @@ const USAGE = `Usage:
   ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
   ocx agent subagents <status|set|clear> [model,model...] [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
-  ocx agent sidecar <status|web|vision> [--model <id|->] [--backend <openai|anthropic|->]
+  ocx agent sidecar <status|web|vision> [--model <id|->] [--backend <openai|anthropic|chat|->]
+      (web backend: openai|anthropic; vision backend: openai|anthropic|chat)
       [--reasoning <level>] [--max-descriptions <n>] [--json]`;
 
 function clearable(value: string | undefined): string | null | undefined {

src/cli/integrations.ts

@@ -19,7 +19,7 @@ const CLAUDE_USAGE = `Usage:
       [--compact-window <tokens|default>] [--inject-agents <on|off>]
       [--small-fast-model <id|->] [--model-map <from=to,from=to|->]
       [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|->]
-      [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]`;
+      [--vision-model <id|->] [--vision-backend <openai|anthropic|chat|->] [--json]`;
 
 const GROK_USAGE = `Usage:
   ocx grok [status] [--json]

src/server/management/agent-settings-routes.ts

@@ -1030,8 +1030,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       if (section === undefined || section === null) continue;
       if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
       if (section.backend !== undefined && section.backend !== null
-        && section.backend !== "openai" && section.backend !== "anthropic") {
-        return jsonResponse({ error: `${field}.backend must be openai, anthropic, or null` }, 400);
+        && section.backend !== "openai" && section.backend !== "anthropic" && (field !== "visionSidecar" || section.backend !== "chat")) {
+        const accepted = field === "visionSidecar" ? "openai, anthropic, chat, or null" : "openai, anthropic, or null";
+        return jsonResponse({ error: `${field}.backend must be ${accepted}` }, 400);
       }
       if (section.model !== undefined && typeof section.model !== "string") {
         return jsonResponse({ error: `${field}.model must be a string` }, 400);
@@ -1058,8 +1059,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         delete next[field];
         continue;
       }
-      const requested = section as { backend?: "openai" | "anthropic" | null; model?: string };
-      const override: NonNullable<OcxClaudeCodeConfig[typeof field]> = { ...next[field] };
+      const requested = section as { backend?: "openai" | "anthropic" | "chat" | null; model?: string };
+      const override = { ...(next[field] as Record<string, unknown> | undefined) } as Record<string, unknown>;
       if (requested.backend === null) delete override.backend;
       else if (requested.backend !== undefined) override.backend = requested.backend;
       if (requested.model === "") delete override.model;

src/server/management/config-routes.ts

@@ -471,8 +471,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       return jsonResponse({ error: "webSearch.streamRoutedModelOutput must be a boolean" }, 400);
     }
     if (body.vision && body.vision.backend !== undefined
-      && body.vision.backend !== null && body.vision.backend !== "openai" && body.vision.backend !== "anthropic") {
-      return jsonResponse({ error: "vision.backend must be openai, anthropic, or null" }, 400);
+      && body.vision.backend !== null && body.vision.backend !== "openai" && body.vision.backend !== "anthropic" && body.vision.backend !== "chat") {
+      return jsonResponse({ error: "vision.backend must be openai, anthropic, chat, or null" }, 400);
     }
     if (body.vision && body.vision.maxDescriptionsPerTurn !== undefined
       && (typeof body.vision.maxDescriptionsPerTurn !== "number"
@@ -544,7 +544,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         else config.visionSidecar.model = body.vision.model;
       }
       if (body.vision.backend === null) delete config.visionSidecar.backend;
-      else if (body.vision.backend === "openai" || body.vision.backend === "anthropic") {
+      else if (body.vision.backend === "openai" || body.vision.backend === "anthropic" || body.vision.backend === "chat") {
         config.visionSidecar.backend = body.vision.backend;
       }
       if (typeof body.vision.maxDescriptionsPerTurn === "number") {

src/server/management/vision-sidecar-options.ts

@@ -20,7 +20,8 @@ import { listOpenAiForwardSidecarCandidates } from "../../providers/openai-sidec
 import { listManagementModelRows } from "./model-rows";
 
 /**
- * Backends whose executor could actually run: openai forward, anthropic OAuth.
+ * Backends whose executor could actually run: openai forward, anthropic OAuth,
+ * chat/google provider with usable auth.
  *
  * `anthropicSidecar` is REQUIRED rather than defaulted. `findAnthropicVisionProvider`
  * reads the OAuth account store from disk, and a default argument made every helper
@@ -36,11 +37,26 @@ export function enabledVisionBackends(
   // provider keyed "openai" — same predicate the runtime sidecar resolver uses.
   if (listOpenAiForwardSidecarCandidates(config).length > 0) backends.push("openai");
   if (anthropicSidecar) backends.push("anthropic");
+  // The chat describer needs a configured openai-chat/google provider with usable
+  // auth — same predicate the runtime chat sidecar resolver uses.
+  if (hasUsableChatVisionProvider(config)) backends.push("chat");
   // Neither side resolvable (fresh install, no login): fall back to both so the
   // picker is populated rather than empty, matching the permissive-unknown rule.
   return backends.length > 0 ? backends : ["openai", "anthropic"];
 }
 
+/** Any enabled openai-chat/google provider the chat sidecar could actually dispatch through. */
+function hasUsableChatVisionProvider(config: OcxConfig): boolean {
+  for (const provider of Object.values(config.providers ?? {})) {
+    if (provider.disabled === true) continue;
+    const chatLike = provider.adapter === "openai-chat" || provider.adapter === "google";
+    if (!chatLike) continue;
+    if (provider.apiKey ?? provider.apiKeyPool?.[0]?.key) return true;
+    if (provider.authMode === "oauth") return true;
+  }
+  return false;
+}
+
 /** Visible catalog rows in the shape the eligibility predicate consumes. */
 export async function visionCandidateRows(config: OcxConfig): Promise<VisionCandidateModel[]> {
   let rows: Awaited<ReturnType<typeof listManagementModelRows>> = [];

src/types.ts

@@ -517,7 +517,7 @@ export interface OcxClaudeCodeConfig {
   /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
   webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
   /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
-  visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
+  visionSidecar?: { backend?: "openai" | "anthropic" | "chat"; model?: string };
   /** Persisted Claude Desktop four-family routing profile. */
   desktopProfile?: OcxClaudeDesktopProfile;
   /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
@@ -1129,7 +1129,7 @@ export interface OcxVisionSidecarConfig {
   /** Master switch. Default: enabled when the selected backend has a usable credential. */
   enabled?: boolean;
   /** Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI. */
-  backend?: "openai" | "anthropic";
+  backend?: "openai" | "anthropic" | "chat";
   /** Vision model that describes images. */
   model?: string;
   /** Max description cache misses admitted in one main-model turn. Zero disables description calls. */