@combycode/llm-sdk 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-07-06
+
+### Fixed
+- **Anthropic file retrieval from the browser** was blocked by CORS. `retrieveFile` /
+  `streamFile` now send Anthropic's `anthropic-dangerous-direct-browser-access: true` header
+  when running in a browser (matching the completion adapter), so hosted code-execution files
+  download directly. No effect on Node/Bun.
+
+## [1.5.0] - 2026-07-06
+
+### Added
+- **Builtin-tool activity in streams + a durable trail.** Provider-run hosted tools (web search,
+  code execution) now surface `{ type: 'builtin_tool_start' }` / `{ type: 'builtin_tool_end' }`
+  stream events as they run, and a `response.builtinToolCalls` trail (`BuiltinToolCall[]` —
+  `{ tool, id? }` with unified tool names) on both `complete()` and streamed responses (propagated
+  through `AgentLoop`). Informational only — unlike `tool_call_*` (a function call the client must
+  execute), the provider runs these itself. Normalized across providers (Anthropic `server_tool_use`
+  / `*_tool_result`, OpenAI/xAI `web_search_call` / `code_interpreter_call` output items, Google
+  `executableCode` / `codeExecutionResult` parts + `googleSearch` grounding, OpenRouter
+  `:online` `url_citation` annotations → `web_search`). Verified live on Anthropic, OpenAI,
+  Google, xAI, and OpenRouter. Exports `BuiltinToolCall`.
+
 ## [1.4.0] - 2026-07-06
 
 ### Fixed

package/dist/index.browser.js

@@ -22471,7 +22471,11 @@ function contentRequest(ctx, file) {
         "x-api-key": ctx.apiKey,
         "anthropic-version": "2023-06-01",
         "anthropic-beta": "files-api-2025-04-14",
-        accept: "application/binary"
+        accept: "application/binary",
+        // Enable CORS for direct browser requests (same header the completion
+        // adapter sets); harmless on Node/Bun. Without it the browser blocks the
+        // file download by CORS.
+        ...isBrowser() ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
       }
     };
   }
@@ -22492,7 +22496,11 @@ function providerAuth(ctx, url) {
   const base = ctx.baseURL ?? DEFAULT_BASE[ctx.provider];
   if (!url.startsWith(base)) return {};
   if (ctx.provider === "anthropic") {
-    return { "x-api-key": ctx.apiKey, "anthropic-version": "2023-06-01" };
+    return {
+      "x-api-key": ctx.apiKey,
+      "anthropic-version": "2023-06-01",
+      ...isBrowser() ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
+    };
   }
   if (ctx.provider === "google") return { "x-goog-api-key": ctx.apiKey };
   return { authorization: `Bearer ${ctx.apiKey}` };
@@ -23082,6 +23090,7 @@ var LLMClient = class {
     let finishReason = "stop";
     let moderationReport;
     const files = [];
+    const builtinToolCalls = [];
     const fetchStream = this.fetchStreamFn;
     const queueName = this.queueName;
     const priority = this.priority;
@@ -23133,6 +23142,9 @@ var LLMClient = class {
         case "file":
           files.push(event.file);
           break;
+        case "builtin_tool_start":
+          builtinToolCalls.push({ tool: event.tool, ...event.id ? { id: event.id } : {} });
+          break;
         case "moderation":
           moderationReport = this.mergeModeration(
             moderationReport,
@@ -23156,6 +23168,7 @@ var LLMClient = class {
       thinking: thinking || null,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23389,6 +23402,24 @@ var AnthropicFileAdapter = class {
   }
 };
 
+// src/llm/providers/_shared/builtin-tools.ts
+var NATIVE_TO_UNIFIED = {
+  // OpenAI / xAI Responses output-item types
+  web_search_call: "web_search",
+  code_interpreter_call: "code_interpreter",
+  // Anthropic server_tool_use names
+  web_search: "web_search",
+  code_execution: "code_interpreter",
+  bash_code_execution: "code_interpreter",
+  // Anthropic *_tool_result block types
+  web_search_tool_result: "web_search",
+  code_execution_tool_result: "code_interpreter",
+  bash_code_execution_tool_result: "code_interpreter"
+};
+function unifiedBuiltinTool(native) {
+  return NATIVE_TO_UNIFIED[native] ?? native.replace(/_call$/, "").replace(/_tool_result$/, "");
+}
+
 // src/llm/providers/_shared/constants.ts
 var AUDIO_PCM16_SAMPLE_RATE_HZ = 24e3;
 var DEFAULT_MAX_TOKENS = 4096;
@@ -23598,6 +23629,7 @@ var AnthropicAdapter = class {
     let thinking = null;
     const toolCalls = [];
     const files = [];
+    const builtinToolCalls = [];
     for (const block of contentBlocks) {
       if (block.type === "text") {
         content.push({ type: "text", text: block.text });
@@ -23612,6 +23644,11 @@ var AnthropicAdapter = class {
         };
         content.push(tc);
         toolCalls.push(tc);
+      } else if (block.type === "server_tool_use") {
+        builtinToolCalls.push({
+          tool: unifiedBuiltinTool(block.name),
+          ...typeof block.id === "string" ? { id: block.id } : {}
+        });
       } else {
         files.push(...filesFromCodeExecBlock(block));
       }
@@ -23629,6 +23666,7 @@ var AnthropicAdapter = class {
       toolCalls,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       thinking,
       latencyMs,
       raw
@@ -23652,8 +23690,23 @@ var AnthropicAdapter = class {
       if (block.type === "tool_use") {
         return [{ type: "tool_call_start", id: block.id, name: block.name }];
       }
-      const files = filesFromCodeExecBlock(block);
-      if (files.length) return files.map((file) => ({ type: "file", file }));
+      const events = [];
+      const blockType = block.type;
+      if (blockType === "server_tool_use") {
+        events.push({
+          type: "builtin_tool_start",
+          tool: unifiedBuiltinTool(block.name),
+          ...typeof block.id === "string" ? { id: block.id } : {}
+        });
+      } else if (blockType?.endsWith("_tool_result")) {
+        events.push({
+          type: "builtin_tool_end",
+          tool: unifiedBuiltinTool(blockType),
+          ...typeof block.tool_use_id === "string" ? { id: block.tool_use_id } : {}
+        });
+      }
+      for (const file of filesFromCodeExecBlock(block)) events.push({ type: "file", file });
+      return events;
     }
     if (type === "content_block_stop") {
     }
@@ -24189,6 +24242,9 @@ var GoogleAdapter = class {
       candidate.finishReason,
       { MAX_TOKENS: "length", SAFETY: "content_filter" }
     );
+    const builtinToolCalls = [];
+    if (hasCodeExec) builtinToolCalls.push({ tool: "code_interpreter" });
+    if (candidate.groundingMetadata) builtinToolCalls.push({ tool: "web_search" });
     return {
       id: crypto.randomUUID(),
       // Google doesn't return a response ID in generateContent
@@ -24201,6 +24257,7 @@ var GoogleAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
       raw
     };
@@ -24238,6 +24295,8 @@ var GoogleAdapter = class {
       if (part.text !== void 0 && !part.thought)
         events.push({ type: "text", text: part.text });
       if (part.thought && part.text) events.push({ type: "thinking", text: part.text });
+      if (part.executableCode) events.push({ type: "builtin_tool_start", tool: "code_interpreter" });
+      if (part.codeExecutionResult) events.push({ type: "builtin_tool_end", tool: "code_interpreter" });
       if (part.inlineData) {
         const inline = part.inlineData;
         const mime = inline.mimeType;
@@ -24268,6 +24327,11 @@ var GoogleAdapter = class {
         events.push({ type: "tool_call_end", id: "" });
       }
     }
+    if (candidate.groundingMetadata && !state.webSearchEmitted) {
+      state.webSearchEmitted = true;
+      events.push({ type: "builtin_tool_start", tool: "web_search" });
+      events.push({ type: "builtin_tool_end", tool: "web_search" });
+    }
     const fr = candidate.finishReason;
     if (fr)
       events.push({
@@ -26034,6 +26098,15 @@ function filenameForMime(mimeType) {
   if (mimeType.startsWith("image/")) return `file.${mimeType.slice("image/".length)}`;
   return "file.bin";
 }
+var RESPONSES_BUILTIN_ITEMS = /* @__PURE__ */ new Set(["web_search_call", "code_interpreter_call"]);
+function builtinCallFromResponsesItem(item) {
+  const type = item.type;
+  if (!RESPONSES_BUILTIN_ITEMS.has(type)) return null;
+  return {
+    tool: unifiedBuiltinTool(type),
+    ...typeof item.id === "string" ? { id: item.id } : {}
+  };
+}
 function filesFromResponsesOutputItem(item) {
   const files = [];
   const type = item.type;
@@ -26237,11 +26310,14 @@ var OpenAIResponsesAdapter = class {
     const toolCalls = [];
     const media = [];
     const files = [];
+    const builtinToolCalls = [];
     let thinking = null;
     let text = "";
     for (const item of output) {
       const type = item.type;
       files.push(...this.filesFromOutputItem(item));
+      const builtinCall = builtinCallFromResponsesItem(item);
+      if (builtinCall) builtinToolCalls.push(builtinCall);
       if (type === "message") {
         const itemContent = item.content ?? [];
         for (const c of itemContent) {
@@ -26302,6 +26378,7 @@ var OpenAIResponsesAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
       latencyMs,
       raw
@@ -26333,6 +26410,10 @@ var OpenAIResponsesAdapter = class {
       if (item?.type === "image_generation_call") {
         events.push({ type: "media_start", mediaType: "image", mimeType: "image/png" });
       }
+      const builtin = builtinCallFromResponsesItem(item ?? {});
+      if (builtin) {
+        events.push({ type: "builtin_tool_start", tool: builtin.tool, ...builtin.id ? { id: builtin.id } : {} });
+      }
     }
     if (type === "response.image_generation_call.partial_image") {
       events.push({
@@ -26344,6 +26425,10 @@ var OpenAIResponsesAdapter = class {
     if (type === "response.output_item.done") {
       const item = data.item;
       for (const file of this.filesFromOutputItem(item)) events.push({ type: "file", file });
+      const builtin = builtinCallFromResponsesItem(item ?? {});
+      if (builtin) {
+        events.push({ type: "builtin_tool_end", tool: builtin.tool, ...builtin.id ? { id: builtin.id } : {} });
+      }
       if (item?.type === "function_call") {
         events.push({ type: "tool_call_end", id: item.call_id ?? "" });
       }
@@ -26442,6 +26527,9 @@ function filenameFor(mimeType) {
 }
 
 // src/llm/providers/openrouter/completions.ts
+function hasUrlCitation(annotations) {
+  return Array.isArray(annotations) && annotations.some((a) => a?.type === "url_citation");
+}
 var OpenRouterAdapter = class extends OpenAIAdapter {
   name = "openrouter";
   constructor(config) {
@@ -26470,6 +26558,35 @@ var OpenRouterAdapter = class extends OpenAIAdapter {
     }
     return result;
   }
+  parseResponse(raw, latencyMs) {
+    const result = super.parseResponse(raw, latencyMs);
+    const choices = raw.choices;
+    const annotations = choices?.[0]?.message?.annotations;
+    if (hasUrlCitation(annotations)) {
+      result.builtinToolCalls = [...result.builtinToolCalls ?? [], { tool: "web_search" }];
+    }
+    return result;
+  }
+  /** Stateful — emit a single `web_search` builtin-tool pair the first time
+   *  `url_citation` annotations appear in the stream (the `:online` search signal). */
+  createStreamParser() {
+    let webSearchEmitted = false;
+    return (event) => {
+      const events = this.parseStreamEvent(event);
+      if (!webSearchEmitted) {
+        const choice = JSON.parse(event.data).choices?.[0];
+        const annotations = choice?.delta?.annotations ?? choice?.message?.annotations;
+        if (hasUrlCitation(annotations)) {
+          webSearchEmitted = true;
+          events.push(
+            { type: "builtin_tool_start", tool: "web_search" },
+            { type: "builtin_tool_end", tool: "web_search" }
+          );
+        }
+      }
+      return events;
+    };
+  }
 };
 
 // src/llm/providers/openrouter/responses.ts
@@ -28338,6 +28455,7 @@ var AgentLoop = class _AgentLoop {
       // Propagate hosted-tool file outputs + inline-moderation result from the final
       // LLM response (e.g. code-execution files produced during the run).
       ...lastResponse?.files ? { files: lastResponse.files } : {},
+      ...lastResponse?.builtinToolCalls ? { builtinToolCalls: lastResponse.builtinToolCalls } : {},
       ...lastResponse?.moderation ? { moderation: lastResponse.moderation } : {},
       latencyMs: performance.now() - startPerf,
       raw: lastResponse?.raw ?? null
@@ -28534,6 +28652,7 @@ var AgentLoop = class _AgentLoop {
       thinking: lastResponse?.thinking ?? null,
       media: [],
       ...lastResponse?.files ? { files: lastResponse.files } : {},
+      ...lastResponse?.builtinToolCalls ? { builtinToolCalls: lastResponse.builtinToolCalls } : {},
       ...lastResponse?.moderation ? { moderation: lastResponse.moderation } : {},
       latencyMs: performance.now() - startPerf,
       raw: null

package/dist/index.d.ts

@@ -48,7 +48,7 @@ export type { Role, MessageOrigin, ContentPart, TextPart, ImagePart, DocumentPar
 export { isFunctionTool, isBuiltinTool } from './llm/types/tools';
 export type { FunctionTool, BuiltinTool, McpToolParams, Tool, ToolChoice, JsonSchema } from './llm/types/tools';
 export { emptyUsage } from './llm/types/response';
-export type { CompletionResponse, FileOutput, FinishReason, Usage } from './llm/types/response';
+export type { BuiltinToolCall, CompletionResponse, FileOutput, FinishReason, Usage, } from './llm/types/response';
 export type { FileStream, RetrievedFile } from './llm/files/retrieve';
 export type { NormalizedRequest, ReasoningContext, ThinkingConfig, CacheConfig } from './llm/types/request';
 export type { MediaStreamType, StreamEvent } from './llm/types/stream';

package/dist/index.js

@@ -22398,7 +22398,11 @@ function contentRequest(ctx, file) {
         "x-api-key": ctx.apiKey,
         "anthropic-version": "2023-06-01",
         "anthropic-beta": "files-api-2025-04-14",
-        accept: "application/binary"
+        accept: "application/binary",
+        // Enable CORS for direct browser requests (same header the completion
+        // adapter sets); harmless on Node/Bun. Without it the browser blocks the
+        // file download by CORS.
+        ...isBrowser() ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
       }
     };
   }
@@ -22419,7 +22423,11 @@ function providerAuth(ctx, url) {
   const base = ctx.baseURL ?? DEFAULT_BASE[ctx.provider];
   if (!url.startsWith(base)) return {};
   if (ctx.provider === "anthropic") {
-    return { "x-api-key": ctx.apiKey, "anthropic-version": "2023-06-01" };
+    return {
+      "x-api-key": ctx.apiKey,
+      "anthropic-version": "2023-06-01",
+      ...isBrowser() ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
+    };
   }
   if (ctx.provider === "google") return { "x-goog-api-key": ctx.apiKey };
   return { authorization: `Bearer ${ctx.apiKey}` };
@@ -23009,6 +23017,7 @@ var LLMClient = class {
     let finishReason = "stop";
     let moderationReport;
     const files = [];
+    const builtinToolCalls = [];
     const fetchStream = this.fetchStreamFn;
     const queueName = this.queueName;
     const priority = this.priority;
@@ -23060,6 +23069,9 @@ var LLMClient = class {
         case "file":
           files.push(event.file);
           break;
+        case "builtin_tool_start":
+          builtinToolCalls.push({ tool: event.tool, ...event.id ? { id: event.id } : {} });
+          break;
         case "moderation":
           moderationReport = this.mergeModeration(
             moderationReport,
@@ -23083,6 +23095,7 @@ var LLMClient = class {
       thinking: thinking || null,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23316,6 +23329,24 @@ var AnthropicFileAdapter = class {
   }
 };
 
+// src/llm/providers/_shared/builtin-tools.ts
+var NATIVE_TO_UNIFIED = {
+  // OpenAI / xAI Responses output-item types
+  web_search_call: "web_search",
+  code_interpreter_call: "code_interpreter",
+  // Anthropic server_tool_use names
+  web_search: "web_search",
+  code_execution: "code_interpreter",
+  bash_code_execution: "code_interpreter",
+  // Anthropic *_tool_result block types
+  web_search_tool_result: "web_search",
+  code_execution_tool_result: "code_interpreter",
+  bash_code_execution_tool_result: "code_interpreter"
+};
+function unifiedBuiltinTool(native) {
+  return NATIVE_TO_UNIFIED[native] ?? native.replace(/_call$/, "").replace(/_tool_result$/, "");
+}
+
 // src/llm/providers/_shared/constants.ts
 var AUDIO_PCM16_SAMPLE_RATE_HZ = 24e3;
 var DEFAULT_MAX_TOKENS = 4096;
@@ -23525,6 +23556,7 @@ var AnthropicAdapter = class {
     let thinking = null;
     const toolCalls = [];
     const files = [];
+    const builtinToolCalls = [];
     for (const block of contentBlocks) {
       if (block.type === "text") {
         content.push({ type: "text", text: block.text });
@@ -23539,6 +23571,11 @@ var AnthropicAdapter = class {
         };
         content.push(tc);
         toolCalls.push(tc);
+      } else if (block.type === "server_tool_use") {
+        builtinToolCalls.push({
+          tool: unifiedBuiltinTool(block.name),
+          ...typeof block.id === "string" ? { id: block.id } : {}
+        });
       } else {
         files.push(...filesFromCodeExecBlock(block));
       }
@@ -23556,6 +23593,7 @@ var AnthropicAdapter = class {
       toolCalls,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       thinking,
       latencyMs,
       raw
@@ -23579,8 +23617,23 @@ var AnthropicAdapter = class {
       if (block.type === "tool_use") {
         return [{ type: "tool_call_start", id: block.id, name: block.name }];
       }
-      const files = filesFromCodeExecBlock(block);
-      if (files.length) return files.map((file) => ({ type: "file", file }));
+      const events = [];
+      const blockType = block.type;
+      if (blockType === "server_tool_use") {
+        events.push({
+          type: "builtin_tool_start",
+          tool: unifiedBuiltinTool(block.name),
+          ...typeof block.id === "string" ? { id: block.id } : {}
+        });
+      } else if (blockType?.endsWith("_tool_result")) {
+        events.push({
+          type: "builtin_tool_end",
+          tool: unifiedBuiltinTool(blockType),
+          ...typeof block.tool_use_id === "string" ? { id: block.tool_use_id } : {}
+        });
+      }
+      for (const file of filesFromCodeExecBlock(block)) events.push({ type: "file", file });
+      return events;
     }
     if (type === "content_block_stop") {
     }
@@ -24116,6 +24169,9 @@ var GoogleAdapter = class {
       candidate.finishReason,
       { MAX_TOKENS: "length", SAFETY: "content_filter" }
     );
+    const builtinToolCalls = [];
+    if (hasCodeExec) builtinToolCalls.push({ tool: "code_interpreter" });
+    if (candidate.groundingMetadata) builtinToolCalls.push({ tool: "web_search" });
     return {
       id: crypto.randomUUID(),
       // Google doesn't return a response ID in generateContent
@@ -24128,6 +24184,7 @@ var GoogleAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
       raw
     };
@@ -24165,6 +24222,8 @@ var GoogleAdapter = class {
       if (part.text !== void 0 && !part.thought)
         events.push({ type: "text", text: part.text });
       if (part.thought && part.text) events.push({ type: "thinking", text: part.text });
+      if (part.executableCode) events.push({ type: "builtin_tool_start", tool: "code_interpreter" });
+      if (part.codeExecutionResult) events.push({ type: "builtin_tool_end", tool: "code_interpreter" });
       if (part.inlineData) {
         const inline = part.inlineData;
         const mime = inline.mimeType;
@@ -24195,6 +24254,11 @@ var GoogleAdapter = class {
         events.push({ type: "tool_call_end", id: "" });
       }
     }
+    if (candidate.groundingMetadata && !state.webSearchEmitted) {
+      state.webSearchEmitted = true;
+      events.push({ type: "builtin_tool_start", tool: "web_search" });
+      events.push({ type: "builtin_tool_end", tool: "web_search" });
+    }
     const fr = candidate.finishReason;
     if (fr)
       events.push({
@@ -25961,6 +26025,15 @@ function filenameForMime(mimeType) {
   if (mimeType.startsWith("image/")) return `file.${mimeType.slice("image/".length)}`;
   return "file.bin";
 }
+var RESPONSES_BUILTIN_ITEMS = /* @__PURE__ */ new Set(["web_search_call", "code_interpreter_call"]);
+function builtinCallFromResponsesItem(item) {
+  const type = item.type;
+  if (!RESPONSES_BUILTIN_ITEMS.has(type)) return null;
+  return {
+    tool: unifiedBuiltinTool(type),
+    ...typeof item.id === "string" ? { id: item.id } : {}
+  };
+}
 function filesFromResponsesOutputItem(item) {
   const files = [];
   const type = item.type;
@@ -26164,11 +26237,14 @@ var OpenAIResponsesAdapter = class {
     const toolCalls = [];
     const media = [];
     const files = [];
+    const builtinToolCalls = [];
     let thinking = null;
     let text = "";
     for (const item of output) {
       const type = item.type;
       files.push(...this.filesFromOutputItem(item));
+      const builtinCall = builtinCallFromResponsesItem(item);
+      if (builtinCall) builtinToolCalls.push(builtinCall);
       if (type === "message") {
         const itemContent = item.content ?? [];
         for (const c of itemContent) {
@@ -26229,6 +26305,7 @@ var OpenAIResponsesAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
       latencyMs,
       raw
@@ -26260,6 +26337,10 @@ var OpenAIResponsesAdapter = class {
       if (item?.type === "image_generation_call") {
         events.push({ type: "media_start", mediaType: "image", mimeType: "image/png" });
       }
+      const builtin = builtinCallFromResponsesItem(item ?? {});
+      if (builtin) {
+        events.push({ type: "builtin_tool_start", tool: builtin.tool, ...builtin.id ? { id: builtin.id } : {} });
+      }
     }
     if (type === "response.image_generation_call.partial_image") {
       events.push({
@@ -26271,6 +26352,10 @@ var OpenAIResponsesAdapter = class {
     if (type === "response.output_item.done") {
       const item = data.item;
       for (const file of this.filesFromOutputItem(item)) events.push({ type: "file", file });
+      const builtin = builtinCallFromResponsesItem(item ?? {});
+      if (builtin) {
+        events.push({ type: "builtin_tool_end", tool: builtin.tool, ...builtin.id ? { id: builtin.id } : {} });
+      }
       if (item?.type === "function_call") {
         events.push({ type: "tool_call_end", id: item.call_id ?? "" });
       }
@@ -26369,6 +26454,9 @@ function filenameFor(mimeType) {
 }
 
 // src/llm/providers/openrouter/completions.ts
+function hasUrlCitation(annotations) {
+  return Array.isArray(annotations) && annotations.some((a) => a?.type === "url_citation");
+}
 var OpenRouterAdapter = class extends OpenAIAdapter {
   name = "openrouter";
   constructor(config) {
@@ -26397,6 +26485,35 @@ var OpenRouterAdapter = class extends OpenAIAdapter {
     }
     return result;
   }
+  parseResponse(raw, latencyMs) {
+    const result = super.parseResponse(raw, latencyMs);
+    const choices = raw.choices;
+    const annotations = choices?.[0]?.message?.annotations;
+    if (hasUrlCitation(annotations)) {
+      result.builtinToolCalls = [...result.builtinToolCalls ?? [], { tool: "web_search" }];
+    }
+    return result;
+  }
+  /** Stateful — emit a single `web_search` builtin-tool pair the first time
+   *  `url_citation` annotations appear in the stream (the `:online` search signal). */
+  createStreamParser() {
+    let webSearchEmitted = false;
+    return (event) => {
+      const events = this.parseStreamEvent(event);
+      if (!webSearchEmitted) {
+        const choice = JSON.parse(event.data).choices?.[0];
+        const annotations = choice?.delta?.annotations ?? choice?.message?.annotations;
+        if (hasUrlCitation(annotations)) {
+          webSearchEmitted = true;
+          events.push(
+            { type: "builtin_tool_start", tool: "web_search" },
+            { type: "builtin_tool_end", tool: "web_search" }
+          );
+        }
+      }
+      return events;
+    };
+  }
 };
 
 // src/llm/providers/openrouter/responses.ts
@@ -28265,6 +28382,7 @@ var AgentLoop = class _AgentLoop {
       // Propagate hosted-tool file outputs + inline-moderation result from the final
       // LLM response (e.g. code-execution files produced during the run).
       ...lastResponse?.files ? { files: lastResponse.files } : {},
+      ...lastResponse?.builtinToolCalls ? { builtinToolCalls: lastResponse.builtinToolCalls } : {},
       ...lastResponse?.moderation ? { moderation: lastResponse.moderation } : {},
       latencyMs: performance.now() - startPerf,
       raw: lastResponse?.raw ?? null
@@ -28461,6 +28579,7 @@ var AgentLoop = class _AgentLoop {
       thinking: lastResponse?.thinking ?? null,
       media: [],
       ...lastResponse?.files ? { files: lastResponse.files } : {},
+      ...lastResponse?.builtinToolCalls ? { builtinToolCalls: lastResponse.builtinToolCalls } : {},
       ...lastResponse?.moderation ? { moderation: lastResponse.moderation } : {},
       latencyMs: performance.now() - startPerf,
       raw: null

package/dist/llm/providers/_shared/builtin-tools.d.ts

@@ -0,0 +1,5 @@
+/** Normalize a provider-native builtin-tool marker (output-item type, server-tool
+ *  name, or result-block type) to the unified tool name used across the SDK
+ *  (`web_search` | `code_interpreter` | …). Unknown values fall back to a stripped
+ *  form so a new provider tool still yields a sensible name. */
+export declare function unifiedBuiltinTool(native: string): string;

package/dist/llm/providers/openrouter/completions.d.ts

@@ -1,6 +1,9 @@
 /** OpenRouter provider adapter — OpenAI-compatible with extensions. */
+import type { SSEEvent } from '../../../network/types';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
+import type { CompletionResponse } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
 import { OpenAIAdapter } from '../openai/completions';
 export interface OpenRouterAdapterConfig {
     apiKey: string;
@@ -12,4 +15,8 @@ export declare class OpenRouterAdapter extends OpenAIAdapter {
     baseURL(): string;
     completionPath(): string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    /** Stateful — emit a single `web_search` builtin-tool pair the first time
+     *  `url_citation` annotations appear in the stream (the `:online` search signal). */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
 }

package/dist/llm/types/response.d.ts

@@ -16,6 +16,10 @@ export interface CompletionResponse {
      *  etc. Unified across providers. When only `id` is set, fetch the bytes via the
      *  provider's files API; some providers return `data` inline. Absent when none. */
     files?: FileOutput[];
+    /** Hosted (provider-run) builtin tools the model invoked this turn — e.g. a web
+     *  search or code-execution run. A durable trail of what was called (the provider
+     *  ran them server-side; nothing for the client to execute). Absent when none. */
+    builtinToolCalls?: BuiltinToolCall[];
     /** Inline-moderation outcome, when the `moderation` request option was used.
      *  Report-only: present for observability; it never blocks the call. Absent when
      *  moderation was not requested. */
@@ -44,6 +48,14 @@ export interface FileOutput {
      *  Absent for providers that don't need extra context. */
     ref?: Record<string, unknown>;
 }
+/** A hosted builtin tool the model invoked (provider-run). */
+export interface BuiltinToolCall {
+    /** Unified tool name: `'web_search'` | `'code_interpreter'` | … (normalized from
+     *  each provider's native name — e.g. Anthropic `code_execution`). */
+    tool: string;
+    /** Provider call id, when available (correlates the stream start/end events). */
+    id?: string;
+}
 export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
 export interface Usage {
     inputTokens: number;

package/dist/llm/types/stream.d.ts

@@ -49,6 +49,23 @@ export type StreamEvent = {
     type: 'file';
     file: FileOutput;
 }
+/** A hosted (provider-run) builtin tool began executing server-side — e.g. the
+ *  model started a web search or code-execution run. `tool` is the unified name
+ *  (`'web_search'` | `'code_interpreter'` | …). Informational progress: unlike
+ *  `tool_call_*` (a function call the CLIENT must run), the provider runs these
+ *  itself, so there is nothing to execute or return. Also collected onto the
+ *  streamed final response's `builtinToolCalls`. */
+ | {
+    type: 'builtin_tool_start';
+    tool: string;
+    id?: string;
+}
+/** A hosted builtin tool finished executing server-side. */
+ | {
+    type: 'builtin_tool_end';
+    tool: string;
+    id?: string;
+}
 /** A moderation result for the input or output. `source` distinguishes a
  *  provider-native result from a client-emulated one. Emitted by the moderation
  *  option (report-only). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",