Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
feat(openai-codex): render Claude Code tools into a freeform exec tool
Jack Rudenko38ad55a2b602
diff --git a/packages/cli/src/code-mode/exec-tool.ts b/packages/cli/src/code-mode/exec-tool.tsnew file mode 100644index 00000000..d839b1a5--- /dev/null+++ b/packages/cli/src/code-mode/exec-tool.ts@@ -0,0 +1,292 @@+/**+ * The exec tool: ONE freeform custom tool whose input is JavaScript that calls+ * Claude Code's tools as `tools.<Name>(args)`.+ *+ * The definition follows the official Codex client's (R1 §1c,+ * `evidence/r1/exec-tool.json`): `type: "custom"`, `name: "exec"`, the same+ * lark grammar (with its optional `// @exec:` first-line pragma), and a+ * description whose head explains the runtime, followed by one section per+ * nested tool in Codex's form:+ *+ * ### `Name`+ * <the tool's description>+ *+ * exec tool declaration:+ * ```ts+ * declare const tools: { Name(args: {…}): Promise<string>; };+ * ```+ *+ * The head lists only what claudish's sandbox implements (`text()`, `exit()`,+ * `tools`, `ALL_TOOLS`); Codex's `image()`, `store()`, `notify()`, timers and+ * yield are absent, so the model is never told about a helper that would throw.+ *+ * Sections are rendered from `claudeRequest.tools` AFTER Layer 4 (step 3c) has+ * rewritten descriptions, so names are Claude Code's own, never the step-5+ * encoded names. A size budget keeps the description bounded on sessions with+ * many MCP tools: a section is at most `perToolBytes` (its description is cut to+ * fit; the full text stays in `ALL_TOOLS`), sections are added in Claude Code's+ * order up to `totalBytes`, and the rest are listed as deferred tools by name+ * and first sentence. Every tool stays callable either way.+ */++import { log } from "../logger.js";+import { schemaToTs } from "./schema-to-ts.js";+import { ToolNameTable, normalizeToolIdent } from "./tool-names.js";++/** The exec tool's grammar, verbatim from the Codex client's definition. */+export const EXEC_TOOL_GRAMMAR =+ "\nstart: pragma_source | plain_source\npragma_source: PRAGMA_LINE NEWLINE SOURCE\nplain_source: SOURCE\n\nPRAGMA_LINE: /[ \\t]*\\/\\/ @exec:[^\\r\\n]*/\nNEWLINE: /\\r?\\n/\nSOURCE: /[\\s\\S]+/\n";++/** The exec tool's name on the wire. */+export const EXEC_TOOL_NAME = "exec";++/**+ * The output budget the exec description states when discovery publishes no+ * token truncation policy: the protocol default the Codex exec description+ * itself states ("Defaults to 10000 tokens"). A rule, not model data.+ */+export const DEFAULT_EXEC_MAX_OUTPUT_TOKENS = 10_000;++/** Description size limits (claudish policy; UTF-8 bytes). */+export interface ExecToolBudget {+ /** One nested tool's section, heading to closing fence. */+ perToolBytes: number;+ /** Every rendered section together. */+ totalBytes: number;+}++export const DEFAULT_EXEC_TOOL_BUDGET: ExecToolBudget = {+ perToolBytes: 6 * 1024,+ totalBytes: 48 * 1024,+};++/** The Responses custom tool definition sent upstream. */+export interface ExecToolDefinition {+ type: "custom";+ name: typeof EXEC_TOOL_NAME;+ description: string;+ format: { type: "grammar"; syntax: "lark"; definition: string };+}++/** One entry of the sandbox's `ALL_TOOLS` global. */+export interface ExecToolMeta {+ /** The identifier a script calls (`tools[name]`). */+ name: string;+ description: string;+ inputSchema: unknown;+}++export interface RenderedExecTool {+ tool: ExecToolDefinition;+ /** Identifier ↔ Claude Code name for every callable tool. */+ names: ToolNameTable;+ /** `ALL_TOOLS`: every callable tool with its full description and schema. */+ allTools: ExecToolMeta[];+ /** Claude Code names listed only under "Deferred tools" (over the budget). */+ deferred: string[];+}++/** A Claude Code tool as it arrives in `claudeRequest.tools`. */+export interface ClaudeToolLike {+ name?: unknown;+ description?: unknown;+ input_schema?: unknown;+}++export interface RenderExecToolOptions {+ /** The `max_output_tokens` default the description states. Default 10,000. */+ defaultMaxOutputTokens?: number;+}++function utf8Bytes(text: string): number {+ return Buffer.byteLength(text, "utf8");+}++/** `text` cut to at most `maxBytes` UTF-8 bytes at a line (else character) boundary. */+function cutToBytes(text: string, maxBytes: number): string {+ if (maxBytes <= 0) return "";+ if (utf8Bytes(text) <= maxBytes) return text;+ let lo = 0;+ let hi = text.length;+ while (lo < hi) {+ const mid = Math.ceil((lo + hi) / 2);+ if (utf8Bytes(text.slice(0, mid)) <= maxBytes) lo = mid;+ else hi = mid - 1;+ }+ const head = text.slice(0, lo);+ const nl = head.lastIndexOf("\n");+ return nl > head.length / 2 ? head.slice(0, nl) : head;+}++/** The first sentence (or first line) of a description, for the deferred list. */+function firstSentence(description: string): string {+ const line = description.trim().split(/\r?\n/)[0] ?? "";+ const match = /^(.+?[.!?])(\s|$)/.exec(line);+ const sentence = (match ? match[1] : line).trim();+ return sentence.length > 200 ? `${sentence.slice(0, 199)}…` : sentence;+}++function execToolHead(defaultMaxOutputTokens: number): string {+ return [+ "Run JavaScript code to orchestrate/compose tool calls",+ "- Evaluates the provided JavaScript code in a fresh sandbox as the body of an async function, so top-level `await` works.",+ '- All nested tools are available on the global `tools` object, for example `await tools.Read({ file_path: "/abs/path" })`. Tool names are exposed as normalized JavaScript identifiers.',+ "- Nested tool methods take an object as their input argument.",+ "- Nested tools return a string: the tool's result text. A failed or denied call rejects with a string (the tool's error text), so use `Promise.allSettled` to inspect every result.",+ "- Runs raw JavaScript -- no Node, no file system, no network access, no console, no timers.",+ "- Accepts raw JavaScript source text, not JSON, quoted strings, or markdown code fences.",+ '- You may optionally start the tool input with a first-line pragma like `// @exec: {"max_output_tokens": 1000}`.',+ `- \`max_output_tokens\` sets the token budget for direct \`exec\` results. Defaults to ${defaultMaxOutputTokens} tokens.`,+ "- When the script finishes, nested tool calls it never awaited are discarded and never run.",+ "",+ "- Global helpers:",+ "- `exit()`: Immediately ends the current script successfully (like an early return from the top level).",+ "- `text(value: string | number | boolean | undefined | null)`: Appends a text item. Non-string values are stringified with `JSON.stringify(...)` when possible.",+ "- `ALL_TOOLS`: metadata for the enabled nested tools as `{ name, description, inputSchema }` entries.",+ "",+ "Batch independent searches and reads in one exec using await Promise.allSettled([...]); inspect every result.",+ "When calling `exec`, parallelize independent tool calls by awaiting Promises.",+ ].join("\n");+}++function renderSection(ident: string, description: string, schema: unknown): string {+ const declaration = `declare const tools: { ${ident}(args: ${schemaToTs(schema)}): Promise<string>; };`;+ const body = description.trim();+ return [+ `### \`${ident}\``,+ ...(body ? [body] : []),+ "",+ "exec tool declaration:",+ "```ts",+ declaration,+ "```",+ ].join("\n");+}++/**+ * One section within `perToolBytes`: the full description when it fits, else+ * the description cut to fit with a pointer to `ALL_TOOLS`; undefined when the+ * declaration alone exceeds the budget (the tool is then deferred).+ */+function sectionWithinBudget(+ ident: string,+ description: string,+ schema: unknown,+ perToolBytes: number+): string | undefined {+ const full = renderSection(ident, description, schema);+ if (utf8Bytes(full) <= perToolBytes) return full;+ const bare = renderSection(ident, "", schema);+ const marker = "\n[description shortened; the full text is in ALL_TOOLS]";+ const room = perToolBytes - utf8Bytes(bare) - utf8Bytes(marker) - 1;+ if (room < 0) return undefined;+ const cut = cutToBytes(description.trim(), room);+ return renderSection(ident, cut ? `${cut}${marker}` : marker.trim(), schema);+}++/** The "Deferred tools" list: identifier and first sentence of each. */+function deferredSection(+ deferred: readonly string[],+ names: ToolNameTable,+ allTools: readonly ExecToolMeta[]+): string {+ const lines = deferred.map((name) => {+ const ident = names.identFor(name) ?? name;+ const meta = allTools.find((m) => m.name === ident);+ const sentence = firstSentence(meta?.description ?? "");+ return sentence ? `- \`${ident}\` — ${sentence}` : `- \`${ident}\``;+ });+ return `### Deferred tools\n${lines.join("\n")}`;+}++/**+ * Every callable tool's `ALL_TOOLS` entry, the sections that fit the budget,+ * and the names deferred past it.+ */+function layOutSections(+ named: ReadonlyArray<ClaudeToolLike & { name: string }>,+ names: ToolNameTable,+ limits: ExecToolBudget+): { sections: string[]; deferred: string[]; allTools: ExecToolMeta[] } {+ const sections: string[] = [];+ const deferred: string[] = [];+ // One entry per kept table name (a repeated name or a skipped collision is not callable).+ const seen = new Set<string>();+ const callable = named.filter((tool) => {+ if (seen.has(tool.name) || names.identFor(tool.name) === undefined) return false;+ seen.add(tool.name);+ return true;+ });+ const allTools: ExecToolMeta[] = callable.map((tool) => ({+ name: names.identFor(tool.name) ?? normalizeToolIdent(tool.name),+ description: typeof tool.description === "string" ? tool.description : "",+ inputSchema: tool.input_schema ?? {},+ }));+ let used = 0;+ let overflowed = false;++ for (const [i, tool] of callable.entries()) {+ const { name: ident, description, inputSchema } = allTools[i];+ const section = overflowed+ ? undefined+ : sectionWithinBudget(ident, description, inputSchema, limits.perToolBytes);+ const size = section === undefined ? 0 : utf8Bytes(section) + 2;+ if (section === undefined || used + size > limits.totalBytes) {+ // Claude Code's order is kept: once one section does not fit the total,+ // every later tool is deferred too. A tool whose declaration alone+ // exceeds the per-tool budget is deferred on its own.+ if (section !== undefined) overflowed = true;+ deferred.push(tool.name);+ continue;+ }+ sections.push(section);+ used += size;+ }+ return { sections, deferred, allTools };+}++/**+ * The exec tool for `tools` (Claude Code's tool list, in its order).+ *+ * Tools without a string name are ignored; a name whose identifier collides+ * with an earlier one is skipped (logged by `ToolNameTable`) and not callable.+ */+export function renderExecTool(+ tools: readonly ClaudeToolLike[],+ budget: Partial<ExecToolBudget> = {},+ options: RenderExecToolOptions = {}+): RenderedExecTool {+ const limits: ExecToolBudget = { ...DEFAULT_EXEC_TOOL_BUDGET, ...budget };+ const defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? DEFAULT_EXEC_MAX_OUTPUT_TOKENS;+ const named = tools.filter(+ (t): t is ClaudeToolLike & { name: string } => typeof t?.name === "string" && t.name !== ""+ );+ const names = new ToolNameTable(named.map((t) => t.name));+ const { sections, deferred, allTools } = layOutSections(named, names, limits);++ const parts = [execToolHead(defaultMaxOutputTokens)];+ if (deferred.length > 0) {+ parts.push(+ "Some deferred nested tools are omitted from this description. They are still available on the global `tools` object and listed in `ALL_TOOLS`.\nTo find one, filter `ALL_TOOLS` by `name` and `description`."+ );+ }+ parts.push(...sections);+ if (deferred.length > 0) {+ parts.push(deferredSection(deferred, names, allTools));+ log(+ `[CodeMode] exec tool: ${sections.length} tool(s) described, ${deferred.length} deferred over the ${limits.totalBytes}-byte budget`+ );+ }++ return {+ tool: {+ type: "custom",+ name: EXEC_TOOL_NAME,+ description: parts.join("\n\n"),+ format: { type: "grammar", syntax: "lark", definition: EXEC_TOOL_GRAMMAR },+ },+ names,+ allTools,+ deferred,+ };+}diff --git a/packages/cli/src/code-mode/schema-to-ts.ts b/packages/cli/src/code-mode/schema-to-ts.tsnew file mode 100644index 00000000..085feb76--- /dev/null+++ b/packages/cli/src/code-mode/schema-to-ts.ts@@ -0,0 +1,153 @@+/**+ * A tool's JSON Schema `input_schema` rendered as a TypeScript type, for the+ * `exec tool declaration:` block of the exec tool's description.+ *+ * The form follows the official Codex client's renderer (R1 §1c,+ * `render_json_schema_to_typescript`): each property's description becomes a+ * `//` comment above it, required properties are bare and optional ones carry+ * `?`. Supported: `enum`, `const`, `anyOf` / `oneOf` unions, type arrays,+ * arrays (and tuples), nested objects to a depth of 4, `additionalProperties`.+ * Anything else, and anything deeper, is `unknown` — the type is guidance for+ * the model; Claude Code validates the real call.+ */++/** Deepest object/array nesting rendered; below it a value is `unknown`. */+export const MAX_SCHEMA_DEPTH = 4;++type Schema = Record<string, unknown>;++const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;++function isSchema(value: unknown): value is Schema {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++function literal(value: unknown): string {+ if (value === null) return "null";+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {+ return JSON.stringify(value);+ }+ return "unknown";+}++function union(parts: string[]): string {+ const unique = [...new Set(parts)];+ if (unique.length === 0) return "unknown";+ if (unique.includes("unknown")) return "unknown";+ return unique.join(" | ");+}++function propertyKey(name: string): string {+ return IDENTIFIER.test(name) ? name : JSON.stringify(name);+}++function commentLines(description: unknown, pad: string): string[] {+ if (typeof description !== "string") return [];+ const text = description.trim();+ if (!text) return [];+ return text.split(/\r?\n/).map((line) => `${pad}// ${line.trimEnd()}`.trimEnd());+}++function renderObject(schema: Schema, depth: number, indent: number): string {+ const properties = isSchema(schema.properties) ? schema.properties : undefined;+ const additional = schema.additionalProperties;+ if (!properties) {+ if (isSchema(additional)) {+ return `Record<string, ${render(additional, depth + 1, indent)}>`;+ }+ return "Record<string, unknown>";+ }+ const names = Object.keys(properties);+ if (names.length === 0) return "{}";+ const required = new Set(+ Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []+ );+ const pad = " ".repeat(indent + 1);+ const lines: string[] = ["{"];+ for (const name of names) {+ const prop = properties[name];+ lines.push(...commentLines(isSchema(prop) ? prop.description : undefined, pad));+ const optional = required.has(name) ? "" : "?";+ lines.push(`${pad}${propertyKey(name)}${optional}: ${render(prop, depth + 1, indent + 1)};`);+ }+ if (isSchema(additional)) {+ lines.push(`${pad}[key: string]: ${render(additional, depth + 1, indent + 1)};`);+ }+ lines.push(`${" ".repeat(indent)}}`);+ return lines.join("\n");+}++function renderArray(schema: Schema, depth: number, indent: number): string {+ const tuple = Array.isArray(schema.prefixItems)+ ? schema.prefixItems+ : Array.isArray(schema.items)+ ? schema.items+ : undefined;+ if (tuple) {+ return `[${tuple.map((item) => render(item, depth + 1, indent)).join(", ")}]`;+ }+ if (schema.items === undefined) return "Array<unknown>";+ return `Array<${render(schema.items, depth + 1, indent)}>`;+}++function renderType(type: string, schema: Schema, depth: number, indent: number): string {+ switch (type) {+ case "string":+ return "string";+ case "number":+ case "integer":+ return "number";+ case "boolean":+ return "boolean";+ case "null":+ return "null";+ case "array":+ return renderArray(schema, depth, indent);+ case "object":+ return renderObject(schema, depth, indent);+ default:+ return "unknown";+ }+}++function render(schema: unknown, depth: number, indent: number): string {+ if (!isSchema(schema)) return "unknown";+ if (depth > MAX_SCHEMA_DEPTH) return "unknown";+ if ("const" in schema) return literal(schema.const);+ if (Array.isArray(schema.enum) && schema.enum.length > 0) {+ return union(schema.enum.map(literal));+ }+ const branches = Array.isArray(schema.anyOf)+ ? schema.anyOf+ : Array.isArray(schema.oneOf)+ ? schema.oneOf+ : undefined;+ if (branches && branches.length > 0) {+ return union(branches.map((branch) => render(branch, depth, indent)));+ }+ const type = schema.type;+ if (Array.isArray(type)) {+ return union(+ type+ .filter((t): t is string => typeof t === "string")+ .map((t) => renderType(t, schema, depth, indent))+ );+ }+ if (typeof type === "string") return renderType(type, schema, depth, indent);+ if (isSchema(schema.properties)) return renderObject(schema, depth, indent);+ if (schema.items !== undefined || Array.isArray(schema.prefixItems)) {+ return renderArray(schema, depth, indent);+ }+ return "unknown";+}++/**+ * `schema` as the TypeScript type of a nested tool's `args` parameter.+ * A schema that is not an object, or names no properties, renders as `{}` /+ * `Record<string, unknown>` (never a primitive: nested tools take an object).+ */+export function schemaToTs(schema: unknown): string {+ if (!isSchema(schema)) return "Record<string, unknown>";+ const rendered = render({ ...schema, type: "object" }, 1, 0);+ return rendered === "unknown" ? "Record<string, unknown>" : rendered;+}diff --git a/packages/cli/src/code-mode/tool-names.ts b/packages/cli/src/code-mode/tool-names.tsnew file mode 100644index 00000000..cfb68074--- /dev/null+++ b/packages/cli/src/code-mode/tool-names.ts@@ -0,0 +1,82 @@+/**+ * Claude Code tool names as JavaScript identifiers on the exec tool's `tools`+ * object.+ *+ * The official Codex client normalises a nested tool's name by replacing every+ * character outside `[A-Za-z0-9_$]` with `_` (a leading digit too), and when two+ * names collide the LATER one is skipped (R1 §1c,+ * `code-mode-protocol/src/description.rs`). claudish applies the same rule to+ * Claude Code's own tool names, so `mcp__my-server__run` is called as+ * `tools.mcp__my_server__run`, and keeps the table both ways: the identifier a+ * script calls, and the name the tool_use block must carry.+ */++import { log } from "../logger.js";++/** `name` as a JavaScript identifier: `[A-Za-z0-9_$]` kept, the rest `_`, no leading digit. */+export function normalizeToolIdent(name: string): string {+ let ident = name.replace(/[^A-Za-z0-9_$]/g, "_");+ if (ident === "") ident = "_";+ if (/^[0-9]/.test(ident)) ident = `_${ident.slice(1)}`;+ return ident;+}++/** One nested tool: the identifier a script calls and Claude Code's own name. */+export interface ToolNameEntry {+ ident: string;+ name: string;+}++/**+ * The identifier ↔ original-name table for one request's tool list, in Claude+ * Code's order. Built once per request from `claudeRequest.tools`.+ */+export class ToolNameTable {+ private readonly byIdent = new Map<string, ToolNameEntry>();+ private readonly byName = new Map<string, ToolNameEntry>();+ /** Names dropped because their identifier was already taken. */+ readonly skipped: string[] = [];++ constructor(names: readonly string[]) {+ for (const name of names) {+ if (typeof name !== "string" || name === "") continue;+ if (this.byName.has(name)) continue;+ const ident = normalizeToolIdent(name);+ const taken = this.byIdent.get(ident);+ if (taken) {+ this.skipped.push(name);+ log(+ `[CodeMode] tool ${JSON.stringify(name)} skipped: its identifier ${ident} is already ` ++ `taken by ${JSON.stringify(taken.name)}`+ );+ continue;+ }+ const entry: ToolNameEntry = { ident, name };+ this.byIdent.set(ident, entry);+ this.byName.set(name, entry);+ }+ }++ /** Every kept entry, in Claude Code's order. */+ entries(): ToolNameEntry[] {+ return [...this.byIdent.values()];+ }++ /** The identifier a script calls for Claude Code's `name`, or undefined (unknown or skipped). */+ identFor(name: string): string | undefined {+ return this.byName.get(name)?.ident;+ }++ /** Claude Code's name for the identifier `ident`, or undefined. */+ nameFor(ident: string): string | undefined {+ return this.byIdent.get(ident)?.name;+ }++ has(ident: string): boolean {+ return this.byIdent.has(ident);+ }++ get size(): number {+ return this.byIdent.size;+ }+}