npm - @bitkyc08/opencodex - Versions diffs - 2.7.9-preview.20260712.2 → 2.7.9 - Mend

@bitkyc08/opencodex 2.7.9-preview.20260712.2 → 2.7.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/gui/dist/assets/index-BAAFKwsh.js +40 -0
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/bridge.ts +6 -2
package/src/claude/outbound.ts +77 -5
package/src/oauth/index.ts +9 -7
package/src/providers/registry.ts +5 -0
package/src/providers/xai-transport.ts +89 -0
package/src/server/claude-messages.ts +25 -1
package/src/server/management-api.ts +99 -10
package/src/server/responses.ts +16 -8
package/src/types.ts +17 -2
package/src/vision/anthropic-describe.ts +185 -0
package/src/vision/index.ts +219 -10
package/src/web-search/anthropic-executor.ts +187 -0
package/src/web-search/executor.ts +4 -2
package/src/web-search/index.ts +80 -18
package/src/web-search/loop.ts +14 -2
package/gui/dist/assets/index-SnN_1Qr9.js +0 -40

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-SnN_1Qr9.js"></script>
+    <script type="module" crossorigin src="/assets/index-BAAFKwsh.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Cq8maiJf.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.7.9-preview.20260712.2",
+  "version": "2.7.9",
   "description": "Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI/App/SDK",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/bridge.ts CHANGED Viewed

@@ -379,11 +379,14 @@ export function bridgeToResponsesSSE(
       // Finalize an open web-search cell. `status` is "completed" on a normal end, or "failed" when
       // the stream terminates (error/incomplete) while a search was still in flight, so Codex never
       // leaves a "Searching the web" spinner spinning forever.
-      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[]) => {
+      // `sources` rides on the done item (additive field; codex-rs serde ignores unknown fields) so
+      // downstream translators (claude outbound) can fill web_search_tool_result content.
+      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[]) => {
         if (!currentWebSearch) return;
         const item = {
           type: "web_search_call", id: currentWebSearch.itemId, status,
           action: webSearchAction(queries),
+          ...(sources && sources.length > 0 ? { sources } : {}),
         };
         emit("response.output_item.done", { output_index: currentWebSearch.outputIndex, item });
         finishedItems.push(item as OutputItem);
@@ -569,7 +572,7 @@ export function bridgeToResponsesSSE(
                 });
                 currentWebSearch = { itemId: event.id, outputIndex };
               }
-              closeCurrentWebSearch(event.status ?? "completed", event.queries);
+              closeCurrentWebSearch(event.status ?? "completed", event.queries, event.sources);
               // Queue this search's sources for the next assistant message (dedup by URL).
               if (event.sources) {
                 const seen = new Set(pendingWebSources.map(s => s.url));
@@ -861,6 +864,7 @@ export function buildResponseJSON(
         output.push({
           type: "web_search_call", id: e.id, status: e.status ?? "completed",
           action: webSearchAction(e.queries),
+          ...(e.sources && e.sources.length > 0 ? { sources: e.sources } : {}),
         });
         if (e.sources) {
           const seen = new Set(pendingWebSources.map(s => s.url));

package/src/claude/outbound.ts CHANGED Viewed

@@ -54,7 +54,7 @@ export function anthropicErrorResponse(status: number, message: string, type?: s
  * subtract the full cache detail (devlog 070 — subtracting reads only inflated the
  * non-cached input Claude Code displays by the write share).
  */
-export function anthropicUsage(usage: unknown): Rec {
+export function anthropicUsage(usage: unknown, webSearchRequests = 0): Rec {
   const u = isRec(usage) ? usage : {};
   const details = isRec(u.input_tokens_details) ? u.input_tokens_details : {};
   const cached = typeof details.cached_tokens === "number" ? details.cached_tokens : 0;
@@ -66,6 +66,8 @@ export function anthropicUsage(usage: unknown): Rec {
     output_tokens: output,
     cache_read_input_tokens: cached,
     cache_creation_input_tokens: cacheWrite,
+    // Only successful searches are billed/counted (Anthropic contract; Claude Code cost accounting).
+    ...(webSearchRequests > 0 ? { server_tool_use: { web_search_requests: webSearchRequests } } : {}),
   };
 }
@@ -73,6 +75,37 @@ function sseFrame(name: string, data: Rec): string {
   return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
 }
+/**
+ * Map a Responses `web_search_call` item to its Anthropic pair: the server_tool_use
+ * input (query/queries) and the web_search_tool_result content (hits, or the error
+ * object when the search failed). Shared by the SSE and JSON translation paths.
+ */
+function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
+  const action = isRec(item.action) ? item.action : {};
+  const queries = Array.isArray(action.queries)
+    ? action.queries.filter((q): q is string => typeof q === "string" && q.length > 0)
+    : [];
+  const query = typeof action.query === "string" ? action.query : "";
+  const input: Rec = queries.length > 1 ? { queries } : { query: queries[0] ?? query };
+  const completed = item.status !== "failed";
+  let resultContent: unknown;
+  if (completed) {
+    const hits: Rec[] = [];
+    if (Array.isArray(item.sources)) {
+      for (const s of item.sources) {
+        if (isRec(s) && typeof s.url === "string" && s.url.length > 0) {
+          hits.push({ type: "web_search_result", title: typeof s.title === "string" ? s.title : "", url: s.url });
+        }
+      }
+    }
+    resultContent = hits;
+  } else {
+    resultContent = { type: "web_search_tool_result_error", error_code: "unavailable" };
+  }
+  const id = typeof item.id === "string" && item.id.length > 0 ? item.id : `srvtoolu_${uuid()}`;
+  return { id, input, resultContent, completed };
+}
 function messageSnapshot(model: string): Rec {
   return {
     id: `msg_${uuid()}`,
@@ -109,6 +142,7 @@ export function responsesSseToAnthropicSse(
   let blockIndex = 0;
   let open: OpenBlock | null = null;
   let sawToolUse = false;
+  let webSearchRequests = 0;
   let pingTimer: ReturnType<typeof setInterval> | undefined;
   let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
@@ -164,7 +198,7 @@ export function responsesSseToAnthropicSse(
         emit("message_delta", {
           type: "message_delta",
           delta: { stop_reason: stopReason, stop_sequence: null },
-          usage: anthropicUsage(usage),
+          usage: anthropicUsage(usage, webSearchRequests),
         });
         emit("message_stop", { type: "message_stop" });
       };
@@ -234,7 +268,35 @@ export function responsesSseToAnthropicSse(
           }
           case "response.output_item.done": {
             const item = isRec(data.item) ? data.item : null;
-            if (!open || !item) break;
+            if (!item) break;
+            // Server-side web search (native passthrough or sidecar bridge): translate the
+            // finished call into the Anthropic pair Claude Code natively parses —
+            // server_tool_use (query via input_json_delta) + web_search_tool_result.
+            // Never marks sawToolUse (stop_reason stays end_turn unless a real tool ran).
+            if (item.type === "web_search_call") {
+              ensureStarted();
+              closeOpenBlock();
+              const pair = webSearchPairFromItem(item);
+              const toolIndex = blockIndex++;
+              emit("content_block_start", {
+                type: "content_block_start", index: toolIndex,
+                content_block: { type: "server_tool_use", id: pair.id, name: "web_search" },
+              });
+              emit("content_block_delta", {
+                type: "content_block_delta", index: toolIndex,
+                delta: { type: "input_json_delta", partial_json: JSON.stringify(pair.input) },
+              });
+              emit("content_block_stop", { type: "content_block_stop", index: toolIndex });
+              const resultIndex = blockIndex++;
+              emit("content_block_start", {
+                type: "content_block_start", index: resultIndex,
+                content_block: { type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent },
+              });
+              emit("content_block_stop", { type: "content_block_stop", index: resultIndex });
+              if (pair.completed) webSearchRequests++;
+              break;
+            }
+            if (!open) break;
             // Close the matching open block (message/reasoning items close implicitly on
             // the next block; function_call items must close here so tool input parses).
             if (open.kind === "tool_use" && item.type === "function_call") closeOpenBlock();
@@ -322,6 +384,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
   const output = Array.isArray(body.output) ? body.output : [];
   const content: Rec[] = [];
   let sawToolUse = false;
+  let webSearchRequests = 0;
   for (const raw of output) {
     if (!isRec(raw)) continue;
@@ -366,6 +429,14 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
         });
         break;
       }
+      case "web_search_call": {
+        // Server-side search: emit the Anthropic pair. Does NOT set sawToolUse.
+        const pair = webSearchPairFromItem(raw);
+        content.push({ type: "server_tool_use", id: pair.id, name: "web_search", input: pair.input });
+        content.push({ type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent });
+        if (pair.completed) webSearchRequests++;
+        break;
+      }
       default:
         break;
     }
@@ -384,7 +455,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
     model,
     stop_reason: stopReason,
     stop_sequence: null,
-    usage: anthropicUsage(body.usage),
+    usage: anthropicUsage(body.usage, webSearchRequests),
   };
 }
@@ -407,7 +478,8 @@ export async function collectAnthropicMessage(stream: ReadableStream<Uint8Array>
   const closeBlock = () => {
     if (!openBlock) return;
-    if (openBlock.type === "tool_use") {
+    // server_tool_use streams its query via input_json_delta exactly like tool_use (audit F3).
+    if (openBlock.type === "tool_use" || openBlock.type === "server_tool_use") {
       try { openBlock.input = toolJson.length > 0 ? JSON.parse(toolJson) : {}; } catch { openBlock.input = {}; }
     }
     content.push(openBlock);

package/src/oauth/index.ts CHANGED Viewed

@@ -12,6 +12,7 @@ import { loginAntigravity, refreshAntigravityToken } from "./google-antigravity"
 import { loginCursor, refreshCursorToken } from "./cursor";
 import { deriveOAuthDefaultModel, deriveOAuthProviderConfig } from "../providers/derive";
 import { effectiveGoogleMode } from "../providers/registry";
+import { resolveProviderTransport } from "../providers/xai-transport";
 const REFRESH_SKEW_MS = 60_000;
 const tokenRefreshes = new Map<string, Promise<string>>();
@@ -254,27 +255,28 @@ export async function resolveModelsAuthToken(name: string, prov: OcxProviderConf
  * response.
  */
 export function buildModelsRequest(prov: OcxProviderConfig, apiKey: string | undefined, providerName = ""): { url: string; headers: Record<string, string> } {
-  const headers: Record<string, string> = { ...(prov.headers ?? {}) };
-  if (effectiveGoogleMode(providerName, prov) === "ai-studio") {
+  const effectiveProvider = resolveProviderTransport(providerName, prov);
+  const headers: Record<string, string> = { ...(effectiveProvider.headers ?? {}) };
+  if (effectiveGoogleMode(providerName, effectiveProvider) === "ai-studio") {
     // Generative Language API: API key goes in x-goog-api-key (never Authorization: Bearer),
     // models live under /v1beta (v1 misses preview models), and pageSize maxes at 1000 —
     // enough to list everything without a pageToken loop. Vertex/antigravity keep the
     // generic branch (they fall back to their static model lists).
     if (apiKey) headers["x-goog-api-key"] = apiKey;
-    return { url: `${prov.baseUrl}/v1beta/models?pageSize=1000`, headers };
+    return { url: `${effectiveProvider.baseUrl}/v1beta/models?pageSize=1000`, headers };
   }
-  if (prov.adapter === "anthropic") {
+  if (effectiveProvider.adapter === "anthropic") {
     headers["anthropic-version"] = "2023-06-01";
-    if (prov.authMode === "oauth") {
+    if (effectiveProvider.authMode === "oauth") {
       headers["anthropic-beta"] = ANTHROPIC_OAUTH_BETA;
       if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
     } else if (apiKey) {
       headers["x-api-key"] = apiKey;
     }
-    return { url: `${prov.baseUrl}/v1/models?limit=1000`, headers };
+    return { url: `${effectiveProvider.baseUrl}/v1/models?limit=1000`, headers };
   }
   if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
-  return { url: `${prov.baseUrl}/models`, headers };
+  return { url: `${effectiveProvider.baseUrl}/models`, headers };
 }
 /**

package/src/providers/registry.ts CHANGED Viewed

@@ -236,6 +236,11 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     models: ["grok-4.5", "grok-4.3", "grok-4.20-multi-agent-0309", "grok-4.20-0309-reasoning", "grok-4.20-0309-non-reasoning", "grok-build-0.1", "grok-composer-2.5-fast"],
     defaultModel: "grok-4.5",
     noReasoningModels: ["grok-4.20-0309-non-reasoning", "grok-build-0.1", "grok-composer-2.5-fast"],
+    // Replay assistant reasoning_content for grok reasoning models: xAI documents dropped
+    // reasoning_content as the top cause of prompt-cache misses on multi-turn conversations
+    // (docs.x.ai prompt-caching/multi-turn, verified 2026-07-13 — devlog/_plan/260713_grok_caching).
+    // Models that never emit reasoning simply have no thinking parts to replay (no-op).
+    preserveReasoningContentModels: ["grok-4.5", "grok-4.3", "grok-4.20-multi-agent-0309", "grok-4.20-0309-reasoning"],
     // grok-4.5 reasoning is always-on with low/medium/high control (no off tier upstream).
     modelReasoningEfforts: { "grok-4.5": ["low", "medium", "high"] },
     modelContextWindows: {

package/src/providers/xai-transport.ts ADDED Viewed

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
+/**
+ * xAI account OAuth and xAI API keys share a bearer shape but not a billing
+ * transport. OAuth represents the Grok CLI subscription entitlement, while a
+ * key represents the API team. Keep the saved provider preset compatible with
+ * the dashboard's "Use an API key instead" switch and resolve the transport at
+ * request time.
+ */
+export const XAI_GROK_CLI_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+/** Minimum-compatible official Grok CLI wire version verified with the proxy. */
+export const XAI_GROK_CLIENT_VERSION = "0.2.93";
+const XAI_GROK_CLI_HEADERS: Readonly<Record<string, string>> = {
+  "x-grok-client-identifier": "opencodex",
+  "x-grok-client-version": XAI_GROK_CLIENT_VERSION,
+  "x-xai-token-auth": "xai-grok-cli",
+};
+/**
+ * Sticky-routing hint for xAI's automatic prefix cache. xAI routes requests
+ * carrying the same `x-grok-conv-id` to the same server, which is where the
+ * prompt cache lives (docs.x.ai prompt-caching best-practices; verified
+ * 2026-07-13, devlog/_plan/260713_grok_caching). Codex clients send a stable
+ * per-conversation `prompt_cache_key`; hash it so the raw session id never
+ * leaves the proxy.
+ */
+export const XAI_CONV_ID_HEADER = "x-grok-conv-id";
+function hasHeaderCaseInsensitive(headers: Record<string, string> | undefined, name: string): boolean {
+  if (!headers) return false;
+  const target = name.toLowerCase();
+  return Object.keys(headers).some(key => key.toLowerCase() === target);
+}
+/** Drop default entries the user already overrides under any header-name casing. */
+function withoutUserOverridden(defaults: Readonly<Record<string, string>>, userHeaders: Record<string, string> | undefined): Record<string, string> {
+  if (!userHeaders) return { ...defaults };
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(defaults)) {
+    if (!hasHeaderCaseInsensitive(userHeaders, key)) out[key] = value;
+  }
+  return out;
+}
+export function deriveXaiConvId(promptCacheKey: string): string {
+  return createHash("sha256").update(promptCacheKey).digest("hex").slice(0, 32);
+}
+/**
+ * Resolve the effective xAI transport without mutating persisted config.
+ * User-provided headers are preserved and may advance the compatibility
+ * version without waiting for an opencodex release.
+ *
+ * `promptCacheKey` (the client's stable conversation key) additionally pins
+ * cache-affinity routing via `x-grok-conv-id` in BOTH auth modes. Blank or
+ * whitespace-only keys are ignored so unrelated requests can never collapse
+ * onto one shared conv id, and any user-configured header (any case) wins.
+ */
+export function resolveProviderTransport(
+  providerName: string,
+  provider: OcxProviderConfig,
+  promptCacheKey?: string,
+): OcxProviderConfig {
+  if (providerName !== "xai") return provider;
+  const cacheKey = promptCacheKey?.trim();
+  const convIdHeaders: Record<string, string> =
+    cacheKey && !hasHeaderCaseInsensitive(provider.headers, XAI_CONV_ID_HEADER)
+      ? { [XAI_CONV_ID_HEADER]: deriveXaiConvId(cacheKey) }
+      : {};
+  if (provider.authMode !== "oauth") {
+    if (Object.keys(convIdHeaders).length === 0) return provider;
+    return {
+      ...provider,
+      headers: { ...convIdHeaders, ...(provider.headers ?? {}) },
+    };
+  }
+  return {
+    ...provider,
+    baseUrl: XAI_GROK_CLI_BASE_URL,
+    headers: {
+      ...withoutUserOverridden(XAI_GROK_CLI_HEADERS, provider.headers),
+      ...convIdHeaders,
+      ...(provider.headers ?? {}),
+    },
+  };
+}

package/src/server/claude-messages.ts CHANGED Viewed

@@ -31,6 +31,21 @@ function isRec(v: unknown): v is Rec {
   return !!v && typeof v === "object" && !Array.isArray(v);
 }
+/** Resolve Claude-only sidecar overrides without mutating the shared server config. */
+export function buildClaudeReplayConfig(config: OcxConfig): OcxConfig {
+  return {
+    ...config,
+    webSearchSidecar: {
+      ...config.webSearchSidecar,
+      ...config.claudeCode?.webSearchSidecar,
+    },
+    visionSidecar: {
+      ...config.visionSidecar,
+      ...config.claudeCode?.visionSidecar,
+    },
+  };
+}
 function claudeInboundDisabled(config: OcxConfig): Response | null {
   if (config.claudeCode?.enabled === false) {
     return anthropicErrorResponse(403, "Claude inbound is disabled (GUI: Claude ON toggle / config.claudeCode.enabled)", "permission_error");
@@ -332,6 +347,15 @@ export async function handleClaudeMessages(
     const value = req.headers.get(name);
     if (value) headers.set(name, value);
   }
+  if (!nativeRoute) {
+    // Routed replays need main ChatGPT auth so OpenAI-backed sidecars remain reachable.
+    const { getMainAccountToken } = await import("../codex/main-account");
+    const token = getMainAccountToken();
+    if (token) {
+      headers.set("authorization", `Bearer ${token.accessToken}`);
+      headers.set("chatgpt-account-id", token.chatgptAccountId);
+    }
+  }
   if (nativeRoute) {
     // No forwarded ChatGPT auth exists on this surface. Attach the main codex login
     // (read-only auth.json token); account-pool rotation still overrides downstream.
@@ -368,7 +392,7 @@ export async function handleClaudeMessages(
     nativeLogged = true;
     addFinalRequestLog(logIds.requestId, logIds.start, logCtx, status, meta);
   };
-  const upstream = await handleResponses(internalReq, config, logCtx, {
+  const upstream = await handleResponses(internalReq, buildClaudeReplayConfig(config), logCtx, {
     abortSignal: req.signal,
     onNativePassthroughTerminal: status => finalizeNativeLog(httpStatusForTerminalStatus(status), { terminalStatus: status, closeReason: "terminal" }),
     onNativePassthroughCancel: () => finalizeNativeLog(499, { closeReason: "client_cancel" }),

package/src/server/management-api.ts CHANGED Viewed

@@ -37,7 +37,7 @@ import {
   setDebugSettings,
   type DebugFlag,
 } from "../lib/debug-settings";
-import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { OcxClaudeCodeConfig, OcxConfig, OcxProviderConfig } from "../types";
 import { drainAndShutdown } from "./lifecycle";
 import { filterRequestLogs, getRequestLogEntries } from "./request-log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "./auth-cors";
@@ -58,6 +58,11 @@ export interface ManagementApiDeps {
   refreshCodexCatalog?: () => Promise<void>;
 }
+/** Narrow an unknown JSON value to a plain (non-array) object for strict request-body validation. */
+function isPlainRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 function parseDebugLogQuery(url: URL): { after: number; limit: number } {
   const after = Number(url.searchParams.get("after") ?? url.searchParams.get("since") ?? "0");
   const limit = Number(url.searchParams.get("limit") ?? "500");
@@ -193,30 +198,78 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     const ws = config.webSearchSidecar ?? {};
     const vs = config.visionSidecar ?? {};
     return jsonResponse({
-      webSearch: { model: ws.model ?? "gpt-5.6-luna", reasoning: ws.reasoning ?? "low" },
-      vision: { model: vs.model ?? "gpt-5.6-luna" },
+      webSearch: { model: ws.model ?? "gpt-5.6-luna", backend: ws.backend },
+      vision: {
+        model: vs.model ?? "gpt-5.6-luna",
+        backend: vs.backend,
+        maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
+      },
     });
   }
   if (url.pathname === "/api/sidecar-settings" && req.method === "PUT") {
-    let body: { webSearch?: { model?: string; reasoning?: string }; vision?: { model?: string } };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    let raw: unknown;
+    try { raw = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    // Strict shape (review F2): reject non-object bodies and non-object sections instead of throwing
+    // on `null` or silently accepting arrays/strings as no-op updates.
+    if (!isPlainRecord(raw)) return jsonResponse({ error: "body must be a JSON object" }, 400);
+    if (raw.webSearch !== undefined && !isPlainRecord(raw.webSearch)) return jsonResponse({ error: "webSearch must be an object" }, 400);
+    if (raw.vision !== undefined && !isPlainRecord(raw.vision)) return jsonResponse({ error: "vision must be an object" }, 400);
+    const body = raw as {
+      webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown };
+      vision?: { model?: unknown; backend?: unknown; maxDescriptionsPerTurn?: unknown };
+    };
+    if (body.webSearch && body.webSearch.backend !== undefined && body.webSearch.backend !== null
+      && body.webSearch.backend !== "openai" && body.webSearch.backend !== "anthropic") {
+      return jsonResponse({ error: "webSearch.backend must be openai, anthropic, or null" }, 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);
+    }
+    if (body.vision && body.vision.maxDescriptionsPerTurn !== undefined
+      && (typeof body.vision.maxDescriptionsPerTurn !== "number"
+        || !Number.isInteger(body.vision.maxDescriptionsPerTurn)
+        || body.vision.maxDescriptionsPerTurn <= 0)) {
+      return jsonResponse({ error: "vision.maxDescriptionsPerTurn must be a positive integer" }, 400);
+    }
     if (body.webSearch) {
       config.webSearchSidecar = { ...config.webSearchSidecar };
-      if (typeof body.webSearch.model === "string") config.webSearchSidecar.model = body.webSearch.model;
+      if (typeof body.webSearch.model === "string") {
+        if (body.webSearch.model === "") delete config.webSearchSidecar.model;
+        else config.webSearchSidecar.model = body.webSearch.model;
+      }
+      if (body.webSearch.backend === null) delete config.webSearchSidecar.backend;
+      else if (body.webSearch.backend === "openai" || body.webSearch.backend === "anthropic") {
+        config.webSearchSidecar.backend = body.webSearch.backend;
+      }
       if (typeof body.webSearch.reasoning === "string") config.webSearchSidecar.reasoning = body.webSearch.reasoning;
     }
     if (body.vision) {
       config.visionSidecar = { ...config.visionSidecar };
-      if (typeof body.vision.model === "string") config.visionSidecar.model = body.vision.model;
+      if (typeof body.vision.model === "string") {
+        if (body.vision.model === "") delete config.visionSidecar.model;
+        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") {
+        config.visionSidecar.backend = body.vision.backend;
+      }
+      if (typeof body.vision.maxDescriptionsPerTurn === "number") {
+        config.visionSidecar.maxDescriptionsPerTurn = body.vision.maxDescriptionsPerTurn;
+      }
     }
     saveConfig(config);
     const ws = config.webSearchSidecar ?? {};
     const vs = config.visionSidecar ?? {};
     return jsonResponse({
       ok: true,
-      webSearch: { model: ws.model ?? "gpt-5.6-luna", reasoning: ws.reasoning ?? "low" },
-      vision: { model: vs.model ?? "gpt-5.6-luna" },
+      webSearch: { model: ws.model ?? "gpt-5.6-luna", backend: ws.backend },
+      vision: {
+        model: vs.model ?? "gpt-5.6-luna",
+        backend: vs.backend,
+        maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
+      },
     });
   }
@@ -707,6 +760,8 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       aliases.push({ id: claudeCodeAlias(m.provider, m.id), display_name: `${m.id} (${m.provider})` });
     }
     const contextWindows = buildClaudeContextWindows([...visibleNativeSlugs(config)], models);
+    const webSearchOverride = config.claudeCode?.webSearchSidecar;
+    const visionOverride = config.claudeCode?.visionSidecar;
     return jsonResponse({
       enabled: config.claudeCode?.enabled !== false,
       model: config.claudeCode?.model ?? "",
@@ -720,6 +775,12 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       autoCompactWindow: config.claudeCode?.autoCompactWindow ?? null,
       blockedSkills: config.claudeCode?.blockedSkills ?? null,
       injectAgents: config.claudeCode?.injectAgents !== false,
+      ...(webSearchOverride && Object.keys(webSearchOverride).length > 0
+        ? { webSearchSidecar: { backend: webSearchOverride.backend, model: webSearchOverride.model } }
+        : {}),
+      ...(visionOverride && Object.keys(visionOverride).length > 0
+        ? { visionSidecar: { backend: visionOverride.backend, model: visionOverride.model } }
+        : {}),
       fastMode: config.fastMode,
       contextWindows,
       effectiveModelEnv: effectiveModelEnv(config.claudeCode, contextWindows),
@@ -743,8 +804,36 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       return prototype === Object.prototype || prototype === null;
     };
     if (!isPlainObject(parsedBody)) return jsonResponse({ error: "body must be an object" }, 400);
-    const body = parsedBody as { enabled?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; blockedSkills?: unknown; injectAgents?: unknown };
+    const body = parsedBody as { enabled?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; blockedSkills?: unknown; injectAgents?: unknown; webSearchSidecar?: unknown; visionSidecar?: unknown };
+    for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
+      const section = body[field];
+      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);
+      }
+      if (section.model !== undefined && typeof section.model !== "string") {
+        return jsonResponse({ error: `${field}.model must be a string` }, 400);
+      }
+    }
     const next = { ...(config.claudeCode ?? {}) };
+    for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
+      const section = body[field];
+      if (section === undefined) continue;
+      if (section === null || Object.keys(section as Record<string, unknown>).length === 0) {
+        delete next[field];
+        continue;
+      }
+      const requested = section as { backend?: "openai" | "anthropic" | null; model?: string };
+      const override: NonNullable<OcxClaudeCodeConfig[typeof field]> = { ...next[field] };
+      if (requested.backend === null) delete override.backend;
+      else if (requested.backend !== undefined) override.backend = requested.backend;
+      if (requested.model === "") delete override.model;
+      else if (requested.model !== undefined) override.model = requested.model;
+      if (Object.keys(override).length > 0) next[field] = override;
+      else delete next[field];
+    }
     if (body.enabled !== undefined) {
       if (typeof body.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
       next.enabled = body.enabled;

package/src/server/responses.ts CHANGED Viewed

@@ -41,6 +41,7 @@ import { isUsageDebugEnabled } from "../usage/debug";
 import { readJsonRequestBody, DecompressedBodyTooLargeError, UnsupportedContentEncodingError } from "./request-decompress";
 import { resolveAdapter, resolveWireProtocolOverride } from "./adapter-resolve";
 import { hasKeyPoolFailover, rotateKeyOn429 } from "../providers/key-failover";
+import { resolveProviderTransport } from "../providers/xai-transport";
 import type { WsData } from "./ws-bridge";
 import { registerTurn, trackStreamLifetime, unregisterTurn } from "./lifecycle";
 import { redactSecretString } from "../lib/redact";
@@ -612,14 +613,15 @@ export async function handleResponses(
       return formatErrorResponse(401, "authentication_error", err instanceof Error ? err.message : String(err));
     }
   }
+  route.provider = resolveProviderTransport(route.providerName, route.provider, parsed.options.promptCacheKey);
-  // Vision sidecar: the routed model can't see images (provider.noVisionModels). Give it "eyes" —
-  // describe each attached image with a gpt vision model via the ChatGPT passthrough and replace it
-  // with text BEFORE the main call, so the text-only model can reason about it.
+  // Vision sidecar: the routed model can't see images (provider.noVisionModels). Describe each
+  // attached image through the selected sidecar backend and replace it with text BEFORE the main
+  // call, so the text-only model can reason about it.
   const visionPlan = planVisionSidecar(config, route.provider, route.modelId, parsed, selectedForwardHeaders, authCtx);
   const recordSidecarOutcome = sidecarOutcomeRecorder(config, authCtx);
   if (visionPlan) {
-    await describeImagesInPlace(parsed, visionPlan.forwardProvider, selectedForwardHeaders, visionPlan.settings, options.abortSignal, recordSidecarOutcome);
+    await describeImagesInPlace(parsed, visionPlan, selectedForwardHeaders, options.abortSignal, recordSidecarOutcome);
   } else if (modelInList(route.provider.noVisionModels, route.modelId)) {
     // Sidecar-covered model but NO plan (no forward provider / missing forwarded auth / sidecar
     // disabled): fail closed — never forward raw images to a text-only upstream.
@@ -870,7 +872,9 @@ export async function handleResponses(
     parsed.context.tools = [...(parsed.context.tools ?? []), buildWebSearchTool()];
     const wsResponse = await runWithWebSearch({
       parsed, adapter,
+      backend: wsPlan.backend,
       forwardProvider: wsPlan.forwardProvider,
+      anthropicSidecar: wsPlan.anthropicSidecar,
       hostedTool: wsPlan.hostedTool,
       selectedForwardHeaders,
       settings: wsPlan.settings,
@@ -884,9 +888,11 @@ export async function handleResponses(
       on429: retryAfter => {
         const rotated = rotateKeyOn429(config, route.providerName, retryAfter, Date.now(), route.provider.apiKey);
         if (!rotated) return null;
-        route.provider = rotated;
+        // Re-resolve the auth-mode transport so the conv-id / subscription headers derived at
+        // line ~616 survive the key rotation (rotated providers come from raw config).
+        route.provider = resolveProviderTransport(route.providerName, rotated, parsed.options.promptCacheKey);
         return resolveAdapter(
-          resolveWireProtocolOverride(route.providerName, route.modelId, rotated),
+          resolveWireProtocolOverride(route.providerName, route.modelId, route.provider),
           config.cacheRetention,
         );
       },
@@ -940,9 +946,11 @@ export async function handleResponses(
       // Release the failed response's socket before retrying; unread bodies otherwise linger
       // until runtime cleanup (one per rotated key under a rate-limit storm).
       try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
-      route.provider = rotated;
+      // Same transport re-resolution as the streaming on429 path: keep conv-id + subscription
+      // headers on the retried request instead of silently reverting to the raw config provider.
+      route.provider = resolveProviderTransport(route.providerName, rotated, parsed.options.promptCacheKey);
       const retryAdapter = resolveAdapter(
-        resolveWireProtocolOverride(route.providerName, route.modelId, rotated),
+        resolveWireProtocolOverride(route.providerName, route.modelId, route.provider),
         config.cacheRetention,
       );
       const retryRequest = await retryAdapter.buildRequest(parsed, { headers: selectedForwardHeaders });