@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
418 lines (393 loc) • 19.8 kB
text/typescript
export interface OcxTool {
name: string;
description: string;
parameters: Record<string, unknown>;
strict?: boolean;
/**
* Anthropic `tools[*].allowed_callers`: which callers may invoke this tool. Carried rather
* than diagnosed, because rebuilding the declaration without it hands the model a tool the
* caller had restricted and returns a normal response (#5210).
*/
allowedCallers?: string[];
/** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
namespace?: string;
/** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
freeform?: boolean;
/** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
toolSearch?: boolean;
/** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
loadedFromToolSearch?: boolean;
/** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
cursorStructuredEdit?: true;
/** Synthetic web_search tool: the model's call is executed by the gpt-5.6-luna sidecar, not relayed to Codex. */
webSearch?: boolean;
/** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
imageGeneration?: boolean;
/** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
videoGeneration?: boolean;
}
/**
* Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
* "<namespace>__<name>" so they survive the chat-completions function-tool format;
* the proxy maps this back to {namespace, name} on the return trip (Codex routes MCP
* calls by an explicit `namespace` field, not by parsing the name).
*/
export function namespacedToolName(namespace: string | undefined, name: string): string {
return namespace ? `${namespace}__${name}` : name;
}
/**
* Whether a declaration actually narrows who may call the tool.
*
* `["direct"]` is the state every unrestricted tool is already in, so treating it as a
* restriction would refuse ordinary traffic. Mirrors the `caller_mode` predicate in
* src/claude/compatibility.ts, which draws the same line.
*/
export function toolRestrictsCallers(tool: Pick<OcxTool, "allowedCallers">): boolean {
const callers = tool.allowedCallers;
if (callers === undefined) return false;
return !(callers.length === 1 && callers[0] === "direct");
}
/**
* Dotted alias of a namespaced tool's wire name. Some routed providers (observed: muse-spark
* via opencode-go) echo a namespaced tool call as "<namespace>.<name>" instead of the flattened
* "<namespace>__<name>" form. It names the same tool identity+�u���T never a new grant"��y��y� so the
* undeclared-tool guard and the tool bridge maps accept it wherever the wire name is accepted
* (mirroring the second entry of `toolChoiceAliases`). See #3402.
*/
export function dottedToolName(namespace: string | undefined, name: string): string {
return namespace ? `${namespace}.${name}` : name;
}
/**
* Codex unified-exec name normalization.
*
* Codex's code-mode shell tool is declared as `exec` (a freeform custom tool whose own
* description mentions the nested `await tools.exec_command(...)` helper). Some routed providers
* echo that helper name as the tool-call name, emitting `exec_command`, `write_stdin`,
* `apply_patch`, `view_image`, or one of the goal helpers (`create_goal`, `get_goal`,
* `update_goal`, #5495) instead of the declared `exec`. Accept these nested helper names only
* when the request catalog actually declares `exec` and does not itself declare the emitted name
* (an MCP server may legitimately advertise one under its own namespace). The helper list itself
* is closed; the one other admission through `exec` is a direct `mcp__<server>__<tool>` call,
* which `isCodeModeMcpDirectName` recognizes.
*/
const LEGACY_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
const CODE_MODE_HELPER_TOOL_NAMES = [
...LEGACY_SHELL_BRIDGE_TOOL_NAMES,
"write_stdin",
"apply_patch",
"view_image",
"create_goal",
"get_goal",
"update_goal",
] as const;
/**
* The one declared name that turns nested-helper normalization on. Declaring it is not just a
* name: it also decides whether an emitted helper name is accepted as that shell tool, so callers
* that build declared-name sets must add it only for a genuine bare declaration.
*/
export const CODE_MODE_EXEC_TOOL_NAME = "exec";
/**
* The nested-helper spellings, as a membership view of the same list.
*
* A code-mode catalog never DECLARES any of them — they exist only as `tools.<helper>(...)` inside
* `exec` — so a recorded call under one of these names can only have come from a provider echoing
* the helper, which is what makes the set usable as a bounded recovery vocabulary for stored
* history (#5095). Kept beside the tuple it is built from so the two can never drift; this is a
* different question from `NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES` below, which also covers `exec`
* itself because declaring THAT name is what turns normalization on.
*/
export const CODE_MODE_HELPER_WIRE_NAMES: ReadonlySet<string> = new Set<string>(
CODE_MODE_HELPER_TOOL_NAMES,
);
/**
* A flattened MCP wire name (`mcp__<server>__<tool>`) emitted as a direct tool call.
*
* Codex code mode reaches the host's nested tools through `tools.<name>(...)` inside `exec`,
* so none of them are declared; routed models (observed: Kimi K3, GLM 5.3) occasionally skip the
* wrapper and call the flattened name directly. Under a code-mode catalog the call is compiled
* into the equivalent `tools.<name>(...)` exec body instead of failing closed — capability-
* equivalent, since the model could have written that JavaScript itself. Server and tool must
* both be non-empty so a bare `mcp__` prefix never qualifies.
*/
export function isCodeModeMcpDirectName(name: string): boolean {
if (!name.startsWith("mcp__")) return false;
const rest = name.slice("mcp__".length);
const separator = rest.indexOf("__");
return separator > 0 && separator + "__".length < rest.length;
}
/**
* Spellings that may never be MANUFACTURED as a bare alias for a namespaced tool.
*
* A bare alias is an ordinary compatibility affordance -- providers echo a namespaced tool
* without its prefix, and restoring the identity needs the bare spelling registered. For these
* names it is also an authorization decision, because a declared-name set is what
* `normalizeDeclaredToolName` and `declaresCodeModeExec` read: bare `exec` turns nested-helper
* normalization on for a catalog that never declared the shell, bare `exec_command` or
* `shell_command` turns it off for one that did, and the rest are accepted as declared calls the
* caller only ever authorized under a namespace.
*
* This is a property of the SPELLING, not of the namespace that declared it and not of the reason
* the alias was being added. It lives here, beside the names it protects, because every site that
* builds a declared-name set has to apply the same list -- the two that kept their own copies each
* drifted, once to a single namespace and once to a single name.
*
* A genuine namespace-free declaration is NOT covered: that is the caller declaring the tool, not
* a namespace being discarded to synthesize a bare name.
*/
export const NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES: ReadonlySet<string> = new Set<string>([
CODE_MODE_EXEC_TOOL_NAME,
...CODE_MODE_HELPER_TOOL_NAMES,
]);
/**
* Normalizes provider-emitted tool names against declared tool catalogs.
*
* Rewrites invented `default.<name>` prefixes back to a declared bare tool when that bare tool
* is declared and neither `default.<name>` nor `default__<name>` was explicitly declared (#4176).
* The same wrapper may surround an already-flattened namespace identity; accept that exact
* declared suffix without treating its child name as a bare declaration.
* Also normalizes nested helper names (`exec_command`, `shell_command`, `write_stdin`,
* `apply_patch`, `view_image`, `create_goal`, `get_goal`, `update_goal`) and direct
* `mcp__<server>__<tool>` calls to `exec` when code-mode `exec` is declared in the
* request catalog. MCP recovery additionally requires explicit custom-tool provenance;
* a structured function named `exec` is not a JavaScript executor.
*
* @param name - The tool name emitted on the wire by the provider.
* @param declared - All wire tool names declared in the request catalog, including aliases.
* @param declaredBare - Explicitly declared bare tool names without namespace provenance.
* When omitted, falls back to `declared`.
* @param declaredCustom - Custom wire identities from the caller's catalog, never bare aliases
* manufactured from foreign namespaces.
* @returns The normalized tool name to expose downstream.
*/
export function normalizeDeclaredToolName(
name: string,
declared: ReadonlySet<string> | undefined,
declaredBare?: ReadonlySet<string>,
declaredCustom?: ReadonlySet<string>,
): string {
if (!declared) return name;
if (declared.has(name)) return name;
let candidate = name;
if (name.startsWith("default.")) {
const bare = name.slice("default.".length);
const bareDeclared = declaredBare ?? declared;
if (
bare.length > 0
&& (
bareDeclared.has(bare)
// Muse can wrap the complete `namespace__tool` identity in `default.`. Requiring the
// exact flattened identity to be declared preserves the #4176 provenance boundary:
// `default.tool` still cannot borrow a namespaced tool's manufactured bare alias.
|| (bare.includes("__") && declared.has(bare))
)
&& !declared.has("default." + bare)
&& !declared.has("default__" + bare)
) {
candidate = bare;
} else if (
// Code mode never declares bare helper names; a provider that invents `default.`
// for one still means the nested helper. The same wrapper can surround a direct MCP
// name, but only a custom exec declaration authorizes that recovery.
bare.length > 0
&& declared.has(CODE_MODE_EXEC_TOOL_NAME)
&& ((CODE_MODE_HELPER_TOOL_NAMES as readonly string[]).includes(bare)
|| (declaredCustom?.has(CODE_MODE_EXEC_TOOL_NAME) && isCodeModeMcpDirectName(bare)))
&& !declared.has("default." + bare)
&& !declared.has("default__" + bare)
) {
candidate = bare;
}
}
if (!declared.has(CODE_MODE_EXEC_TOOL_NAME)) return candidate;
if (declared.has(candidate)) return candidate;
if (candidate === "apply_patch") return CODE_MODE_EXEC_TOOL_NAME;
// When the catalog explicitly declares any legacy shell bridge name, the environment
// genuinely exposes that tool — turn normalization off so a call is never mis-routed
// to `exec`.
if ((LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).some(legacy => declared.has(legacy))) {
return candidate;
}
if ((CODE_MODE_HELPER_TOOL_NAMES as readonly string[]).includes(candidate)) {
return CODE_MODE_EXEC_TOOL_NAME;
}
// A direct `mcp__<server>__<tool>` call names a nested host tool the code-mode catalog
// never declares; `compileCodeModeHelperInput` turns it into the `tools.<name>(...)`
// exec body the model could have written itself.
return declaredCustom?.has(CODE_MODE_EXEC_TOOL_NAME) && isCodeModeMcpDirectName(candidate)
? CODE_MODE_EXEC_TOOL_NAME
: candidate;
}
/**
* True when a declared catalog is the genuine Codex code-mode shape.
*
* `exec` is a name, not a guarantee. A catalog that lists `exec` NEXT TO a bare
* `exec_command` or `shell_command` is the flat-bridge shape: there `exec` may be an
* ordinary caller-defined tool, and nested `tools.*` helpers are not what it runs.
* `normalizeDeclaredToolName` already refuses to reinterpret helper names in that shape,
* and anything inferring code mode from the bare name owes the same check.
*/
export function declaresCodeModeExec(declared: ReadonlySet<string> | undefined): boolean {
if (!declared || !declared.has(CODE_MODE_EXEC_TOOL_NAME)) return false;
return !(LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).some(legacy => declared.has(legacy));
}
export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
const wireName = namespacedToolName(tool.namespace, tool.name);
return tool.namespace ? [wireName, dottedToolName(tool.namespace, tool.name)] : [wireName];
}
function sameToolIdentity(
left: Pick<OcxTool, "namespace" | "name">,
right: Pick<OcxTool, "namespace" | "name">,
): boolean {
return left.namespace === right.namespace && left.name === right.name;
}
type ToolIdentity = Readonly<Pick<OcxTool, "namespace" | "name">>;
function snapshotToolIdentity(tool: Pick<OcxTool, "namespace" | "name">): ToolIdentity {
return Object.freeze({
name: tool.name,
...(tool.namespace === undefined ? {} : { namespace: tool.namespace }),
});
}
function buildToolChoiceCatalog(
tools: readonly ToolIdentity[],
): {
candidatesByName: ReadonlyMap<string, readonly ToolIdentity[]>;
sourceCandidatesByName: ReadonlyMap<string, readonly ToolIdentity[]>;
identitiesByTool: WeakMap<object, ToolIdentity>;
} {
const index = new Map<string, ToolIdentity[]>();
const sourceIndex = new Map<string, ToolIdentity[]>();
const identities = new Map<string, Set<string>>();
const identitiesByTool = new WeakMap<object, ToolIdentity>();
for (const tool of tools) {
const snapshot = snapshotToolIdentity(tool);
identitiesByTool.set(tool, snapshot);
const identity = JSON.stringify([snapshot.namespace ?? null, snapshot.name]);
for (const selector of [...toolChoiceAliases(snapshot), snapshot.name]) {
const candidates = index.get(selector);
if (!candidates) {
index.set(selector, [snapshot]);
sourceIndex.set(selector, [tool]);
identities.set(selector, new Set([identity]));
} else if (!identities.get(selector)!.has(identity)) {
candidates.push(snapshot);
sourceIndex.get(selector)!.push(tool);
identities.get(selector)!.add(identity);
}
}
}
return { candidatesByName: index, sourceCandidatesByName: sourceIndex, identitiesByTool };
}
/** Compile one immutable view of a request's tool catalog for repeated policy checks. */
export function createToolChoiceResolver(tools: readonly ToolIdentity[] | undefined) {
const compiled = tools ? buildToolChoiceCatalog(tools) : undefined;
const candidatesByName = compiled?.candidatesByName;
const snapshotFor = (tool: ToolIdentity): ToolIdentity | undefined => {
const snapshot = compiled?.identitiesByTool.get(tool);
return snapshot && sameToolIdentity(snapshot, tool) ? snapshot : undefined;
};
return {
candidates(name: string): ToolIdentity[] {
return (candidatesByName?.get(name) ?? []).map(candidate => ({ ...candidate }));
},
candidateCount(name: string): number {
return candidatesByName?.get(name)?.length ?? 0;
},
allows(tool: ToolIdentity, allowedTools: ReadonlySet<string>): boolean {
if (!candidatesByName) return toolChoiceAliases(tool).some(name => allowedTools.has(name));
const snapshot = snapshotFor(tool);
return snapshot ? toolAllowedByChoiceFromIndex(snapshot, allowedTools, candidatesByName) : false;
},
selects(tool: ToolIdentity, name: string): boolean {
const snapshot = snapshotFor(tool);
const candidates = candidatesByName?.get(name);
return !!snapshot && candidates?.length === 1 && sameToolIdentity(candidates[0], snapshot);
},
};
}
/**
* All tools that could be selected by one client-facing name. Bare logical names are included
* here because they are a compatibility selector for namespaced tools, while wire and dotted
* aliases come from `toolChoiceAliases`. A selector with more than one candidate is invalid.
*/
export function toolChoiceCandidates(
tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
name: string,
): Pick<OcxTool, "namespace" | "name">[] {
if (!tools) return [];
return [...(buildToolChoiceCatalog(tools).sourceCandidatesByName.get(name) ?? [])];
}
/**
* Newer Codex clients can select a tool nested in a namespace by its bare name. Resolve that
* shorthand only when the request contains one tool with the logical name, so an ambiguous name
* cannot authorize a tool from an unintended namespace.
*/
export function toolAllowedByChoice(
tool: Pick<OcxTool, "namespace" | "name">,
allowedTools: ReadonlySet<string>,
tools?: readonly Pick<OcxTool, "namespace" | "name">[],
): boolean {
if (!tools) return toolChoiceAliases(tool).some(name => allowedTools.has(name));
return toolAllowedByChoiceFromIndex(
snapshotToolIdentity(tool),
allowedTools,
buildToolChoiceCatalog(tools).candidatesByName,
);
}
function toolAllowedByChoiceFromIndex(
tool: ToolIdentity,
allowedTools: ReadonlySet<string>,
candidatesByName: ReadonlyMap<string, readonly ToolIdentity[]>,
): boolean {
for (const name of [...toolChoiceAliases(tool), tool.name]) {
if (!allowedTools.has(name)) continue;
const candidates = candidatesByName.get(name);
if (candidates?.length === 1 && sameToolIdentity(candidates[0], tool)) return true;
}
return false;
}
export function resolveToolChoiceWireName(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined, name: string): string {
const candidates = toolChoiceCandidates(tools, name);
if (candidates.length === 1) {
const match = candidates[0];
return namespacedToolName(match.namespace, match.name);
}
// Keep unknown/ambiguous names unchanged for callers that only serialize a selector. The
// catalog-aware predicate rejects them, and parseRequest rejects ambiguous request selectors.
return name;
}
/**
* Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
* id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
* `gpt-oss:120b`/`gpt-oss:20b`. Colon-less ids (e.g. `grok-build-0.1`) still match exactly only.
*/
export function modelInList(list: string[] | undefined, modelId: string): boolean {
if (!list || list.length === 0) return false;
if (list.includes(modelId)) return true;
const colon = modelId.indexOf(":");
return colon > 0 && list.includes(modelId.slice(0, colon));
}
export type OcxToolChoice =
| "auto"
| "none"
| "required"
| { name: string }
| { allowedTools: string[]; mode: "auto" | "required" };
export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is { allowedTools: string[]; mode: "auto" | "required" } {
return typeof value === "object" && value !== null && "allowedTools" in value;
}
/** Compile the request's tool-choice policy into a reusable advertisement/restoration predicate. */
export function toolChoiceToolPredicate(
choice: OcxToolChoice | undefined,
tools?: readonly Pick<OcxTool, "namespace" | "name">[],
): (tool: Pick<OcxTool, "namespace" | "name">) => boolean {
if (!choice || choice === "auto" || choice === "required") return () => true;
if (choice === "none") return () => false;
if (isAllowedToolChoice(choice)) {
const allowed = new Set(choice.allowedTools);
const resolver = createToolChoiceResolver(tools);
return tool => resolver.allows(tool, allowed);
}
if (!tools) return tool => toolChoiceAliases(tool).includes(choice.name);
const resolver = createToolChoiceResolver(tools);
return tool => resolver.selects(tool, choice.name);
}