Skip to content

Commit 5f2b939

Browse files
committed
responses: flatten Codex 0.147 built-in functions namespace in parser
Codex 0.147 groups its ordinary client tools under the reserved `functions` namespace, including freeform custom tools such as code-mode `exec`. Flatten those children as top-level tools (no namespace) and lower nested custom tools the same way as top-level ones; other namespace groups keep MCP-style round-trip routing. Extracted from PR #1896 (credit: original author of #1896). The code-mode rejection-guidance changes with hardcoded exec / mcp_opencodex-responses_* name lists were intentionally dropped; a catalog-helper approach will follow separately.
1 parent 542ea37 commit 5f2b939

2 files changed

Lines changed: 59 additions & 16 deletions

File tree

‎src/responses/parser.ts‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,23 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
169169
if (namespace) tool.namespace = namespace;
170170
out.push(tool);
171171
};
172+
const pushCustom = (t: Record<string, unknown>, namespace?: string) => {
173+
// Freeform custom tools are lowered to a single string `input` because chat models cannot
174+
// emit Responses grammar payloads directly. Keep tool-specific input guidance scoped to the
175+
// tool that owns it: leaking apply_patch syntax into `exec` or another freeform tool teaches
176+
// routed models that the nested helper name is itself a callable top-level tool.
177+
const inputDescription = t.name === "apply_patch"
178+
? "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope."
179+
: "Raw freeform input for this tool.";
180+
const tool: OcxTool = {
181+
name: t.name as string,
182+
description: (t.description as string) ?? "",
183+
parameters: { type: "object", properties: { input: { type: "string", description: inputDescription } }, required: ["input"] },
184+
freeform: true,
185+
};
186+
if (namespace) tool.namespace = namespace;
187+
out.push(tool);
188+
};
172189
for (const t of tools) {
173190
if (!isObj(t)) continue;
174191
if (t.type === "function" && isObj(t.function) && typeof t.function.name === "string" && t.function.name.length > 0) {
@@ -178,27 +195,19 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
178195
if (t.type === "function" && typeof t.name === "string") {
179196
pushFn(t);
180197
} else if (t.type === "namespace" && Array.isArray(t.tools)) {
181-
// MCP tools arrive grouped under a namespace tool; flatten the inner function tools so
182-
// chat-completions models receive them (round-trip restores the namespace in the bridge).
183-
const ns = typeof t.name === "string" ? t.name : undefined;
198+
// Codex 0.147 groups its ordinary client tools under the reserved `functions` namespace,
199+
// including freeform custom tools such as code-mode `exec`. Those children are still
200+
// top-level Responses tools, so flatten them without a namespace. Other namespace groups
201+
// are MCP-style and keep their namespace for round-trip routing.
202+
const builtinFunctions = t.name === "functions";
203+
const ns = typeof t.name === "string" && !builtinFunctions ? t.name : undefined;
184204
for (const inner of t.tools as unknown[]) {
185205
if (isObj(inner) && inner.type === "function" && typeof inner.name === "string") pushFn(inner, ns);
206+
else if (builtinFunctions && isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner);
186207
}
187208
}
188209
else if (t.type === "custom" && typeof t.name === "string") {
189-
// Freeform custom tools are lowered to a single string `input` because chat models cannot
190-
// emit Responses grammar payloads directly. Keep tool-specific input guidance scoped to the
191-
// tool that owns it: leaking apply_patch syntax into `exec` or another freeform tool teaches
192-
// routed models that the nested helper name is itself a callable top-level tool.
193-
const inputDescription = t.name === "apply_patch"
194-
? "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope."
195-
: "Raw freeform input for this tool.";
196-
out.push({
197-
name: t.name,
198-
description: (t.description as string) ?? "",
199-
parameters: { type: "object", properties: { input: { type: "string", description: inputDescription } }, required: ["input"] },
200-
freeform: true,
201-
});
210+
pushCustom(t);
202211
}
203212
else if (t.type === "tool_search") {
204213
// Client-executed tool discovery — the gateway to deferred tools (subagents, extra MCP tools).

‎tests/responses-tool-conformance.test.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { describe, expect, it } from "bun:test";
22
import { parseRequest } from "../src/responses/parser";
3+
import { cursorRequestUsesCodeMode } from "../src/adapters/cursor/tool-definitions";
34
import type { AdapterEvent } from "../src/types";
45
import { jsonItemTypes, jsonToolItems, streamedView } from "./helpers/responses-conformance";
56

@@ -64,6 +65,39 @@ describe("Responses Lite additional_tools declaration merge", () => {
6465
expect(parsed.context.tools?.find(tool => tool.name === "search")?.namespace).toBe("github");
6566
});
6667

68+
it("flattens Codex 0.147 built-in functions and preserves nested custom exec", () => {
69+
const parsed = parseRequest(request([
70+
{
71+
type: "additional_tools",
72+
role: "developer",
73+
tools: [
74+
{
75+
type: "namespace",
76+
name: "functions",
77+
tools: [
78+
{ type: "custom", name: "exec", description: "Run JavaScript with nested helpers." },
79+
{ type: "function", name: "wait", parameters: { type: "object", properties: {} } },
80+
],
81+
},
82+
{
83+
type: "namespace",
84+
name: "collaboration",
85+
tools: [{ type: "function", name: "spawn_agent", parameters: { type: "object", properties: {} } }],
86+
},
87+
],
88+
},
89+
]));
90+
91+
const exec = parsed.context.tools?.find(tool => tool.name === "exec");
92+
const wait = parsed.context.tools?.find(tool => tool.name === "wait");
93+
const spawn = parsed.context.tools?.find(tool => tool.name === "spawn_agent");
94+
expect(exec).toMatchObject({ name: "exec", freeform: true });
95+
expect(exec?.namespace).toBeUndefined();
96+
expect(wait?.namespace).toBeUndefined();
97+
expect(spawn?.namespace).toBe("collaboration");
98+
expect(cursorRequestUsesCodeMode(parsed.context.tools)).toBe(true);
99+
});
100+
67101
it("preserves wire order across multiple additional_tools groups", () => {
68102
const parsed = parseRequest(request([
69103
{ type: "additional_tools", role: "developer", tools: [fnTool] },

0 commit comments

Comments
 (0)