@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
290 lines (263 loc) • 12.8 kB
text/typescript
import type { OcxProviderConfig } from "../types";
import { debugProviderDiagnostic } from "../lib/debug";
import { isXaiResponsesDestination } from "../providers/xai-transport";
import { isOpenCodeGoResponsesUrl } from "./opencode-go-additional-tools";
const CODEX_WEB_SEARCH_TOOL = "web_search";
const CODEX_WEB_SEARCH_PREVIEW_TOOL = "web_search_preview";
const XAI_SEARCH_TOOL = "x_search";
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;
}
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 };
// Only the two fields xAI actually refuses are removed. Probed 2026-08-22, one field per
// request, against BOTH xAI destinations (api.x.ai and cli-chat-proxy.grok.com): they behave
// identically — `external_web_access` 400s on every value including `true`, and
// `search_context_size` 400s, while `user_location`, `search_content_types`, `filters` and
// `enable_image_search` are all accepted. Deleting the accepted ones was a silent capability
// loss, and it contradicted the sibling layer, whose own probe note already records
// user_location/filters as accepted (tests/responses/responses-routed-web-search-fields.test.ts).
delete next.external_web_access;
delete next.search_context_size;
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;
}
function currentInputStart(inputLength: number, replayPrefixLength: number | undefined): number {
if (typeof replayPrefixLength !== "number" || !Number.isFinite(replayPrefixLength)) return 0;
return Math.min(inputLength, Math.max(0, Math.trunc(replayPrefixLength)));
}
function hasToolType(tools: unknown, type: string): boolean {
return Array.isArray(tools) && tools.some(tool => isPlainObject(tool) && tool.type === type);
}
/**
* OpenCode Go serves Grok on its Responses endpoint by relaying to xAI, and relays xAI's schema
* verbatim. Probed 2026-09-26 on `https://opencode.ai/zen/go/v1/responses` with grok-4.6 and
* grok-4.7, one field per request: `external_web_access` and `search_context_size` -> 400
* "Argument not supported", `web_search_preview` -> 422 `unknown variant`, while a plain
* `web_search` with `search_content_types`, `enable_image_search`, `user_location` or
* `filters` -> 200 and performs live searches. That is the xAI dialect exactly, so the same
* normalization applies. Sibling Go models (Luna, Muse Spark) accept the OpenAI fields and are
* left alone. Membership is by family prefix: an exact-id match is what let grok-4.7 reach this
* endpoint unnormalized once it joined grok-4.6 on the Responses wire.
*/
function isOpenCodeGoGrokResponses(modelId: unknown, responseUrl: string | undefined): boolean {
return typeof modelId === "string"
&& modelId.trim().toLowerCase().startsWith("grok-")
&& typeof responseUrl === "string"
&& isOpenCodeGoResponsesUrl(responseUrl);
}
/**
* Make Codex's hosted web-search declaration acceptable to xAI Responses without changing other
* providers or mutating the caller-owned request body.
*
* Scoped to BOTH xAI Responses hosts, not just the public API. The 2026-08-22 probe recorded in
* `normalizeToolGroup` and in `isXaiResponsesDestination` already found the two hosts to be one
* dialect, but this gate stayed on `api.x.ai` alone, so the Grok CLI proxy — the OAuth lane — was
* left unnormalized. Re-probed 2026-08-27 against `cli-chat-proxy.grok.com`:
* `web_search_preview` -> 422 `unknown variant`, `external_web_access` -> 400 on every value,
* `search_context_size` -> 400, while `user_location` and `search_content_types` -> 200. Identical
* to the public API, which is what makes one shared gate correct.
*
* Grok models on the exact OpenCode Go Responses URL speak the same dialect and share this gate;
* see `isOpenCodeGoGrokResponses`. `target` carries the final model id and request URL for that
* check, and callers without it keep the xAI-host-only behavior.
*/
export function normalizeXaiResponsesWebSearch(
body: unknown,
provider: Pick<OcxProviderConfig, "baseUrl">,
target?: { modelId?: unknown; responseUrl?: string },
): unknown {
if (!isPlainObject(body)) return body;
const xaiDestination = isXaiResponsesDestination(provider);
if (!xaiDestination && !isOpenCodeGoGrokResponses(target?.modelId, target?.responseUrl)) return body;
// On Go, a wrapper emptied here stays in place: Go promotion (opencode-go-additional-tools.ts)
// removes every wrapper before the wire and splits them into history and current turn by
// index against _replayPrefixLen, so deleting one would shift the current turn into history.
const keepEmptiedWrappers = !xaiDestination;
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 || keepEmptiedWrappers) input.push({ ...item, tools: rewritten.tools });
}
if (inputChanged) next = { ...next, input };
}
const normalized = normalizeToolChoice(next);
const choice = normalized.tool_choice;
if ((choice === "auto" || choice === "none") && !hasAnyDeclaredTool(normalized)) {
debugProviderDiagnostic("xai", "tool-choice-omitted", { choice });
const { tool_choice: _toolChoice, ...rest } = normalized;
// `auto` selects from the catalog, so a catalog with nothing in it makes it meaningless and
// the omission says nothing the request did not already say. `none` is the opposite: it is a
// prohibition, and on a request whose catalog this normalizer just emptied it is the only
// place the turn's client-call boundary is written down. Downstream repair reads that
// boundary off the final outbound body, so omitting the word alone would hand back a call the
// caller ruled out. Restate it as the explicit empty catalog, which carries the same deny-all
// and which this destination already receives whenever a caller sends one itself.
return choice === "none" && !Array.isArray(rest.tools) ? { ...rest, tools: [] } : rest;
}
return normalized;
}
function isLiveWebSearchTool(tool: unknown): boolean {
return isPlainObject(tool)
&& tool.type === CODEX_WEB_SEARCH_TOOL
&& (!Object.hasOwn(tool, "external_web_access") || tool.external_web_access === true);
}
/**
* Add xAI's hosted X search declaration without changing web-search normalization or selectors.
* Destination classification belongs only to this opt-in injection path; the public-API
* normalizer above intentionally retains its narrower causality boundary.
*/
export function injectXaiResponsesXSearch(
body: unknown,
provider: Pick<OcxProviderConfig, "baseUrl" | "xaiResponsesXSearch">,
replayPrefixLength?: number,
): unknown {
if (
!isPlainObject(body)
|| !isXaiResponsesDestination(provider)
|| provider.xaiResponsesXSearch !== true
) return body;
const input = Array.isArray(body.input) ? body.input : undefined;
const inputStart = input ? currentInputStart(input.length, replayPrefixLength) : 0;
const currentInput = input?.slice(inputStart) ?? [];
const currentXSearchDeclared = hasToolType(body.tools, XAI_SEARCH_TOOL)
|| currentInput.some(item =>
isPlainObject(item)
&& item.type === "additional_tools"
&& hasToolType(item.tools, XAI_SEARCH_TOOL)
);
if (currentXSearchDeclared) return body;
const liveWebSearchSurvives = Array.isArray(body.tools) && body.tools.some(isLiveWebSearchTool)
|| currentInput.some(item =>
isPlainObject(item)
&& item.type === "additional_tools"
&& Array.isArray(item.tools)
&& item.tools.some(isLiveWebSearchTool)
);
if (!liveWebSearchSurvives) return body;
// Declaration does not grant selection when `tool_choice` names a specific tool or carries an
// `allowed_tools` set that excludes x_search, so leave that selector byte-shape untouched.
const tools = Array.isArray(body.tools) ? body.tools : [];
return { ...body, tools: [...tools, { type: XAI_SEARCH_TOOL }] };
}