@bitkyc08/opencodex 2.29.0 → 2.31.0-preview.20260822

package/src/adapters/cursor/request-builder.ts

@@ -31,6 +31,7 @@ import {
   type CursorCheckpointInvalidationReason,
   type CursorCheckpointSnapshot,
 } from "./checkpoint-store";
+import { extractCursorImageUrls } from "./images";
 
 /** Probe-verified Cursor Connect boundaries, with byte headroom for the enclosing field. */
 export const CURSOR_TOOL_COUNT_LIMIT = 330;
@@ -211,15 +212,8 @@ function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): stri
     case "thinking":
       return part.thinking;
     case "image":
-      // User-message images are still flattened here: this path builds the plain-text prompt, and
-      // the schema slot that could carry them (UserMessage.selectedContext.selectedImages) is not
-      // populated by this adapter. The tool-result ENCODER does build real McpImageContent
-      // (see protobuf-request.ts), so the old "unsupported by Cursor adapter" wording is no
-      // longer true of the encoder — but note that nothing reaches Cursor today either way:
-      // every Cursor model is in noVisionModels (providers/registry.ts), so the vision sidecar
-      // describes or strips images before this adapter runs. Kept the same length to avoid
-      // shifting any byte-budgeted prompt path.
-      return `[image omitted from this Cursor text prompt: ${part.detail ?? "auto"}]`;
+      // Images ride UserMessage.selected_context (SelectedImage) instead of text.
+      return undefined;
     case "toolCall":
       // Cursor does not accept OpenAI Responses assistant tool-call parts as native history here.
       // Rendering them as visible "[tool_call]" text leaks synthetic protocol markers back into
@@ -252,9 +246,19 @@ function requestMessage(message: OcxMessage): CursorRequestMessage | undefined {
   switch (message.role) {
     case "user":
     case "developer":
-      return { role: message.role, content: contentToText(message.content) };
+      {
+        const content = contentToText(message.content);
+        // Image-only turns survive as empty content; the encoder keeps them userMessageAction.
+        if (content.length === 0 && extractCursorImageUrls(message.content).length === 0) {
+          return undefined;
+        }
+        return { role: message.role, content };
+      }
     case "assistant":
-      return { role: "assistant", content: contentToText(message.content) };
+      {
+        const content = contentToText(message.content);
+        return content.length > 0 ? { role: "assistant", content } : undefined;
+      }
     case "toolResult":
       return {
         role: "tool",
@@ -263,6 +267,19 @@ function requestMessage(message: OcxMessage): CursorRequestMessage | undefined {
   }
 }
 
+/**
+ * Rebuild the text `messages` channel from prepared `rawMessages` so omission markers
+ * and JPEG-rewritten parts stay visible to activePromptText after image preparation.
+ */
+export function cursorRequestMessagesFromRaw(
+  messages: readonly OcxMessage[] | undefined,
+): CursorRequestMessage[] {
+  if (!messages?.length) return [];
+  return messages
+    .map(requestMessage)
+    .filter((message): message is CursorRequestMessage => !!message);
+}
+
 export function generatedCursorConversationId(): string {
   return `cursor_${crypto.randomUUID().replace(/-/g, "")}`;
 }
@@ -409,9 +426,7 @@ export function createCursorRequest(
   parsed: OcxParsedRequest,
   options: CreateCursorRequestOptions = {},
 ): CursorRunRequest {
-  const messages = parsed.context.messages
-    .map(requestMessage)
-    .filter((message): message is CursorRequestMessage => !!message && message.content.length > 0);
+  const messages = cursorRequestMessagesFromRaw(parsed.context.messages);
   const activeText = [...messages].reverse().find(message => message.role === "user" || message.role === "developer")?.content ?? "";
   const visibleTools = cursorToolsForActivePrompt(parsed.context.tools, activeText, parsed.options.toolChoice);
   const budget = applyCursorToolBudget(visibleTools, parsed.options.toolChoice);

package/src/adapters/cursor/tool-definitions.ts

@@ -336,6 +336,26 @@ export function normalizeCursorWireName(name: string): string {
   return name.startsWith(CURSOR_MCP_DISPLAY_PREFIX) ? name.slice(CURSOR_MCP_DISPLAY_PREFIX.length) : name;
 }
 
+/**
+ * #2305: some models emit a TEXTUAL pseudo tool call ("[TOOL_CALL]name[ARGS]{...}")
+ * instead of a real frame, using Cursor's display alias as the name. Text-mode clients
+ * (Pi) parse that text and then cannot dispatch the undeclared display name. Rewrite the
+ * display alias to the advertised wire name ONLY inside the marker pair — prose that
+ * merely mentions the alias stays untouched, and the scope guard is the exact
+ * `mcp_${OCX_RESPONSES_TOOL_PROVIDER}_` prefix, never generic `mcp_`.
+ * Known limit (recorded in devlog 230): a marker split across two streaming deltas is
+ * not rewritten; tail-buffering is deferred until a live trace shows split markers.
+ */
+const CURSOR_TEXT_TOOL_MARKER = new RegExp(
+  String.raw`\[TOOL_CALL\](${CURSOR_MCP_DISPLAY_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\[\]]+)\[ARGS\]`,
+  "g",
+);
+
+export function normalizeCursorTextToolMarkers(text: string): string {
+  if (!text.includes(CURSOR_MCP_DISPLAY_PREFIX)) return text;
+  return text.replace(CURSOR_TEXT_TOOL_MARKER, (_match, name: string) => `[TOOL_CALL]${normalizeCursorWireName(name)}[ARGS]`);
+}
+
 export function responsesToolNameFromCursorWire(name: string, cursorToolNameMap?: ReadonlyMap<string, string>): string {
   const normalized = normalizeCursorWireName(name);
   if (!cursorToolNameMap) return normalized;

package/src/adapters/cursor/transport.ts

@@ -29,6 +29,16 @@ export interface CursorTransportFactoryInput {
   firstFrameTimeoutMs?: number;
   /** Grace (ms) between close() and the force-destroy fallback after a first-frame timeout. Defaults to 1s. */
   timeoutDestroyGraceMs?: number;
+  /**
+   * T04 watchdog: maximum inbound decoded-frame silence (ms) after the first frame before the
+   * turn is failed. Defaults to 30s.
+   */
+  streamSilenceFailMs?: number;
+  /**
+   * T04 watchdog: maximum heartbeat/checkpoint-only traffic (ms) without turn progress before
+   * the turn is failed. Defaults to 90s.
+   */
+  streamHeartbeatOnlyFailMs?: number;
   /**
    * Grace window (ms) before a drained client-tool turn is finalized, so a sibling tool call
    * announced in a later receive chunk can revoke a premature finalize. Defaults to 50ms.

package/src/adapters/cursor/types.ts

@@ -2,6 +2,7 @@ import type { OcxUsage } from "../../types";
 import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
 import type { CursorRoutingLevel } from "./discovery";
 import type { CursorCheckpointInvalidationReason } from "./checkpoint-store";
+import type { ResolvedCursorImage } from "./images";
 
 export interface CursorRequestedModelParameter {
   id: string;
@@ -17,7 +18,13 @@ export interface CursorRunRequest {
   conversationId: string;
   system: string[];
   messages: CursorRequestMessage[];
-  rawMessages?: OcxMessage[];
+  rawMessages?: readonly OcxMessage[];
+  /**
+   * Images for the active user/developer turn. Encoded as SelectedImage blobIdWithData refs under
+   * UserMessage.selected_context (bytes live in the request-scoped KV store for getBlobArgs
+   * hydration). History stays text-only. data: URLs only in this slice.
+   */
+  selectedImages?: readonly ResolvedCursorImage[];
   tools?: OcxTool[];
   toolChoice?: OcxRequestOptions["toolChoice"];
   parallelToolCalls?: boolean;

package/src/adapters/cursor.ts

@@ -3,8 +3,8 @@ import type { AdapterEvent, OcxProviderConfig } from "../types";
 import type { ProviderAdapter } from "./base";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
 import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
-import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage } from "./cursor/cursor-errors";
-import { cursorCheckpointModelAffinityId, isCursorExternalWireModel } from "./cursor/discovery";
+import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage, type CursorSizeContext } from "./cursor/cursor-errors";
+import { cursorCheckpointModelAffinityId, inferCursorContextWindow, isCursorExternalWireModel } from "./cursor/discovery";
 import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
 import {
@@ -25,6 +25,7 @@ import {
   invalidateCursorCheckpoint,
 } from "./cursor/checkpoint-store";
 import { debugProviderDiagnostic } from "../lib/debug";
+import { estimateTokens } from "../lib/token-estimate";
 import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
 import { runCursorTurnWithRetry } from "./cursor/transport-retry";
 import {
@@ -53,16 +54,29 @@ export interface CursorAdapterDeps {
   rekeyContextUsage?: (fromConversationId: string, toConversationId: string) => void;
 }
 
-function safeCursorTransportError(err: unknown): string {
+function safeCursorTransportError(err: unknown, sizeContext?: CursorSizeContext): string {
   if (err instanceof CursorTransportDisabledError) return CURSOR_TRANSPORT_DISABLED_MESSAGE;
   if (err instanceof CursorMissingCredentialError) {
     return "Cursor live transport is enabled, but no Cursor access token is configured. Set provider.apiKey or OPENCODEX_CURSOR_TEST_TOKEN.";
   }
   const message = err instanceof Error ? err.message : typeof err === "string" ? err : undefined;
-  if (message) return safeCursorErrorMessage(message);
+  if (message) return safeCursorErrorMessage(message, sizeContext);
   return "Cursor upstream error: transport failed before completion.";
 }
 
+/**
+ * Size prior for bare resource_exhausted classification (devlog 260): a rough input
+ * estimate over the outgoing text vs the model's context window. Only used to keep
+ * SMALL requests on the 429 class — unknown/large stays on the overflow mapping.
+ */
+function cursorRequestSizeContext(request: { modelId: string; system: string[]; messages: { content: string }[] }): CursorSizeContext {
+  const text = [...request.system, ...request.messages.map(message => message.content)].join("\n");
+  return {
+    estimatedInputTokens: estimateTokens(text, request.modelId),
+    contextWindow: inferCursorContextWindow(request.modelId),
+  };
+}
+
 export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAdapterDeps = {}): ProviderAdapter {
   return {
     name: "cursor",
@@ -88,6 +102,9 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         emit({ type: "error", message: "Cursor turn was aborted before start." });
         return;
       }
+      // Captured after createCursorRequest so the catch block can apply the bare-RE
+      // size prior (devlog 260) even though `request` is scoped inside the try.
+      let requestSizeContext: CursorSizeContext | undefined;
       try {
         const makeTransport = deps.createTransport ?? createLiveCursorTransport;
         const kv = deps.kv ?? createCursorKvStore({}, incoming.translatorBudget);
@@ -110,6 +127,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         const inheritedCheckpointRef = _parsed._providerContinuation?.cursor?.checkpointRef;
         const previousConversationId = _parsed._cursorConversationId;
         let request = createCursorRequest(_parsed);
+        requestSizeContext = cursorRequestSizeContext(request);
         // The builder may derive a stable provider id from the client thread when Responses state
         // is unavailable. Rekey only existing state; there is nothing to migrate on a fresh turn,
         // and isolated helper/compaction turns must never inherit or donate the parent's usage state.
@@ -292,7 +310,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           type: "error",
           message: isTranslatorBudgetExceededError(err)
             ? "upstream translation buffer exceeded the safe limit"
-            : safeCursorTransportError(err),
+            : safeCursorTransportError(err, requestSizeContext),
           ...(isTranslatorBudgetExceededError(err)
             ? { status: 502, errorType: "upstream_error", code: "translation_buffer_limit" }
             : {}),

package/src/adapters/google.ts

@@ -413,6 +413,7 @@ interface GoogleResponsePart {
   thought?: boolean;
   thoughtSignature?: string;
   thought_signature?: string;
+  extra_content?: { google?: { thought_signature?: unknown } };
   functionCall?: unknown;
 }
 
@@ -421,6 +422,18 @@ interface GoogleFunctionCall {
   args?: unknown;
 }
 
+/**
+ * Read a Gemini/Antigravity thought signature from a response part. Antigravity can place it
+ * either directly on the part (`thoughtSignature` / `thought_signature`) or inside the same
+ * nested `extra_content.google.thought_signature` shape used on the Responses wire.
+ */
+function googlePartThoughtSignature(part: GoogleResponsePart): string | undefined {
+  const direct = part.thoughtSignature ?? part.thought_signature;
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  const nested = part.extra_content?.google?.thought_signature;
+  return typeof nested === "string" && nested.length > 0 ? nested : undefined;
+}
+
 /**
  * Carry a Gemini thought signature with the exact function-call part that produced it. Google
  * validates the signature against that specific part, so it must ride the individual tool call
@@ -430,7 +443,7 @@ function googleToolCallMetadataFromPart(
   part: GoogleResponsePart,
   fallbackSignature?: string,
 ): { providerMetadata: OcxProviderOpaqueToolCallMetadata } | undefined {
-  const signature = part.thoughtSignature ?? part.thought_signature ?? fallbackSignature;
+  const signature = googlePartThoughtSignature(part) ?? fallbackSignature;
   if (!isLikelyRealThoughtSignature(signature)) return undefined;
   return { providerMetadata: { google: { thoughtSignature: signature } } };
 }
@@ -960,7 +973,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         }
         if (parts) {
           for (const part of parts) {
-            const sig = part.thoughtSignature ?? part.thought_signature;
+            const sig = googlePartThoughtSignature(part);
             if (part.thought === true && sig && isLikelyRealThoughtSignature(sig)) {
               pendingStreamThoughtSig = sig;
             }
@@ -1224,7 +1237,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         }
         let pendingThoughtSig: string | undefined;
         for (const part of parts) {
-          const sig = part.thoughtSignature ?? part.thought_signature;
+          const sig = googlePartThoughtSignature(part);
           if (part.thought === true && sig && isLikelyRealThoughtSignature(sig)) {
             pendingThoughtSig = sig;
           }

package/src/adapters/openai-responses.ts

@@ -19,6 +19,7 @@ import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-co
 import { rewriteRoutedToolSearchForUpstream } from "../responses/tool-search-compat";
 import { rewriteRoutedNamespaceToolsForUpstream } from "../responses/namespace-tool-compat";
 import { openaiResponsesUrl } from "./openai-responses-url";
+import { normalizeXaiResponsesWebSearch } from "./xai-web-search";
 import {
   createAdapterTierMetadata,
 } from "../providers/fastwire";
@@ -1503,17 +1504,55 @@ function stripUnsupportedHostedTools(body: unknown): unknown {
  * provider capability metadata; an unclassified upstream keeps the fields.
  */
 const OPENAI_ONLY_WEB_SEARCH_FIELDS = ["external_web_access", "search_context_size"] as const;
-export function stripOpenAiOnlyWebSearchFields(body: unknown): unknown {
-  if (!isPlainObject(body) || !Array.isArray(body.tools)) return body;
+
+function stripOpenAiOnlyWebSearchFieldsFromTools(tools: unknown[]): {
+  tools: unknown[];
+  changed: boolean;
+} {
   let changed = false;
-  const tools = body.tools.map(t => {
-    if (!isPlainObject(t) || (t.type !== "web_search" && t.type !== "web_search_preview")) return t;
-    if (!OPENAI_ONLY_WEB_SEARCH_FIELDS.some(field => Object.hasOwn(t, field))) return t;
-    const { external_web_access: _access, search_context_size: _size, ...rest } = t;
+  const stripped = tools.map(tool => {
+    if (!isPlainObject(tool) || (tool.type !== "web_search" && tool.type !== "web_search_preview")) {
+      return tool;
+    }
+    if (!OPENAI_ONLY_WEB_SEARCH_FIELDS.some(field => Object.hasOwn(tool, field))) return tool;
+    const { external_web_access: _access, search_context_size: _size, ...rest } = tool;
     changed = true;
     return rest;
   });
-  return changed ? { ...body, tools } : body;
+  return { tools: changed ? stripped : tools, changed };
+}
+
+export function stripOpenAiOnlyWebSearchFields(body: unknown): unknown {
+  if (!isPlainObject(body)) return body;
+
+  let next: Record<string, unknown> = body;
+  let changed = false;
+  if (Array.isArray(body.tools)) {
+    const stripped = stripOpenAiOnlyWebSearchFieldsFromTools(body.tools);
+    if (stripped.changed) {
+      next = { ...next, tools: stripped.tools };
+      changed = true;
+    }
+  }
+
+  if (Array.isArray(body.input)) {
+    let inputChanged = false;
+    const input = body.input.map(item => {
+      if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) {
+        return item;
+      }
+      const stripped = stripOpenAiOnlyWebSearchFieldsFromTools(item.tools);
+      if (!stripped.changed) return item;
+      inputChanged = true;
+      return { ...item, tools: stripped.tools };
+    });
+    if (inputChanged) {
+      next = { ...next, input };
+      changed = true;
+    }
+  }
+
+  return changed ? next : body;
 }
 
 /** Replace every `input_image` part under a routed-compaction body with a short marker. */
@@ -1692,17 +1731,14 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       // that already recorded a single-query web_search_call replays it every turn, and
       // a strict parser rejects the whole request over it (#930).
       outBody = backfillWebSearchQueries(outBody);
-      // Same predicate as the routedCompaction gate in handleResponses(): an
-      // authMode check would let a noncanonical custom forward provider skip this
-      // rewrite while the server still routes it as a summarizer turn (#422).
-      if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
-        outBody = buildRoutedCompactionBody(outBody);
-      }
       if (!isCanonicalOpenAiForwardProvider(provider)) {
         outBody = promoteClientLoadedTools(outBody);
       }
       if (!isCanonicalOpenAiForwardProvider(provider)) {
-        const rewritten = rewriteRoutedCustomToolsForUpstream(outBody);
+        const rewritten = rewriteRoutedCustomToolsForUpstream(
+          outBody,
+          provider.supportsResponsesCustomTools,
+        );
         outBody = rewritten.body;
         convertedRoutedCustomToolNames = rewritten.names;
       }
@@ -1712,12 +1748,6 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         const rewritten = rewriteRoutedToolSearchForUpstream(outBody);
         outBody = rewritten.body;
         convertedRoutedToolSearchNames = rewritten.names;
-        // xAI rejects these OpenAI web_search extensions with HTTP 400. Keep them
-        // for OpenAI API-key traffic and unclassified gateways; only an explicit
-        // provider capability denial activates the compatibility transform.
-        if (provider.supportsOpenAiWebSearchToolFields === false) {
-          outBody = stripOpenAiOnlyWebSearchFields(outBody);
-        }
       }
       if (!isCanonicalOpenAiForwardProvider(provider)) {
         // Codex 0.147 emits private namespace tool groups, while public/third-party Responses
@@ -1726,9 +1756,25 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         const rewritten = rewriteRoutedNamespaceToolsForUpstream(outBody);
         outBody = rewritten.body;
         convertedRoutedNamespaceToolAliases = rewritten.aliases;
+        // Preserve xAI's cached-only fail-closed semantics and image-search mapping before the
+        // generic capability fallback removes the private OpenAI fields.
+        outBody = normalizeXaiResponsesWebSearch(outBody, provider);
+        // xAI and explicitly classified compatible gateways reject these OpenAI web_search
+        // extensions. Keep them for OpenAI API-key traffic and unclassified gateways.
+        if (provider.supportsOpenAiWebSearchToolFields === false) {
+          outBody = stripOpenAiOnlyWebSearchFields(outBody);
+        }
         // Last, so promoted namespace children are also cleared of Codex-private fields.
         outBody = stripCanonicalOnlyToolFields(outBody, provider.supportsOpenAiWebSearchToolFields === false);
       }
+      // Same predicate as the routedCompaction gate in handleResponses(): an authMode check would
+      // let a noncanonical custom forward provider skip this rewrite while the server still routes
+      // it as a summarizer turn (#422). The compaction body build removes the tool surface and must
+      // therefore be the last routed transform: anything before it may depend on the declarations;
+      // anything after it cannot.
+      if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
+        outBody = buildRoutedCompactionBody(outBody);
+      }
       const threadServingIdentityChanged = parsed._stripReasoningEncryptedContent === true;
       const sanitizedBody = normalizeToolSchemas(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(
         outBody,

package/src/adapters/xai-web-search.ts

@@ -0,0 +1,185 @@
+import type { OcxProviderConfig } from "../types";
+
+const CODEX_WEB_SEARCH_TOOL = "web_search";
+const CODEX_WEB_SEARCH_PREVIEW_TOOL = "web_search_preview";
+const XAI_API_HOST = "api.x.ai";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isCodexWebSearchToolType(value: unknown): boolean {
+  return value === CODEX_WEB_SEARCH_TOOL || value === CODEX_WEB_SEARCH_PREVIEW_TOOL;
+}
+
+/** Match only xAI's documented public API, not arbitrary Responses-compatible gateways. */
+function isXaiPublicApi(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
+  try {
+    const url = new URL(provider.baseUrl);
+    return url.protocol === "https:"
+      && url.hostname.toLowerCase() === XAI_API_HOST
+      && (url.port === "" || url.port === "443");
+  } catch {
+    return false;
+  }
+}
+
+type ToolGroupRewrite = {
+  tools: unknown[];
+  changed: boolean;
+};
+
+/**
+ * Translate Codex-private hosted-search fields to xAI's public Responses schema.
+ *
+ * xAI web search is live-only. A Codex cached/index-only declaration carries
+ * `external_web_access: false`; dropping that flag while keeping the tool would silently widen
+ * network access, so the whole tool is omitted instead. `true` maps to xAI's ordinary live
+ * `{type:"web_search"}` declaration. Requests that omit the private flag are already public-API
+ * shaped and retain their live-search behavior.
+ */
+function normalizeToolGroup(tools: unknown[]): ToolGroupRewrite {
+  const normalized: unknown[] = [];
+  let changed = false;
+
+  for (const tool of tools) {
+    if (!isPlainObject(tool) || !isCodexWebSearchToolType(tool.type)) {
+      normalized.push(tool);
+      continue;
+    }
+
+    const hasExternalAccess = Object.hasOwn(tool, "external_web_access");
+    if (hasExternalAccess && tool.external_web_access !== true) {
+      // xAI has no cached/index-only equivalent. Fail closed instead of turning it into live search.
+      changed = true;
+      continue;
+    }
+
+    const searchContentTypes = Array.isArray(tool.search_content_types)
+      ? tool.search_content_types
+      : undefined;
+    const enableImageSearch = searchContentTypes?.includes("image") === true;
+    const next: Record<string, unknown> = { ...tool, type: CODEX_WEB_SEARCH_TOOL };
+    delete next.external_web_access;
+    delete next.search_context_size;
+    delete next.search_content_types;
+    delete next.user_location;
+    if (enableImageSearch && !Object.hasOwn(next, "enable_image_search")) {
+      next.enable_image_search = true;
+    }
+
+    const toolChanged = Object.keys(next).length !== Object.keys(tool).length
+      || Object.entries(next).some(([key, value]) => tool[key] !== value);
+    changed ||= toolChanged;
+    normalized.push(toolChanged ? next : tool);
+  }
+
+  return { tools: changed ? normalized : tools, changed };
+}
+
+function hasWebSearchTool(body: Record<string, unknown>): boolean {
+  if (Array.isArray(body.tools) && body.tools.some(tool =>
+    isPlainObject(tool) && isCodexWebSearchToolType(tool.type)
+  )) return true;
+  return Array.isArray(body.input) && body.input.some(item =>
+    isPlainObject(item)
+    && item.type === "additional_tools"
+    && Array.isArray(item.tools)
+    && item.tools.some(tool => isPlainObject(tool) && isCodexWebSearchToolType(tool.type))
+  );
+}
+
+function hasAnyDeclaredTool(body: Record<string, unknown>): boolean {
+  if (Array.isArray(body.tools) && body.tools.length > 0) return true;
+  return Array.isArray(body.input) && body.input.some(item =>
+    isPlainObject(item)
+    && item.type === "additional_tools"
+    && Array.isArray(item.tools)
+    && item.tools.length > 0
+  );
+}
+
+/** Remove selectors that would still force a cached-only tool omitted above. */
+function normalizeToolChoice(body: Record<string, unknown>): Record<string, unknown> {
+  const choice = body.tool_choice;
+  if (choice === undefined) return body;
+  const hasSearch = hasWebSearchTool(body);
+
+  if (isPlainObject(choice) && isCodexWebSearchToolType(choice.type)) {
+    if (!hasSearch) return { ...body, tool_choice: "none" };
+    return choice.type === CODEX_WEB_SEARCH_TOOL
+      ? body
+      : { ...body, tool_choice: { ...choice, type: CODEX_WEB_SEARCH_TOOL } };
+  }
+  if (isPlainObject(choice) && choice.type === "allowed_tools" && Array.isArray(choice.tools)) {
+    let changed = false;
+    const tools: unknown[] = [];
+    for (const tool of choice.tools) {
+      if (!isPlainObject(tool) || !isCodexWebSearchToolType(tool.type)) {
+        tools.push(tool);
+        continue;
+      }
+      if (!hasSearch) {
+        changed = true;
+        continue;
+      }
+      if (tool.type === CODEX_WEB_SEARCH_PREVIEW_TOOL) {
+        tools.push({ ...tool, type: CODEX_WEB_SEARCH_TOOL });
+        changed = true;
+      } else {
+        tools.push(tool);
+      }
+    }
+    if (!changed) return body;
+    return {
+      ...body,
+      tool_choice: tools.length > 0 ? { ...choice, tools } : "none",
+    };
+  }
+  if (choice === "required" && !hasAnyDeclaredTool(body)) {
+    return { ...body, tool_choice: "none" };
+  }
+  return body;
+}
+
+/**
+ * Make Codex's hosted web-search declaration acceptable to xAI Responses without changing other
+ * providers or mutating the caller-owned request body.
+ */
+export function normalizeXaiResponsesWebSearch(
+  body: unknown,
+  provider: Pick<OcxProviderConfig, "baseUrl">,
+): unknown {
+  if (!isXaiPublicApi(provider) || !isPlainObject(body)) return body;
+
+  let next: Record<string, unknown> = body;
+  if (Array.isArray(body.tools)) {
+    const rewritten = normalizeToolGroup(body.tools);
+    if (rewritten.changed) {
+      next = { ...next };
+      if (rewritten.tools.length > 0) next.tools = rewritten.tools;
+      else delete next.tools;
+    }
+  }
+
+  if (Array.isArray(next.input)) {
+    let inputChanged = false;
+    const input: unknown[] = [];
+    for (const item of next.input) {
+      if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) {
+        input.push(item);
+        continue;
+      }
+      const rewritten = normalizeToolGroup(item.tools);
+      if (!rewritten.changed) {
+        input.push(item);
+        continue;
+      }
+      inputChanged = true;
+      if (rewritten.tools.length > 0) input.push({ ...item, tools: rewritten.tools });
+    }
+    if (inputChanged) next = { ...next, input };
+  }
+
+  return normalizeToolChoice(next);
+}

package/src/cli/agent.ts

@@ -27,7 +27,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> [--list] [--model <id|->] [--backend <openai|anthropic|xai|gemini|exa|->]
+  ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
+      [--backend web:<openai|anthropic|xai|gemini|exa|-> vision:<openai|anthropic|routed|->]
       [--reasoning <level>] [--max-descriptions <n>] [--json]`;
 
 function clearable(value: string | undefined): string | null | undefined {

package/src/cli/dispatch.ts

@@ -172,9 +172,9 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   doctor: async deps => {
     const doctorArgs = deps.args.slice(1);
-    const { runDoctor } = await import("./doctor");
+    const { RECOVER_ZERO_BYTE_COORDINATOR_FLAG, runDoctor } = await import("./doctor");
     await runDoctor(doctorArgs);
-    if (!doctorArgs.includes("--fix-codex-runtime")) {
+    if (!doctorArgs.includes("--fix-codex-runtime") && !doctorArgs.includes(RECOVER_ZERO_BYTE_COORDINATOR_FLAG)) {
       console.log("");
       const { printCodexLogGuardDoctor } = await import("./codex-log-guard-doctor");
       printCodexLogGuardDoctor();