@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
256 lines (248 loc) • 13.6 kB
text/typescript
import { createToolChoiceResolver, dottedToolName, namespacedToolName, type OcxRequestOptions, type OcxTool } from "../types";
import { isObj } from "./parser-content";
import { WEB_SEARCH_TOOL_NAME } from "../web-search/synthetic-tool";
import { buildImageTool, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
import { toolSearchDescription, toolSearchParameters } from "./tool-search-compat";
/** Capture the function and custom selectors from the original request before wire lowering. */
export function explicitToolChoices(value: unknown, tools: readonly OcxTool[]): Pick<OcxRequestOptions, "explicitRootFunctionChoices" | "explicitClientToolChoices"> {
if (!isObj(value)) return {};
const selectors = value.type === "allowed_tools" && Array.isArray(value.tools) ? value.tools : [value];
const rootFunctions = new Set<string>();
const clientTools: NonNullable<OcxRequestOptions["explicitClientToolChoices"]>[number][] = [];
for (const selector of selectors) {
if (!isObj(selector) || typeof selector.name !== "string" || !selector.name) continue;
const { type, name } = selector;
if (type !== "function" && type !== "custom") continue;
const namespace = selectorNamespace(selector);
clientTools.push({ type, name, namespace });
if (type === "function" && (namespace === undefined || (
isQualifiedRootAdvisor(type, namespace, name) && !tools.some(tool => !tool.namespace && tool.name === name)
))) rootFunctions.add(name);
}
return { explicitRootFunctionChoices: [...rootFunctions], explicitClientToolChoices: clientTools };
}
function selectorNamespace(selector: Record<string, unknown>): string | undefined {
// Codex's reserved functions group and the empty namespace both denote root tools.
return typeof selector.namespace === "string" ? (selector.namespace === "functions" ? "" : selector.namespace) : undefined;
}
function isQualifiedRootAdvisor(type: unknown, namespace: string | undefined, name: string): boolean {
return type === "function" && namespace === "" && name === "advisor";
}
export function mapToolChoice(value: unknown, tools?: readonly OcxTool[]): OcxRequestOptions["toolChoice"] {
if (value === undefined || value === null) return undefined;
if (value === "auto" || value === "none" || value === "required") return value;
if (isObj(value) && "type" in value) {
const qualifiedToolNames = new Set<string>();
let resolver: ReturnType<typeof createToolChoiceResolver> | undefined;
let wireTools: Map<string, OcxTool> | undefined;
const lower = (selector: Record<string, unknown>, name: string): string => {
const { type } = selector;
const namespace = type === "function" || type === "custom" ? selectorNamespace(selector) : undefined;
if (namespace === undefined) {
if (tools && (resolver ??= createToolChoiceResolver(tools)).candidateCount(name) > 1) {
throw new Error(`ambiguous tool_choice name: ${name}`);
}
return name;
}
const wireName = namespacedToolName(namespace, name);
if (tools) {
wireTools ??= new Map(tools.map(tool => [namespacedToolName(tool.namespace, tool.name), tool]));
const match = wireTools.get(wireName);
// An undeclared root Advisor can be supplied later by the sidecar. A declared
// owner still has to match exactly, including kind.
const defersToAdvisor = !match && isQualifiedRootAdvisor(type, namespace, name);
if (!defersToAdvisor && (!match || (match.namespace ?? "") !== namespace || match.name !== name
|| (match.freeform ? "custom" : "function") !== type || match.imageGeneration || match.toolSearch)) {
throw new Error(`invalid tool_choice: no declared ${type} tool ${dottedToolName(namespace, name)}`);
}
}
qualifiedToolNames.add(wireName);
return wireName;
};
const qualified = () => qualifiedToolNames.size > 0 ? { qualifiedToolNames: [...qualifiedToolNames] } : {};
const t = value.type;
if ((t === "function" || t === "custom") && typeof value.name === "string") {
return { name: lower(value, value.name), ...qualified() };
}
// Hosted image tool types (with or without a name) map to the synthetic image_gen wire name.
if (t === "image_generation" || t === "image_gen") {
return { name: lower(value, IMAGE_GEN_TOOL_NAME) };
}
if (t === "tool_search") return { name: lower(value, "tool_search") };
if (t === "allowed_tools" && Array.isArray(value.tools)) {
const names = value.tools
.map(entry => {
if (!isObj(entry)) return undefined;
const name = allowedToolName(entry);
if (name) return lower(entry, name);
if ((entry.type === "function" || entry.type === "custom") && selectorNamespace(entry) !== undefined) {
throw new Error("invalid tool_choice: a namespace-qualified selector requires a tool name");
}
return undefined;
})
.filter((name): name is string => Boolean(name));
return names.length > 0
? { allowedTools: [...new Set(names)], mode: value.mode === "required" ? "required" : "auto", ...qualified() }
: "none";
}
return "auto";
}
return undefined;
}
function allowedToolName(tool: Record<string, unknown>): string | undefined {
if (typeof tool.name === "string" && tool.name.length > 0) return tool.name;
if (tool.type === "web_search" || tool.type === "web_search_preview") return WEB_SEARCH_TOOL_NAME;
if (tool.type === "image_generation" || tool.type === "image_gen") return IMAGE_GEN_TOOL_NAME;
if (tool.type === "tool_search") return "tool_search";
return undefined;
}
export function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
if (!tools) return undefined;
const out: OcxTool[] = [];
const normalizeParameters = (raw: unknown): Record<string, unknown> => {
if (isObj(raw) && raw.type === "object") return raw;
return { ...(isObj(raw) ? raw : {}), type: "object" };
};
const pushFn = (t: Record<string, unknown>, namespace?: string) => {
// Hosted image_generation already installed the synthetic root tool. A later
// ordinary root `image_gen` must not create a second un-namespaced identity.
if (
!namespace
&& t.name === IMAGE_GEN_TOOL_NAME
&& out.some(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace && tool.imageGeneration)
) {
return;
}
const tool: OcxTool = {
name: t.name as string,
description: (t.description as string) ?? "",
parameters: normalizeParameters(t.parameters),
};
if (t.strict !== undefined) tool.strict = t.strict as boolean;
if (Array.isArray(t.allowed_callers)) {
tool.allowedCallers = (t.allowed_callers as unknown[]).filter((c): c is string => typeof c === "string");
}
if (namespace) tool.namespace = namespace;
out.push(tool);
};
const pushCustom = (t: Record<string, unknown>, namespace?: string) => {
// Hosted image_generation already installed the synthetic root tool. A later
// root custom `image_gen` would collide on the same wire name with a different
// `freeform` flag and throw `ambiguous tool catalog`.
if (
!namespace
&& t.name === IMAGE_GEN_TOOL_NAME
&& out.some(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace && tool.imageGeneration)
) {
return;
}
// Freeform custom tools are lowered to a single string `input` because chat models cannot
// emit Responses grammar payloads directly. Keep tool-specific input guidance scoped to the
// tool that owns it: leaking apply_patch syntax into `exec` or another freeform tool teaches
// routed models that the nested helper name is itself a callable top-level tool.
const inputDescription = t.name === "apply_patch"
? "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope."
: "Raw freeform input for this tool.";
const tool: OcxTool = {
name: t.name as string,
description: (t.description as string) ?? "",
parameters: { type: "object", properties: { input: { type: "string", description: inputDescription } }, required: ["input"] },
freeform: true,
};
if (namespace) tool.namespace = namespace;
out.push(tool);
};
for (const t of tools) {
if (!isObj(t)) continue;
if (t.type === "function" && isObj(t.function) && typeof t.function.name === "string" && t.function.name.length > 0) {
pushFn(t.function as Record<string, unknown>);
continue;
}
if (t.type === "function" && typeof t.name === "string") {
pushFn(t);
} else if (t.type === "namespace" && Array.isArray(t.tools)) {
// Codex 0.147 groups its ordinary client tools under the reserved `functions` namespace,
// including freeform custom tools such as code-mode `exec`. Those children are still
// top-level Responses tools, so flatten them without a namespace. Other namespace groups
// are MCP-style and keep their namespace for round-trip routing.
const builtinFunctions = t.name === "functions";
const ns = typeof t.name === "string" && !builtinFunctions ? t.name : undefined;
for (const inner of t.tools as unknown[]) {
if (isObj(inner) && inner.type === "function" && typeof inner.name === "string") pushFn(inner, ns);
else if (isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner, ns);
}
}
else if (t.type === "custom" && typeof t.name === "string") {
pushCustom(t);
}
else if (t.type === "tool_search") {
// Client-executed tool discovery — the gateway to deferred tools (subagents, extra MCP tools).
// Expose as a function so chat models can call it; the bridge relays it as a tool_search_call.
out.push({
name: "tool_search",
description: toolSearchDescription(t),
parameters: normalizeParameters(toolSearchParameters(t)),
toolSearch: true,
});
}
else if (t.type === "image_generation" || t.type === "image_gen") {
// Keep Codex's image_gen visible to routed chat models. The hosted OpenAI tool
// cannot execute on Grok; the model still has to see a callable image_gen so
// Codex's client-side /v1/images request can fire and be relayed to xAI.
// Identity is the un-namespaced synthetic root (`imageGeneration: true`), not
// the bare name: a namespaced ordinary `image_gen` must not suppress it.
const synthetic = buildImageTool();
// Every un-namespaced `image_gen` collides on one wire name, so removing only
// the first leaves a second root behind and the catalog stays ambiguous.
// Drop all root collisions, keep namespaced entries, then insert exactly one
// synthetic root — at the earliest colliding position so declaration order is
// preserved for models that read the catalog positionally.
let insertAt = -1;
for (let i = out.length - 1; i >= 0; i -= 1) {
const tool = out[i]!;
if (tool.name !== IMAGE_GEN_TOOL_NAME || tool.namespace) continue;
out.splice(i, 1);
insertAt = i;
}
if (insertAt >= 0) out.splice(insertAt, 0, synthetic);
else out.push(synthetic);
}
else if (typeof t.name === "string" && t.type !== "web_search" && t.type !== "image_generation") {
// Any OTHER named tool (e.g. a native/computer-use tool type opencodex doesn't explicitly
// model) is client-executed — pass it through as a function so the routed model can read and
// call it naturally; the bridge relays its call as a function_call. Previously such tools were
// silently dropped, so the model never saw them.
pushFn(t);
}
// Hosted web_search is still dropped here — the web-search sidecar re-injects it.
}
return out.length > 0 ? out : undefined;
}
/**
* Namespace a custom tool was declared under, by its bare name.
*
* A `custom_tool_call` echoed back by the client carries only the bare name — the bridge
* emits `{"type":"custom_tool_call","name":"exec"}` even when the tool was declared as
* `mcp__functions__exec`. Without this lookup the namespace is lost on the return trip,
* and the adapters replay history through `namespacedToolName(namespace, name)`, which
* then produces a bare `exec` the provider may not have. Ordinary `function_call` items
* do not need this: they carry `namespace` on the wire.
*/
export function customToolNamespaces(tools: unknown): Map<string, string> {
const out = new Map<string, string>();
if (!Array.isArray(tools)) return out;
for (const spec of tools) {
if (!isObj(spec) || spec.type !== "namespace" || !Array.isArray(spec.tools)) continue;
const namespace = typeof spec.name === "string" ? spec.name : undefined;
// Codex 0.147 groups ordinary client tools under the reserved `functions` namespace and
// buildTools deliberately flattens those without a namespace. Mirror that here, or the
// reconstruction would invent a namespace the request never advertised.
if (!namespace || namespace === "functions") continue;
for (const inner of spec.tools) {
if (!isObj(inner) || inner.type !== "custom" || typeof inner.name !== "string") continue;
// Ambiguous bare names are already rejected upstream, so first declaration wins.
if (!out.has(inner.name)) out.set(inner.name, namespace);
}
}
return out;
}