Skip to content

Commit 82ec47f

Browse files
committed
feat(claude): translate web_search_call frames to server_tool_use + web_search_tool_result
Claude Code showed 'Did 0 searches' because outbound dropped web_search_call frames. Emit the Anthropic pair (server_tool_use w/ input_json_delta query + web_search_tool_result w/ hits or error object) in SSE, JSON, and collector paths; count completed searches in usage.server_tool_use.web_search_requests; bridge attaches sources to the done item (additive, codex-rs-safe). WP1 of cross-vendor sidecar matrix (devlog 260712_claudecode_websearch/04).
1 parent 862e0ea commit 82ec47f

3 files changed

Lines changed: 225 additions & 7 deletions

File tree

‎src/bridge.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -379,11 +379,14 @@ export function bridgeToResponsesSSE(
379379
// Finalize an open web-search cell. `status` is "completed" on a normal end, or "failed" when
380380
// the stream terminates (error/incomplete) while a search was still in flight, so Codex never
381381
// leaves a "Searching the web" spinner spinning forever.
382-
const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[]) => {
382+
// `sources` rides on the done item (additive field; codex-rs serde ignores unknown fields) so
383+
// downstream translators (claude outbound) can fill web_search_tool_result content.
384+
const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[]) => {
383385
if (!currentWebSearch) return;
384386
const item = {
385387
type: "web_search_call", id: currentWebSearch.itemId, status,
386388
action: webSearchAction(queries),
389+
...(sources && sources.length > 0 ? { sources } : {}),
387390
};
388391
emit("response.output_item.done", { output_index: currentWebSearch.outputIndex, item });
389392
finishedItems.push(item as OutputItem);
@@ -569,7 +572,7 @@ export function bridgeToResponsesSSE(
569572
});
570573
currentWebSearch = { itemId: event.id, outputIndex };
571574
}
572-
closeCurrentWebSearch(event.status ?? "completed", event.queries);
575+
closeCurrentWebSearch(event.status ?? "completed", event.queries, event.sources);
573576
// Queue this search's sources for the next assistant message (dedup by URL).
574577
if (event.sources) {
575578
const seen = new Set(pendingWebSources.map(s => s.url));
@@ -861,6 +864,7 @@ export function buildResponseJSON(
861864
output.push({
862865
type: "web_search_call", id: e.id, status: e.status ?? "completed",
863866
action: webSearchAction(e.queries),
867+
...(e.sources && e.sources.length > 0 ? { sources: e.sources } : {}),
864868
});
865869
if (e.sources) {
866870
const seen = new Set(pendingWebSources.map(s => s.url));

‎src/claude/outbound.ts‎

Lines changed: 77 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ export function anthropicErrorResponse(status: number, message: string, type?: s
5454
* subtract the full cache detail (devlog 070 — subtracting reads only inflated the
5555
* non-cached input Claude Code displays by the write share).
5656
*/
57-
export function anthropicUsage(usage: unknown): Rec {
57+
export function anthropicUsage(usage: unknown, webSearchRequests = 0): Rec {
5858
const u = isRec(usage) ? usage : {};
5959
const details = isRec(u.input_tokens_details) ? u.input_tokens_details : {};
6060
const cached = typeof details.cached_tokens === "number" ? details.cached_tokens : 0;
@@ -66,13 +66,46 @@ export function anthropicUsage(usage: unknown): Rec {
6666
output_tokens: output,
6767
cache_read_input_tokens: cached,
6868
cache_creation_input_tokens: cacheWrite,
69+
// Only successful searches are billed/counted (Anthropic contract; Claude Code cost accounting).
70+
...(webSearchRequests > 0 ? { server_tool_use: { web_search_requests: webSearchRequests } } : {}),
6971
};
7072
}
7173

7274
function sseFrame(name: string, data: Rec): string {
7375
return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
7476
}
7577

78+
/**
79+
* Map a Responses `web_search_call` item to its Anthropic pair: the server_tool_use
80+
* input (query/queries) and the web_search_tool_result content (hits, or the error
81+
* object when the search failed). Shared by the SSE and JSON translation paths.
82+
*/
83+
function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
84+
const action = isRec(item.action) ? item.action : {};
85+
const queries = Array.isArray(action.queries)
86+
? action.queries.filter((q): q is string => typeof q === "string" && q.length > 0)
87+
: [];
88+
const query = typeof action.query === "string" ? action.query : "";
89+
const input: Rec = queries.length > 1 ? { queries } : { query: queries[0] ?? query };
90+
const completed = item.status !== "failed";
91+
let resultContent: unknown;
92+
if (completed) {
93+
const hits: Rec[] = [];
94+
if (Array.isArray(item.sources)) {
95+
for (const s of item.sources) {
96+
if (isRec(s) && typeof s.url === "string" && s.url.length > 0) {
97+
hits.push({ type: "web_search_result", title: typeof s.title === "string" ? s.title : "", url: s.url });
98+
}
99+
}
100+
}
101+
resultContent = hits;
102+
} else {
103+
resultContent = { type: "web_search_tool_result_error", error_code: "unavailable" };
104+
}
105+
const id = typeof item.id === "string" && item.id.length > 0 ? item.id : `srvtoolu_${uuid()}`;
106+
return { id, input, resultContent, completed };
107+
}
108+
76109
function messageSnapshot(model: string): Rec {
77110
return {
78111
id: `msg_${uuid()}`,
@@ -109,6 +142,7 @@ export function responsesSseToAnthropicSse(
109142
let blockIndex = 0;
110143
let open: OpenBlock | null = null;
111144
let sawToolUse = false;
145+
let webSearchRequests = 0;
112146
let pingTimer: ReturnType<typeof setInterval> | undefined;
113147
let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
114148

@@ -164,7 +198,7 @@ export function responsesSseToAnthropicSse(
164198
emit("message_delta", {
165199
type: "message_delta",
166200
delta: { stop_reason: stopReason, stop_sequence: null },
167-
usage: anthropicUsage(usage),
201+
usage: anthropicUsage(usage, webSearchRequests),
168202
});
169203
emit("message_stop", { type: "message_stop" });
170204
};
@@ -234,7 +268,35 @@ export function responsesSseToAnthropicSse(
234268
}
235269
case "response.output_item.done": {
236270
const item = isRec(data.item) ? data.item : null;
237-
if (!open || !item) break;
271+
if (!item) break;
272+
// Server-side web search (native passthrough or sidecar bridge): translate the
273+
// finished call into the Anthropic pair Claude Code natively parses —
274+
// server_tool_use (query via input_json_delta) + web_search_tool_result.
275+
// Never marks sawToolUse (stop_reason stays end_turn unless a real tool ran).
276+
if (item.type === "web_search_call") {
277+
ensureStarted();
278+
closeOpenBlock();
279+
const pair = webSearchPairFromItem(item);
280+
const toolIndex = blockIndex++;
281+
emit("content_block_start", {
282+
type: "content_block_start", index: toolIndex,
283+
content_block: { type: "server_tool_use", id: pair.id, name: "web_search" },
284+
});
285+
emit("content_block_delta", {
286+
type: "content_block_delta", index: toolIndex,
287+
delta: { type: "input_json_delta", partial_json: JSON.stringify(pair.input) },
288+
});
289+
emit("content_block_stop", { type: "content_block_stop", index: toolIndex });
290+
const resultIndex = blockIndex++;
291+
emit("content_block_start", {
292+
type: "content_block_start", index: resultIndex,
293+
content_block: { type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent },
294+
});
295+
emit("content_block_stop", { type: "content_block_stop", index: resultIndex });
296+
if (pair.completed) webSearchRequests++;
297+
break;
298+
}
299+
if (!open) break;
238300
// Close the matching open block (message/reasoning items close implicitly on
239301
// the next block; function_call items must close here so tool input parses).
240302
if (open.kind === "tool_use" && item.type === "function_call") closeOpenBlock();
@@ -322,6 +384,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
322384
const output = Array.isArray(body.output) ? body.output : [];
323385
const content: Rec[] = [];
324386
let sawToolUse = false;
387+
let webSearchRequests = 0;
325388

326389
for (const raw of output) {
327390
if (!isRec(raw)) continue;
@@ -366,6 +429,14 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
366429
});
367430
break;
368431
}
432+
case "web_search_call": {
433+
// Server-side search: emit the Anthropic pair. Does NOT set sawToolUse.
434+
const pair = webSearchPairFromItem(raw);
435+
content.push({ type: "server_tool_use", id: pair.id, name: "web_search", input: pair.input });
436+
content.push({ type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent });
437+
if (pair.completed) webSearchRequests++;
438+
break;
439+
}
369440
default:
370441
break;
371442
}
@@ -384,7 +455,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
384455
model,
385456
stop_reason: stopReason,
386457
stop_sequence: null,
387-
usage: anthropicUsage(body.usage),
458+
usage: anthropicUsage(body.usage, webSearchRequests),
388459
};
389460
}
390461

@@ -407,7 +478,8 @@ export async function collectAnthropicMessage(stream: ReadableStream<Uint8Array>
407478

408479
const closeBlock = () => {
409480
if (!openBlock) return;
410-
if (openBlock.type === "tool_use") {
481+
// server_tool_use streams its query via input_json_delta exactly like tool_use (audit F3).
482+
if (openBlock.type === "tool_use" || openBlock.type === "server_tool_use") {
411483
try { openBlock.input = toolJson.length > 0 ? JSON.parse(toolJson) : {}; } catch { openBlock.input = {}; }
412484
}
413485
content.push(openBlock);

‎tests/claude-outbound.test.ts‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import {
33
anthropicErrorBody,
44
anthropicErrorType,
55
anthropicUsage,
6+
collectAnthropicMessage,
67
responsesJsonToAnthropicMessage,
78
responsesSseToAnthropicSse,
89
} from "../src/claude/outbound";
@@ -207,3 +208,144 @@ describe("claude outbound non-stream + helpers", () => {
207208
expect(anthropicUsage({ input_tokens: 7, output_tokens: 2 })).toEqual({ input_tokens: 7, output_tokens: 2, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 });
208209
});
209210
});
211+
212+
describe("claude outbound web_search translation", () => {
213+
const wsItem = (over: Record<string, unknown> = {}) => ({
214+
type: "web_search_call", id: "ws_1", status: "completed",
215+
action: { type: "search", query: "latest bun release" },
216+
sources: [
217+
{ url: "https://bun.sh/blog", title: "Bun Blog" },
218+
{ url: "https://github.com/oven-sh/bun/releases" },
219+
],
220+
...over,
221+
});
222+
223+
test("T1 single search -> server_tool_use + web_search_tool_result pair with usage count", async () => {
224+
const upstream = [
225+
sse("response.created", { response: { id: "r", status: "in_progress" } }),
226+
sse("response.output_item.added", { output_index: 0, item: { type: "web_search_call", id: "ws_1", status: "in_progress" } }),
227+
sse("response.output_item.done", { output_index: 0, item: wsItem() }),
228+
sse("response.output_item.added", { output_index: 1, item: { type: "message", id: "m1" } }),
229+
sse("response.output_text.delta", { item_id: "m1", output_index: 1, content_index: 0, delta: "answer" }),
230+
sse("response.output_item.done", { output_index: 1, item: { type: "message", id: "m1" } }),
231+
sse("response.completed", { response: { status: "completed", usage: { input_tokens: 9, output_tokens: 3 } } }),
232+
].join("");
233+
const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
234+
expect(events.map(e => e.name)).toEqual([
235+
"message_start", "ping",
236+
"content_block_start", "content_block_delta", "content_block_stop", // server_tool_use
237+
"content_block_start", "content_block_stop", // web_search_tool_result
238+
"content_block_start", "content_block_delta", "content_block_stop", // text
239+
"message_delta", "message_stop",
240+
]);
241+
// server_tool_use start has no inline input; query arrives via input_json_delta.
242+
expect(events[2].data.content_block).toEqual({ type: "server_tool_use", id: "ws_1", name: "web_search" });
243+
expect(events[3].data.delta).toEqual({ type: "input_json_delta", partial_json: JSON.stringify({ query: "latest bun release" }) });
244+
const result = events[5].data.content_block;
245+
expect(result.type).toBe("web_search_tool_result");
246+
expect(result.tool_use_id).toBe("ws_1");
247+
expect(result.content).toEqual([
248+
{ type: "web_search_result", title: "Bun Blog", url: "https://bun.sh/blog" },
249+
{ type: "web_search_result", title: "", url: "https://github.com/oven-sh/bun/releases" },
250+
]);
251+
const usage = events[10].data.usage;
252+
expect(usage.server_tool_use).toEqual({ web_search_requests: 1 });
253+
// stop_reason stays end_turn: server_tool_use is not a client tool call.
254+
expect(events[10].data.delta.stop_reason).toBe("end_turn");
255+
});
256+
257+
test("T2 multi-search -> two pairs, usage 2, monotonic indexes", async () => {
258+
const upstream = [
259+
sse("response.created", { response: {} }),
260+
sse("response.output_item.done", { output_index: 0, item: wsItem() }),
261+
sse("response.output_item.done", { output_index: 1, item: wsItem({ id: "ws_2", action: { type: "search", queries: ["a", "b"] }, sources: [] }) }),
262+
sse("response.completed", { response: { status: "completed", usage: {} } }),
263+
].join("");
264+
const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
265+
const starts = events.filter(e => e.name === "content_block_start");
266+
expect(starts.map(e => e.data.content_block.type)).toEqual([
267+
"server_tool_use", "web_search_tool_result", "server_tool_use", "web_search_tool_result",
268+
]);
269+
const indexes = starts.map(e => e.data.index);
270+
expect(indexes).toEqual([0, 1, 2, 3]);
271+
// Batched queries keep the plural form in input.
272+
const secondDelta = events.filter(e => e.name === "content_block_delta")[1];
273+
expect(secondDelta.data.delta.partial_json).toBe(JSON.stringify({ queries: ["a", "b"] }));
274+
const msgDelta = events.find(e => e.name === "message_delta")!;
275+
expect(msgDelta.data.usage.server_tool_use).toEqual({ web_search_requests: 2 });
276+
});
277+
278+
test("T3 failed search -> error-shaped content, NOT counted in usage", async () => {
279+
const upstream = [
280+
sse("response.created", { response: {} }),
281+
sse("response.output_item.done", { output_index: 0, item: wsItem({ status: "failed", sources: undefined }) }),
282+
sse("response.completed", { response: { status: "completed", usage: {} } }),
283+
].join("");
284+
const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
285+
const result = events.filter(e => e.name === "content_block_start")[1].data.content_block;
286+
expect(result.content).toEqual({ type: "web_search_tool_result_error", error_code: "unavailable" });
287+
const msgDelta = events.find(e => e.name === "message_delta")!;
288+
expect(msgDelta.data.usage.server_tool_use).toBeUndefined();
289+
});
290+
291+
test("T4 no sources -> empty hits array still emits the pair (search count registers)", async () => {
292+
const upstream = [
293+
sse("response.created", { response: {} }),
294+
sse("response.output_item.done", { output_index: 0, item: wsItem({ sources: undefined }) }),
295+
sse("response.completed", { response: { status: "completed", usage: {} } }),
296+
].join("");
297+
const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
298+
const result = events.filter(e => e.name === "content_block_start")[1].data.content_block;
299+
expect(result.content).toEqual([]);
300+
expect(events.find(e => e.name === "message_delta")!.data.usage.server_tool_use).toEqual({ web_search_requests: 1 });
301+
});
302+
303+
test("T5 JSON path: pair emitted, stop_reason preserved, failed not counted", () => {
304+
const msg = responsesJsonToAnthropicMessage({
305+
status: "completed",
306+
output: [
307+
wsItem(),
308+
wsItem({ id: "ws_9", status: "failed" }),
309+
{ type: "message", id: "m", role: "assistant", content: [{ type: "output_text", text: "done" }] },
310+
],
311+
usage: { input_tokens: 5, output_tokens: 1 },
312+
}, "claude-ocx-x") as Record<string, any>;
313+
expect(msg.stop_reason).toBe("end_turn");
314+
expect(msg.content[0]).toEqual({ type: "server_tool_use", id: "ws_1", name: "web_search", input: { query: "latest bun release" } });
315+
expect(msg.content[1]).toMatchObject({ type: "web_search_tool_result", tool_use_id: "ws_1" });
316+
expect(msg.content[1].content).toHaveLength(2);
317+
expect(msg.content.map((c: Record<string, unknown>) => c.type)).toEqual([
318+
"server_tool_use", "web_search_tool_result", "server_tool_use", "web_search_tool_result", "text",
319+
]);
320+
expect(msg.content[3]).toMatchObject({ type: "web_search_tool_result", tool_use_id: "ws_9" });
321+
expect(msg.content[3].content).toEqual({ type: "web_search_tool_result_error", error_code: "unavailable" });
322+
expect(msg.usage.server_tool_use).toEqual({ web_search_requests: 1 });
323+
});
324+
325+
test("T6 regression: turn without web_search emits no server_tool_use and no usage field", async () => {
326+
const upstream = [
327+
sse("response.created", { response: {} }),
328+
sse("response.output_item.added", { output_index: 0, item: { type: "message", id: "m1" } }),
329+
sse("response.output_text.delta", { item_id: "m1", output_index: 0, content_index: 0, delta: "plain" }),
330+
sse("response.completed", { response: { status: "completed", usage: { input_tokens: 2, output_tokens: 1 } } }),
331+
].join("");
332+
const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
333+
expect(events.some(e => e.name === "content_block_start" && e.data.content_block.type === "server_tool_use")).toBe(false);
334+
expect(events.find(e => e.name === "message_delta")!.data.usage.server_tool_use).toBeUndefined();
335+
});
336+
337+
test("T7 collect path: server_tool_use input survives aggregation, usage passthrough", async () => {
338+
const upstream = [
339+
sse("response.created", { response: {} }),
340+
sse("response.output_item.done", { output_index: 0, item: wsItem() }),
341+
sse("response.output_text.delta", { item_id: "m1", output_index: 1, content_index: 0, delta: "hi" }),
342+
sse("response.completed", { response: { status: "completed", usage: { input_tokens: 4, output_tokens: 2 } } }),
343+
].join("");
344+
const anthropicSse = responsesSseToAnthropicSse(streamFrom(upstream), "m");
345+
const msg = await collectAnthropicMessage(anthropicSse, "m") as Record<string, any>;
346+
expect(msg.content.map((c: Record<string, unknown>) => c.type)).toEqual(["server_tool_use", "web_search_tool_result", "text"]);
347+
expect(msg.content[0].input).toEqual({ query: "latest bun release" });
348+
expect(msg.content[1].tool_use_id).toBe("ws_1");
349+
expect(msg.usage.server_tool_use).toEqual({ web_search_requests: 1 });
350+
});
351+
});

0 commit comments

Comments
 (0)