Skip to content

Commit d6c6a31

Browse files
committed
fix(xai): restore Grok Responses tool compatibility
1 parent 03735ec commit d6c6a31

8 files changed

Lines changed: 714 additions & 20 deletions

File tree

‎src/adapters/base.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ export interface AdapterRequest {
7272
convertedRoutedCustomToolNames?: ReadonlySet<string>;
7373
/** Client tool-search names actually lowered to upstream function calls for this request. */
7474
convertedRoutedToolSearchNames?: ReadonlySet<string>;
75+
/** Upstream-only aliases for namespace tools flattened in this request. */
76+
convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string }>;
7577
/** Releases observation of a serialized request body after its final fetch attempt settles. */
7678
releaseBodyObservation?: () => void;
7779
/** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */

‎src/adapters/openai-responses.ts‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { modelRecordValue } from "../reasoning-effort";
1212
import type { TranslatorBudget } from "../lib/translator-budget";
1313
import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-compat";
1414
import { rewriteRoutedToolSearchForUpstream } from "../responses/tool-search-compat";
15+
import { rewriteRoutedNamespaceToolsForUpstream } from "../responses/namespace-tool-compat";
1516
import { openaiResponsesUrl } from "./openai-responses-url";
1617
import {
1718
createAdapterTierMetadata,
@@ -120,6 +121,52 @@ function stripInvalidItemIds(body: unknown): unknown {
120121
return changed ? { ...body, input } : body;
121122
}
122123

124+
/**
125+
* Codex attaches ChatGPT's private `external_web_access` policy bit to the public
126+
* `web_search` tool. Third-party Responses APIs enable browsing by the presence of the tool and
127+
* commonly reject the extra argument (xAI returns `Argument not supported:
128+
* external_web_access`). Keep the hosted tool and every public option, but remove only that
129+
* canonical-only hint before a routed request reaches a non-OpenAI gateway.
130+
*/
131+
function stripCanonicalWebSearchAccessHint(body: unknown): unknown {
132+
if (!isPlainObject(body)) return body;
133+
134+
const rewriteTools = (tools: unknown[]): unknown[] => {
135+
let changed = false;
136+
const rewritten = tools.map(tool => {
137+
if (
138+
!isPlainObject(tool)
139+
|| tool.type !== "web_search"
140+
|| !Object.hasOwn(tool, "external_web_access")
141+
) {
142+
return tool;
143+
}
144+
changed = true;
145+
const { external_web_access: _externalWebAccess, ...rest } = tool;
146+
return rest;
147+
});
148+
return changed ? rewritten : tools;
149+
};
150+
151+
let rewrittenBody = body;
152+
if (Array.isArray(body.tools)) {
153+
const tools = rewriteTools(body.tools);
154+
if (tools !== body.tools) rewrittenBody = { ...rewrittenBody, tools };
155+
}
156+
if (!Array.isArray(body.input)) return rewrittenBody;
157+
158+
let input: unknown[] | undefined;
159+
for (let index = 0; index < body.input.length; index += 1) {
160+
const item = body.input[index];
161+
if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) continue;
162+
const tools = rewriteTools(item.tools);
163+
if (tools === item.tools) continue;
164+
input ??= [...body.input];
165+
input[index] = { ...item, tools };
166+
}
167+
return input ? { ...rewrittenBody, input } : rewrittenBody;
168+
}
169+
123170
/**
124171
* When `store` is false, the upstream API does not persist response items. Any item ID
125172
* forwarded in `input` is then interpreted as a reference to a stored item that does not
@@ -1506,6 +1553,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
15061553
const forward = provider.authMode === "forward";
15071554
let convertedRoutedCustomToolNames: Set<string> | undefined;
15081555
let convertedRoutedToolSearchNames: Set<string> | undefined;
1556+
let convertedRoutedNamespaceToolAliases: Map<string, { namespace: string; name: string }> | undefined;
15091557
const unexpandedMiss = !!parsed.previousResponseId && parsed._previousResponseInputExpanded !== true;
15101558
let outBody = stripPreviousResponseId(
15111559
parsed._rawBody,
@@ -1572,6 +1620,17 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
15721620
outBody = rewritten.body;
15731621
convertedRoutedToolSearchNames = rewritten.names;
15741622
}
1623+
if (!isCanonicalOpenAiForwardProvider(provider)) {
1624+
// Codex 0.147 emits private namespace tool groups, while public/third-party Responses
1625+
// gateways accept only flat tool variants. Run after custom/tool-search lowering so
1626+
// namespace children already carry their final public kind before they are promoted.
1627+
const rewritten = rewriteRoutedNamespaceToolsForUpstream(outBody);
1628+
outBody = rewritten.body;
1629+
convertedRoutedNamespaceToolAliases = rewritten.aliases;
1630+
}
1631+
if (!isCanonicalOpenAiForwardProvider(provider)) {
1632+
outBody = stripCanonicalWebSearchAccessHint(outBody);
1633+
}
15751634
const sanitizedBody = normalizeToolSchemas(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody), { preserveRawReasoningContent: provider.preserveResponsesReasoningContent === true })))))));
15761635
const finalBody = stripDisabledReasoningSummaries(
15771636
normalizeConfiguredReasoningSummaryDelivery(sanitizedBody, provider, parsed.modelId),
@@ -1600,6 +1659,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
16001659
releaseBodyObservation,
16011660
...(convertedRoutedCustomToolNames ? { convertedRoutedCustomToolNames } : {}),
16021661
...(convertedRoutedToolSearchNames ? { convertedRoutedToolSearchNames } : {}),
1662+
...(convertedRoutedNamespaceToolAliases ? { convertedRoutedNamespaceToolAliases } : {}),
16031663
...(tierLog ? { tierLog } : {}),
16041664
};
16051665
},
Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
import { namespacedToolName } from "../types";
2+
import { collectResponsesToolGroups } from "./tool-groups";
3+
4+
export interface RoutedNamespaceToolIdentity {
5+
namespace: string;
6+
name: string;
7+
}
8+
9+
export type RoutedNamespaceToolAliases = ReadonlyMap<string, RoutedNamespaceToolIdentity>;
10+
11+
const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
12+
13+
function isPlainObject(value: unknown): value is Record<string, unknown> {
14+
return !!value && typeof value === "object" && !Array.isArray(value);
15+
}
16+
17+
function namespaceIdentity(namespace: string, name: string): string {
18+
return `${namespace}\u0000${name}`;
19+
}
20+
21+
function namespaceToolIdentity(tool: unknown): RoutedNamespaceToolIdentity | undefined {
22+
if (
23+
!isPlainObject(tool)
24+
|| tool.type !== "namespace"
25+
|| typeof tool.name !== "string"
26+
|| tool.name.length === 0
27+
|| !Array.isArray(tool.tools)
28+
|| tool.tools.length === 0
29+
) return undefined;
30+
return { namespace: tool.name, name: "" };
31+
}
32+
33+
function namespaceChildren(tool: unknown): Record<string, unknown>[] | undefined {
34+
const identity = namespaceToolIdentity(tool);
35+
if (!identity || !isPlainObject(tool) || !Array.isArray(tool.tools)) return undefined;
36+
const children: Record<string, unknown>[] = [];
37+
for (const child of tool.tools) {
38+
if (
39+
!isPlainObject(child)
40+
|| child.type === "namespace"
41+
|| typeof child.name !== "string"
42+
|| child.name.length === 0
43+
) return undefined;
44+
children.push(child);
45+
}
46+
return children;
47+
}
48+
49+
function addSelector(
50+
selectors: Map<string, string | null>,
51+
selector: string,
52+
wireName: string,
53+
): void {
54+
const current = selectors.get(selector);
55+
if (current === undefined) selectors.set(selector, wireName);
56+
else if (current !== wireName) selectors.set(selector, null);
57+
}
58+
59+
type NamespaceRewritePlan = {
60+
aliases: Map<string, RoutedNamespaceToolIdentity>;
61+
identities: Map<string, string>;
62+
selectors: Map<string, string | null>;
63+
};
64+
65+
function buildRewritePlan(groups: readonly unknown[][]): NamespaceRewritePlan {
66+
const aliases = new Map<string, RoutedNamespaceToolIdentity>();
67+
const identities = new Map<string, string>();
68+
const selectors = new Map<string, string | null>();
69+
const directNames = new Set<string>();
70+
71+
for (const group of groups) {
72+
for (const tool of group) {
73+
if (
74+
isPlainObject(tool)
75+
&& tool.type !== "namespace"
76+
&& typeof tool.name === "string"
77+
&& tool.name.length > 0
78+
) directNames.add(tool.name);
79+
}
80+
}
81+
82+
const wireOwners = new Map<string, string>();
83+
for (const name of directNames) wireOwners.set(name, `direct:${name}`);
84+
85+
for (const group of groups) {
86+
for (const tool of group) {
87+
const parent = namespaceToolIdentity(tool);
88+
const children = namespaceChildren(tool);
89+
if (!parent || !children) continue;
90+
for (const child of children) {
91+
const childName = child.name as string;
92+
const identity = namespaceIdentity(parent.namespace, childName);
93+
const wireName = parent.namespace === BUILTIN_FUNCTIONS_NAMESPACE
94+
? childName
95+
: namespacedToolName(parent.namespace, childName);
96+
const owner = wireOwners.get(wireName);
97+
if (owner !== undefined && owner !== identity) {
98+
throw new Error(
99+
`namespace tool wire-name collision for "${wireName}"; rename one of the colliding tools`,
100+
);
101+
}
102+
wireOwners.set(wireName, identity);
103+
identities.set(identity, wireName);
104+
addSelector(selectors, wireName, wireName);
105+
addSelector(selectors, `${parent.namespace}.${childName}`, wireName);
106+
addSelector(selectors, childName, wireName);
107+
if (parent.namespace !== BUILTIN_FUNCTIONS_NAMESPACE) {
108+
aliases.set(wireName, { namespace: parent.namespace, name: childName });
109+
}
110+
}
111+
}
112+
}
113+
114+
return { aliases, identities, selectors };
115+
}
116+
117+
function rewriteToolList(
118+
tools: unknown[],
119+
plan: NamespaceRewritePlan,
120+
): { tools: unknown[]; changed: boolean } {
121+
let changed = false;
122+
const rewritten: unknown[] = [];
123+
for (const tool of tools) {
124+
const parent = namespaceToolIdentity(tool);
125+
const children = namespaceChildren(tool);
126+
if (!parent || !children) {
127+
rewritten.push(tool);
128+
continue;
129+
}
130+
changed = true;
131+
for (const child of children) {
132+
const identity = namespaceIdentity(parent.namespace, child.name as string);
133+
const wireName = plan.identities.get(identity);
134+
rewritten.push(wireName && wireName !== child.name ? { ...child, name: wireName } : child);
135+
}
136+
}
137+
return changed ? { tools: rewritten, changed: true } : { tools, changed: false };
138+
}
139+
140+
function rewriteNamedSelector(value: unknown, plan: NamespaceRewritePlan): unknown {
141+
if (!isPlainObject(value) || typeof value.name !== "string") return value;
142+
const explicitNamespace = typeof value.namespace === "string" ? value.namespace : undefined;
143+
const wireName = explicitNamespace
144+
? plan.identities.get(namespaceIdentity(explicitNamespace, value.name))
145+
: plan.selectors.get(value.name) ?? undefined;
146+
if (!wireName) return value;
147+
const { namespace: _namespace, ...rest } = value;
148+
return wireName === value.name && explicitNamespace === undefined
149+
? value
150+
: { ...rest, name: wireName };
151+
}
152+
153+
function rewriteToolChoice(value: unknown, plan: NamespaceRewritePlan): unknown {
154+
if (!isPlainObject(value)) return value;
155+
if ((value.type === "function" || value.type === "custom") && typeof value.name === "string") {
156+
return rewriteNamedSelector(value, plan);
157+
}
158+
if (value.type !== "allowed_tools" || !Array.isArray(value.tools)) return value;
159+
let changed = false;
160+
const tools = value.tools.map(tool => {
161+
if (
162+
!isPlainObject(tool)
163+
|| (tool.type !== "function" && tool.type !== "custom")
164+
|| typeof tool.name !== "string"
165+
) return tool;
166+
const rewritten = rewriteNamedSelector(tool, plan);
167+
changed ||= rewritten !== tool;
168+
return rewritten;
169+
});
170+
return changed ? { ...value, tools } : value;
171+
}
172+
173+
function rewriteInputItem(item: unknown, plan: NamespaceRewritePlan): unknown {
174+
if (!isPlainObject(item)) return item;
175+
if (item.type === "additional_tools" && Array.isArray(item.tools)) {
176+
const rewritten = rewriteToolList(item.tools, plan);
177+
return rewritten.changed ? { ...item, tools: rewritten.tools } : item;
178+
}
179+
if (
180+
(item.type === "function_call" || item.type === "custom_tool_call")
181+
&& typeof item.name === "string"
182+
) return rewriteNamedSelector(item, plan);
183+
return item;
184+
}
185+
186+
/**
187+
* Lower Codex's private Responses namespace declarations for public/third-party gateways.
188+
*
189+
* Codex 0.147 groups ordinary tools under the reserved `functions` namespace; those children
190+
* become bare top-level declarations. Other namespaces use the same collision-checked
191+
* `<namespace>__<name>` wire identity as the chat adapters. The returned request-local aliases
192+
* are the only names response restoration is allowed to expand.
193+
*/
194+
export function rewriteRoutedNamespaceToolsForUpstream(body: unknown): {
195+
body: unknown;
196+
aliases: Map<string, RoutedNamespaceToolIdentity>;
197+
} {
198+
if (!isPlainObject(body)) return { body, aliases: new Map() };
199+
const groups = collectResponsesToolGroups(body);
200+
const plan = buildRewritePlan(groups);
201+
if (plan.identities.size === 0) return { body, aliases: plan.aliases };
202+
203+
let tools = body.tools;
204+
if (Array.isArray(body.tools)) tools = rewriteToolList(body.tools, plan).tools;
205+
206+
let input = body.input;
207+
if (Array.isArray(body.input)) input = body.input.map(item => rewriteInputItem(item, plan));
208+
209+
const toolChoice = rewriteToolChoice(body.tool_choice, plan);
210+
return {
211+
body: {
212+
...body,
213+
...(tools !== body.tools ? { tools } : {}),
214+
...(input !== body.input ? { input } : {}),
215+
...(toolChoice !== body.tool_choice ? { tool_choice: toolChoice } : {}),
216+
},
217+
aliases: plan.aliases,
218+
};
219+
}
220+
221+
export function restoreRoutedNamespaceCalls(
222+
value: unknown,
223+
aliases: RoutedNamespaceToolAliases,
224+
): { value: unknown; changed: boolean } {
225+
if (Array.isArray(value)) {
226+
let changed = false;
227+
const restored = value.map(entry => {
228+
const result = restoreRoutedNamespaceCalls(entry, aliases);
229+
changed ||= result.changed;
230+
return result.value;
231+
});
232+
return changed ? { value: restored, changed: true } : { value, changed: false };
233+
}
234+
if (!isPlainObject(value)) return { value, changed: false };
235+
236+
let changed = false;
237+
const restored: Record<string, unknown> = {};
238+
for (const [key, entry] of Object.entries(value)) {
239+
const result = restoreRoutedNamespaceCalls(entry, aliases);
240+
restored[key] = result.value;
241+
changed ||= result.changed;
242+
}
243+
244+
if (
245+
(value.type === "function_call" || value.type === "custom_tool_call")
246+
&& typeof value.name === "string"
247+
) {
248+
const identity = aliases.get(value.name);
249+
if (identity) {
250+
restored.name = identity.name;
251+
restored.namespace = identity.namespace;
252+
changed = true;
253+
}
254+
}
255+
return changed ? { value: restored, changed: true } : { value, changed: false };
256+
}
257+
258+
export function restoreRoutedNamespaceCallsInJson(
259+
text: string,
260+
aliases: RoutedNamespaceToolAliases,
261+
): string {
262+
if (aliases.size === 0) return text;
263+
let payload: unknown;
264+
try {
265+
payload = JSON.parse(text);
266+
} catch {
267+
return text;
268+
}
269+
const restored = restoreRoutedNamespaceCalls(payload, aliases);
270+
return restored.changed ? JSON.stringify(restored.value) : text;
271+
}
272+
273+
export function createRoutedNamespaceCallRestoreRewrite(
274+
aliases: RoutedNamespaceToolAliases,
275+
): (payload: string) => string {
276+
return payload => restoreRoutedNamespaceCallsInJson(payload, aliases);
277+
}

0 commit comments

Comments
 (0)