Skip to content

Commit a3df535

Browse files
committed
fix(responses): bridge routed tool search passthrough
1 parent 69650fa commit a3df535

13 files changed

Lines changed: 710 additions & 11 deletions

File tree

‎docs-site/src/content/docs/ja/reference/adapters.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ interface ProviderAdapter {
4646
**対象:** OpenAI **Responses API**。**`passthrough: true`** — 元のリクエスト本文をそのまま渡し、レスポンスを **変換せずに** ストリーミングします。
4747
**認証:** `forward`(呼び出し元ヘッダー中継)または `key`。
4848

49+
非 canonical な Responses ゲートウェイには、Codex のクライアント実行型 `tool_search`
50+
宣言を公開 function tool として送り、対応する JSON/SSE function call をクライアント向けの
51+
`tool_search_call` に復元します。canonical OpenAI forward はネイティブな非公開型を維持します。
52+
4953
`key` 認証では、[`retryOn429`](/ja/reference/configuration/) もここに適用されます: プリストリームの
5054
429 は、翻訳された `openai-chat` / Anthropic リクエスト経路と同様に、他の処理やフェイルオーバーに
5155
先立って、同じキーで同一リクエストを待機して再送します。カスタム `runTurn` トランスポートは

‎docs-site/src/content/docs/ko/reference/adapters.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ interface ProviderAdapter {
5353
**변환하지 않은 채** 스트리밍합니다.
5454
**인증:** `forward`(호출자 헤더 중계) 또는 `key`.
5555

56+
비정규 Responses 게이트웨이에는 Codex의 클라이언트 실행형 `tool_search` 선언을 공개 function
57+
도구로 전달하고, 일치하는 JSON/SSE function call을 클라이언트용 `tool_search_call`로 복원합니다.
58+
정규 OpenAI forward 경로는 네이티브 비공개 타입을 그대로 유지합니다.
59+
5660
`key` 인증에서는 [`retryOn429`](/ko/reference/configuration/)도 여기에 적용됩니다: 사전 스트림
5761
429는 번역된 `openai-chat`/Anthropic 요청 경로와 동일하게 다른 처리나 페일오버보다 먼저
5862
같은 키로 동일 요청을 대기 후 재전송합니다. 커스텀 `runTurn` 전송은 HTTP 재시도 루프에

‎docs-site/src/content/docs/reference/adapters.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ provider — xAI, Kimi, DeepSeek, GLM, Groq, OpenRouter, Ollama (local & cloud),
5353
streams the response back **untranslated**.
5454
**Auth:** `forward` (relay the caller's headers) or `key`.
5555

56+
Noncanonical Responses gateways receive Codex's client-executed `tool_search` declaration as a
57+
public function tool, and matching JSON/SSE function calls are restored to `tool_search_call` for
58+
the client. Canonical OpenAI forward keeps the native private type unchanged.
59+
5660
For `key` auth, [`retryOn429`](/reference/configuration/) applies here too: a pre-stream 429
5761
waits and replays the identical request on the same key before any other handling, exactly like
5862
the translated `openai-chat` / Anthropic request path. Custom `runTurn` transports are not part

‎docs-site/src/content/docs/zh-cn/reference/adapters.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ interface ProviderAdapter {
4949
**不经转换**地流式传回。
5050
**认证:** `forward`(转发调用方 header)或 `key`。
5151

52+
对于非规范 Responses 网关,Codex 的客户端执行型 `tool_search` 声明会作为公共 function tool
53+
发送;匹配的 JSON/SSE function call 会在返回客户端前恢复为 `tool_search_call`。规范 OpenAI
54+
forward 路径仍保持原生私有类型不变。
55+
5256
使用 `key` 认证时,[`retryOn429`](/zh-cn/reference/configuration/) 同样适用:流开始前的 429
5357
会等待并先于其他处理或故障转移,在相同 key 上重放完全相同请求,与翻译后的
5458
`openai-chat`/Anthropic 请求路径一致。自定义 `runTurn` 传输不在 HTTP 重试循环之内。

‎src/adapters/base.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ export interface AdapterRequest {
5252
body: string;
5353
/** Custom-tool names actually lowered to upstream function calls while building this request. */
5454
convertedRoutedCustomToolNames?: ReadonlySet<string>;
55+
/** Client tool-search names actually lowered to upstream function calls for this request. */
56+
convertedRoutedToolSearchNames?: ReadonlySet<string>;
5557
/** Releases observation of a serialized request body after its final fetch attempt settles. */
5658
releaseBodyObservation?: () => void;
5759
/** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */

‎src/adapters/openai-responses.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import { OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
1111
import { modelRecordValue } from "../reasoning-effort";
1212
import type { TranslatorBudget } from "../lib/translator-budget";
1313
import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-compat";
14+
import { rewriteRoutedToolSearchForUpstream } from "../responses/tool-search-compat";
1415
import { openaiResponsesUrl } from "./openai-responses-url";
1516
import {
1617
createAdapterTierMetadata,
@@ -1468,6 +1469,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
14681469

14691470
const forward = provider.authMode === "forward";
14701471
let convertedRoutedCustomToolNames: Set<string> | undefined;
1472+
let convertedRoutedToolSearchNames: Set<string> | undefined;
14711473
const unexpandedMiss = !!parsed.previousResponseId && parsed._previousResponseInputExpanded !== true;
14721474
let outBody = stripPreviousResponseId(
14731475
parsed._rawBody,
@@ -1516,6 +1518,9 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
15161518
}
15171519
if (!isCanonicalOpenAiForwardProvider(provider)) {
15181520
outBody = promoteClientLoadedTools(outBody);
1521+
const rewritten = rewriteRoutedToolSearchForUpstream(outBody);
1522+
outBody = rewritten.body;
1523+
convertedRoutedToolSearchNames = rewritten.names;
15191524
}
15201525
if (provider.authMode !== "forward") {
15211526
const rewritten = rewriteRoutedCustomToolsForUpstream(outBody);
@@ -1549,6 +1554,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
15491554
body,
15501555
releaseBodyObservation,
15511556
...(convertedRoutedCustomToolNames ? { convertedRoutedCustomToolNames } : {}),
1557+
...(convertedRoutedToolSearchNames ? { convertedRoutedToolSearchNames } : {}),
15521558
...(tierLog ? { tierLog } : {}),
15531559
};
15541560
},

‎src/responses/parser.ts‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import { previousResponseReplayPrefixLength } from "./state";
2020
import { decodeReasoningEnvelope } from "./reasoning-envelope";
2121
import { extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "../web-search/synthetic-tool";
2222
import { extractHostedImageGeneration, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
23+
import { toolSearchDescription, toolSearchParameters } from "./tool-search-compat";
2324

2425
function isObj(v: unknown): v is Record<string, unknown> {
2526
return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -214,15 +215,8 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
214215
// Expose as a function so chat models can call it; the bridge relays it as a tool_search_call.
215216
out.push({
216217
name: "tool_search",
217-
description: (t.description as string) ?? "Search for additional tools to load for the next turn.",
218-
parameters: (isObj(t.parameters) ? t.parameters : {
219-
type: "object",
220-
properties: {
221-
query: { type: "string", description: "Search query for tools to load." },
222-
limit: { type: "number", description: "Maximum number of tools to return." },
223-
},
224-
required: ["query"],
225-
}) as Record<string, unknown>,
218+
description: toolSearchDescription(t),
219+
parameters: toolSearchParameters(t),
226220
toolSearch: true,
227221
});
228222
}
Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
export const TOOL_SEARCH_FUNCTION_NAME = "tool_search";
2+
export const TOOL_SEARCH_DEFAULT_DESCRIPTION = "Search for additional tools to load for the next turn.";
3+
4+
function isPlainObject(value: unknown): value is Record<string, unknown> {
5+
return !!value && typeof value === "object" && !Array.isArray(value);
6+
}
7+
8+
export function toolSearchDescription(tool: unknown): string {
9+
return isPlainObject(tool) && typeof tool.description === "string"
10+
? tool.description
11+
: TOOL_SEARCH_DEFAULT_DESCRIPTION;
12+
}
13+
14+
export function toolSearchParameters(tool: unknown): Record<string, unknown> {
15+
if (isPlainObject(tool) && isPlainObject(tool.parameters)) return tool.parameters;
16+
// Fresh per parse/build: downstream normalizers are allowed to clone or extend schemas, and a
17+
// shared mutable default would couple otherwise unrelated requests.
18+
return {
19+
type: "object",
20+
properties: {
21+
query: { type: "string", description: "Search query for tools to load." },
22+
limit: { type: "number", description: "Maximum number of tools to return." },
23+
},
24+
required: ["query"],
25+
};
26+
}
27+
28+
function rewriteToolList(tools: unknown[]): { tools: unknown[]; changed: boolean } {
29+
let changed = false;
30+
const rewritten = tools.map(tool => {
31+
if (!isPlainObject(tool) || tool.type !== "tool_search") return tool;
32+
const {
33+
execution: _execution,
34+
defer_loading: _deferLoading,
35+
...rest
36+
} = tool;
37+
changed = true;
38+
return {
39+
...rest,
40+
type: "function",
41+
name: TOOL_SEARCH_FUNCTION_NAME,
42+
description: toolSearchDescription(tool),
43+
parameters: toolSearchParameters(tool),
44+
};
45+
});
46+
return changed ? { tools: rewritten, changed: true } : { tools, changed: false };
47+
}
48+
49+
function rewriteToolChoice(choice: unknown): unknown {
50+
if (!isPlainObject(choice)) return choice;
51+
if (choice.type === "tool_search") {
52+
return { type: "function", name: TOOL_SEARCH_FUNCTION_NAME };
53+
}
54+
if (choice.type !== "allowed_tools" || !Array.isArray(choice.tools)) return choice;
55+
let changed = false;
56+
const tools = choice.tools.map(tool => {
57+
if (!isPlainObject(tool) || tool.type !== "tool_search") return tool;
58+
changed = true;
59+
return { type: "function", name: TOOL_SEARCH_FUNCTION_NAME };
60+
});
61+
return changed ? { ...choice, tools } : choice;
62+
}
63+
64+
/**
65+
* Third-party Responses gateways generally implement the public function-tool schema, not Codex's
66+
* private client-executed `tool_search` declaration. Lower only request catalogs sent to a
67+
* noncanonical upstream; the caller-facing response is restored separately.
68+
*/
69+
export function rewriteRoutedToolSearchForUpstream(body: unknown): {
70+
body: unknown;
71+
names: Set<string>;
72+
} {
73+
const names = new Set<string>();
74+
if (!isPlainObject(body)) return { body, names };
75+
76+
let tools = body.tools;
77+
if (Array.isArray(tools)) {
78+
const result = rewriteToolList(tools);
79+
tools = result.tools;
80+
if (result.changed) names.add(TOOL_SEARCH_FUNCTION_NAME);
81+
}
82+
83+
let input = body.input;
84+
if (Array.isArray(input)) {
85+
input = input.map(item => {
86+
if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) {
87+
return item;
88+
}
89+
const result = rewriteToolList(item.tools);
90+
if (!result.changed) return item;
91+
names.add(TOOL_SEARCH_FUNCTION_NAME);
92+
return { ...item, tools: result.tools };
93+
});
94+
}
95+
96+
if (names.size === 0) return { body, names };
97+
const toolChoice = rewriteToolChoice(body.tool_choice);
98+
return {
99+
body: {
100+
...body,
101+
...(tools !== body.tools ? { tools } : {}),
102+
...(input !== body.input ? { input } : {}),
103+
...(toolChoice !== body.tool_choice ? { tool_choice: toolChoice } : {}),
104+
},
105+
names,
106+
};
107+
}
108+
109+
export function toolSearchItemId(id: unknown): unknown {
110+
if (typeof id !== "string") return id;
111+
return id.startsWith("fc_") ? `tsc_${id.slice(3)}` : id;
112+
}
113+
114+
function toolSearchArguments(value: unknown): Record<string, unknown> {
115+
if (isPlainObject(value)) return value;
116+
if (typeof value !== "string" || value.length === 0) return {};
117+
try {
118+
const parsed: unknown = JSON.parse(value);
119+
return isPlainObject(parsed) ? parsed : {};
120+
} catch {
121+
return {};
122+
}
123+
}
124+
125+
export function restoreRoutedToolSearchCalls(
126+
value: unknown,
127+
names: ReadonlySet<string>,
128+
): { value: unknown; changed: boolean } {
129+
if (Array.isArray(value)) {
130+
let changed = false;
131+
const restored = value.map(entry => {
132+
const result = restoreRoutedToolSearchCalls(entry, names);
133+
changed ||= result.changed;
134+
return result.value;
135+
});
136+
return changed ? { value: restored, changed: true } : { value, changed: false };
137+
}
138+
if (!isPlainObject(value)) return { value, changed: false };
139+
140+
let changed = false;
141+
const restored: Record<string, unknown> = {};
142+
for (const [key, entry] of Object.entries(value)) {
143+
const result = restoreRoutedToolSearchCalls(entry, names);
144+
restored[key] = result.value;
145+
changed ||= result.changed;
146+
}
147+
148+
if (value.type === "function_call" && typeof value.name === "string" && names.has(value.name)) {
149+
restored.type = "tool_search_call";
150+
restored.id = toolSearchItemId(value.id);
151+
restored.execution = "client";
152+
restored.arguments = toolSearchArguments(value.arguments);
153+
delete restored.name;
154+
changed = true;
155+
}
156+
return changed ? { value: restored, changed: true } : { value, changed: false };
157+
}
158+
159+
export function restoreRoutedToolSearchCallsInJson(
160+
text: string,
161+
names: ReadonlySet<string>,
162+
): string {
163+
if (names.size === 0) return text;
164+
let payload: unknown;
165+
try {
166+
payload = JSON.parse(text);
167+
} catch {
168+
return text;
169+
}
170+
const restored = restoreRoutedToolSearchCalls(payload, names);
171+
return restored.changed ? JSON.stringify(restored.value) : text;
172+
}

0 commit comments

Comments
 (0)