@combycode/llm-sdk 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 
 ## [Unreleased]
 
+## [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
+- **xAI hosted code-execution files** now surface on `response.files` (parity with the other
+  providers). xAI returns code-interpreter output files inline inside the `code_interpreter_call`
+  `logs` JSON (`output_files:[{file_name, mime_type, data:[…bytes]}]`) and only when the request
+  asks for them — so `XAIResponsesAdapter` now sends `include:['code_interpreter_call.outputs']`
+  when `code_interpreter` is used and extracts the inline bytes into `FileOutput`. Verified live on
+  `complete()` and `stream()`. `OpenAIResponsesAdapter.filesFromOutputItem` is now a `protected`
+  overridable method so Responses-compatible providers can extend file extraction.
+
+### Added
+- **Adapter-sourced builtin-tool capabilities in the catalog.** Every tool-capable (chat-family)
+  model now carries `capabilities.builtinTools` — `['web_search', 'code_interpreter']` for
+  anthropic/openai/google/xai, `['web_search']` for openrouter (it doesn't route hosted code
+  execution) — injected at catalog load from a single provider map (`PROVIDER_BUILTIN_TOOLS`) that
+  mirrors what the adapters actually support. New `catalog.builtinToolsFor()` /
+  `supportsBuiltinTool()` accessors and `select('web_search')` / `select('code_interpreter')`
+  queries (`search` stays an alias for `web_search`). Non-tool models (embeddings/tts/image) get
+  none. A reliable per-model source can refine this later.
+
 ## [1.3.0] - 2026-07-06
 
 ### Added

package/dist/index.browser.js

@@ -22105,6 +22105,15 @@ var catalog_default5 = {
   }
 };
 
+// src/llm/providers/builtin-tools.ts
+var PROVIDER_BUILTIN_TOOLS = {
+  anthropic: ["web_search", "code_interpreter"],
+  openai: ["web_search", "code_interpreter"],
+  google: ["web_search", "code_interpreter"],
+  xai: ["web_search", "code_interpreter"],
+  openrouter: ["web_search"]
+};
+
 // src/plugins/model-catalog/catalog.ts
 var PROVIDER_DEFAULT_CATALOGS = [
   catalog_default,
@@ -22142,6 +22151,13 @@ var DEFAULT_REASONING = {
   encryptedContent: false,
   summaryAvailable: false
 };
+function withBuiltinTools(provider, caps) {
+  if (caps.builtinTools !== void 0) return caps;
+  if (!caps.toolUse) return caps;
+  const tools = PROVIDER_BUILTIN_TOOLS[provider];
+  if (!tools || tools.length === 0) return caps;
+  return { ...caps, builtinTools: [...tools] };
+}
 var ModelCatalog = class {
   models = /* @__PURE__ */ new Map();
   /** `provider/alias` → `provider/canonical-slug`. Lets get()/resolveModelId
@@ -22160,7 +22176,7 @@ var ModelCatalog = class {
       supportedApis: info.supportedApis ?? [info.preferredApi ?? "completions"],
       contextWindow: info.contextWindow,
       maxOutput: info.maxOutput,
-      capabilities: { ...DEFAULT_CAPABILITIES, ...info.capabilities },
+      capabilities: withBuiltinTools(provider, { ...DEFAULT_CAPABILITIES, ...info.capabilities }),
       reasoning: { ...DEFAULT_REASONING, ...info.reasoning },
       mediaOnly: info.mediaOnly,
       tokenizer: info.tokenizer,
@@ -22214,6 +22230,15 @@ var ModelCatalog = class {
   supportsTools(provider, model) {
     return this.get(provider, model)?.capabilities.toolUse ?? false;
   }
+  /** Hosted server-side builtin tools this model supports (e.g. `['web_search',
+   *  'code_interpreter']`). Empty when unknown or the model isn't tool-capable. */
+  builtinToolsFor(provider, model) {
+    return [...this.get(provider, model)?.capabilities.builtinTools ?? []];
+  }
+  /** Whether this model supports a specific hosted builtin tool. */
+  supportsBuiltinTool(provider, model, tool) {
+    return this.get(provider, model)?.capabilities.builtinTools?.includes(tool) ?? false;
+  }
   supportsPreviousResponseId(provider, model) {
     const info = this.get(provider, model);
     if (info && !info.supportedApis.some((a) => a === "responses" || a === "interactions")) {
@@ -23057,6 +23082,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;
@@ -23108,6 +23134,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,
@@ -23131,6 +23160,7 @@ var LLMClient = class {
       thinking: thinking || null,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23364,6 +23394,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;
@@ -23573,6 +23621,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 });
@@ -23587,6 +23636,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));
       }
@@ -23604,6 +23658,7 @@ var AnthropicAdapter = class {
       toolCalls,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       thinking,
       latencyMs,
       raw
@@ -23627,8 +23682,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") {
     }
@@ -24164,6 +24234,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
@@ -24176,6 +24249,7 @@ var GoogleAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
       raw
     };
@@ -24213,6 +24287,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;
@@ -24243,6 +24319,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({
@@ -26009,6 +26090,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;
@@ -26212,11 +26302,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(...filesFromResponsesOutputItem(item));
+      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) {
@@ -26277,6 +26370,7 @@ var OpenAIResponsesAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
       latencyMs,
       raw
@@ -26308,6 +26402,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({
@@ -26318,7 +26416,11 @@ var OpenAIResponsesAdapter = class {
     }
     if (type === "response.output_item.done") {
       const item = data.item;
-      for (const file of filesFromResponsesOutputItem(item)) events.push({ type: "file", file });
+      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 ?? "" });
       }
@@ -26354,6 +26456,12 @@ var OpenAIResponsesAdapter = class {
   createStreamParser() {
     return (event) => this.parseStreamEvent(event);
   }
+  /** Hosted code-execution output files from one output item. Overridable so
+   *  Responses-compatible providers with a different file shape (e.g. xAI, which
+   *  embeds files in the code-interpreter `logs` payload) can extend it. */
+  filesFromOutputItem(item) {
+    return filesFromResponsesOutputItem(item);
+  }
   parseUsage(u) {
     if (!u) return emptyUsage();
     const input = u.input_tokens ?? 0;
@@ -26411,6 +26519,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) {
@@ -26439,6 +26550,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
@@ -26918,6 +27058,29 @@ var XAIMediaAdapter = class {
 };
 
 // src/llm/providers/xai/responses.ts
+function xaiCodeExecFiles(item) {
+  if (item.type !== "code_interpreter_call") return [];
+  const files = [];
+  for (const out of item.outputs ?? []) {
+    if (out.type !== "logs" || typeof out.logs !== "string") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(out.logs);
+    } catch {
+      continue;
+    }
+    for (const f of parsed.output_files ?? []) {
+      if (!Array.isArray(f.data)) continue;
+      files.push({
+        data: bytesToBase64(Uint8Array.from(f.data)),
+        ...typeof f.file_name === "string" ? { name: f.file_name } : {},
+        ...typeof f.mime_type === "string" ? { mimeType: f.mime_type } : {},
+        source: "code_execution"
+      });
+    }
+  }
+  return files;
+}
 var XAIResponsesAdapter = class extends OpenAIResponsesAdapter {
   name = "xai";
   constructor(config) {
@@ -26937,8 +27100,20 @@ var XAIResponsesAdapter = class extends OpenAIResponsesAdapter {
     if (!req.model.includes("multi-agent")) {
       delete body.reasoning;
     }
+    const usesCodeInterpreter = req.tools?.some(
+      (t) => !isFunctionTool(t) && t.type === "code_interpreter"
+    );
+    if (usesCodeInterpreter) {
+      const include = /* @__PURE__ */ new Set([...body.include ?? [], "code_interpreter_call.outputs"]);
+      body.include = [...include];
+    }
     return result;
   }
+  /** xAI embeds code-execution files inline in the `logs` payload — extend the base
+   *  extraction (which handles OpenAI-style annotations / image URLs) with the xAI shape. */
+  filesFromOutputItem(item) {
+    return [...super.filesFromOutputItem(item), ...xaiCodeExecFiles(item)];
+  }
 };
 
 // src/util/json-schema.ts
@@ -28272,6 +28447,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
@@ -28468,6 +28644,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
@@ -36863,12 +37040,16 @@ var DEFAULT_TAGS = {
   huge: "context:large"
 };
 var CAP_KEYS = {
-  search: "webSearch",
   vision: "vision",
   tools: "toolUse",
   audio: "audio",
   structured: "structuredOutput"
 };
+var BUILTIN_TOOL_KEYS = {
+  search: "web_search",
+  web_search: "web_search",
+  code_interpreter: "code_interpreter"
+};
 var KNOWN_KEYS = /* @__PURE__ */ new Set([
   "price",
   "context",
@@ -36878,7 +37059,8 @@ var KNOWN_KEYS = /* @__PURE__ */ new Set([
   "status",
   "provider",
   "active",
-  ...Object.keys(CAP_KEYS)
+  ...Object.keys(CAP_KEYS),
+  ...Object.keys(BUILTIN_TOOL_KEYS)
 ]);
 function parseNum(v) {
   const m = /^([\d.]+)\s*([kKmM]?)$/.exec(v.trim());
@@ -36947,6 +37129,13 @@ function matches(m, c, th, tier) {
     case "active":
       return isNo(c.value) ? m.active === false : m.active !== false;
     default: {
+      const tool = BUILTIN_TOOL_KEYS[c.key];
+      if (tool) {
+        const inList = m.capabilities.builtinTools?.includes(tool) ?? false;
+        const legacy = tool === "web_search" && !!m.capabilities.webSearch;
+        const has2 = inList || legacy;
+        return isNo(c.value) ? !has2 : has2;
+      }
       const cap = CAP_KEYS[c.key];
       const has = !!m.capabilities[cap];
       return isNo(c.value) ? !has : has;

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

@@ -22032,6 +22032,15 @@ var catalog_default5 = {
   }
 };
 
+// src/llm/providers/builtin-tools.ts
+var PROVIDER_BUILTIN_TOOLS = {
+  anthropic: ["web_search", "code_interpreter"],
+  openai: ["web_search", "code_interpreter"],
+  google: ["web_search", "code_interpreter"],
+  xai: ["web_search", "code_interpreter"],
+  openrouter: ["web_search"]
+};
+
 // src/plugins/model-catalog/catalog.ts
 var PROVIDER_DEFAULT_CATALOGS = [
   catalog_default,
@@ -22069,6 +22078,13 @@ var DEFAULT_REASONING = {
   encryptedContent: false,
   summaryAvailable: false
 };
+function withBuiltinTools(provider, caps) {
+  if (caps.builtinTools !== void 0) return caps;
+  if (!caps.toolUse) return caps;
+  const tools = PROVIDER_BUILTIN_TOOLS[provider];
+  if (!tools || tools.length === 0) return caps;
+  return { ...caps, builtinTools: [...tools] };
+}
 var ModelCatalog = class {
   models = /* @__PURE__ */ new Map();
   /** `provider/alias` → `provider/canonical-slug`. Lets get()/resolveModelId
@@ -22087,7 +22103,7 @@ var ModelCatalog = class {
       supportedApis: info.supportedApis ?? [info.preferredApi ?? "completions"],
       contextWindow: info.contextWindow,
       maxOutput: info.maxOutput,
-      capabilities: { ...DEFAULT_CAPABILITIES, ...info.capabilities },
+      capabilities: withBuiltinTools(provider, { ...DEFAULT_CAPABILITIES, ...info.capabilities }),
       reasoning: { ...DEFAULT_REASONING, ...info.reasoning },
       mediaOnly: info.mediaOnly,
       tokenizer: info.tokenizer,
@@ -22141,6 +22157,15 @@ var ModelCatalog = class {
   supportsTools(provider, model) {
     return this.get(provider, model)?.capabilities.toolUse ?? false;
   }
+  /** Hosted server-side builtin tools this model supports (e.g. `['web_search',
+   *  'code_interpreter']`). Empty when unknown or the model isn't tool-capable. */
+  builtinToolsFor(provider, model) {
+    return [...this.get(provider, model)?.capabilities.builtinTools ?? []];
+  }
+  /** Whether this model supports a specific hosted builtin tool. */
+  supportsBuiltinTool(provider, model, tool) {
+    return this.get(provider, model)?.capabilities.builtinTools?.includes(tool) ?? false;
+  }
   supportsPreviousResponseId(provider, model) {
     const info = this.get(provider, model);
     if (info && !info.supportedApis.some((a) => a === "responses" || a === "interactions")) {
@@ -22984,6 +23009,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;
@@ -23035,6 +23061,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,
@@ -23058,6 +23087,7 @@ var LLMClient = class {
       thinking: thinking || null,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23291,6 +23321,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;
@@ -23500,6 +23548,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 });
@@ -23514,6 +23563,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));
       }
@@ -23531,6 +23585,7 @@ var AnthropicAdapter = class {
       toolCalls,
       media: [],
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       thinking,
       latencyMs,
       raw
@@ -23554,8 +23609,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") {
     }
@@ -24091,6 +24161,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
@@ -24103,6 +24176,7 @@ var GoogleAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
       raw
     };
@@ -24140,6 +24214,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;
@@ -24170,6 +24246,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({
@@ -25936,6 +26017,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;
@@ -26139,11 +26229,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(...filesFromResponsesOutputItem(item));
+      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) {
@@ -26204,6 +26297,7 @@ var OpenAIResponsesAdapter = class {
       thinking,
       media,
       ...files.length ? { files } : {},
+      ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
       latencyMs,
       raw
@@ -26235,6 +26329,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({
@@ -26245,7 +26343,11 @@ var OpenAIResponsesAdapter = class {
     }
     if (type === "response.output_item.done") {
       const item = data.item;
-      for (const file of filesFromResponsesOutputItem(item)) events.push({ type: "file", file });
+      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 ?? "" });
       }
@@ -26281,6 +26383,12 @@ var OpenAIResponsesAdapter = class {
   createStreamParser() {
     return (event) => this.parseStreamEvent(event);
   }
+  /** Hosted code-execution output files from one output item. Overridable so
+   *  Responses-compatible providers with a different file shape (e.g. xAI, which
+   *  embeds files in the code-interpreter `logs` payload) can extend it. */
+  filesFromOutputItem(item) {
+    return filesFromResponsesOutputItem(item);
+  }
   parseUsage(u) {
     if (!u) return emptyUsage();
     const input = u.input_tokens ?? 0;
@@ -26338,6 +26446,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) {
@@ -26366,6 +26477,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
@@ -26845,6 +26985,29 @@ var XAIMediaAdapter = class {
 };
 
 // src/llm/providers/xai/responses.ts
+function xaiCodeExecFiles(item) {
+  if (item.type !== "code_interpreter_call") return [];
+  const files = [];
+  for (const out of item.outputs ?? []) {
+    if (out.type !== "logs" || typeof out.logs !== "string") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(out.logs);
+    } catch {
+      continue;
+    }
+    for (const f of parsed.output_files ?? []) {
+      if (!Array.isArray(f.data)) continue;
+      files.push({
+        data: bytesToBase64(Uint8Array.from(f.data)),
+        ...typeof f.file_name === "string" ? { name: f.file_name } : {},
+        ...typeof f.mime_type === "string" ? { mimeType: f.mime_type } : {},
+        source: "code_execution"
+      });
+    }
+  }
+  return files;
+}
 var XAIResponsesAdapter = class extends OpenAIResponsesAdapter {
   name = "xai";
   constructor(config) {
@@ -26864,8 +27027,20 @@ var XAIResponsesAdapter = class extends OpenAIResponsesAdapter {
     if (!req.model.includes("multi-agent")) {
       delete body.reasoning;
     }
+    const usesCodeInterpreter = req.tools?.some(
+      (t) => !isFunctionTool(t) && t.type === "code_interpreter"
+    );
+    if (usesCodeInterpreter) {
+      const include = /* @__PURE__ */ new Set([...body.include ?? [], "code_interpreter_call.outputs"]);
+      body.include = [...include];
+    }
     return result;
   }
+  /** xAI embeds code-execution files inline in the `logs` payload — extend the base
+   *  extraction (which handles OpenAI-style annotations / image URLs) with the xAI shape. */
+  filesFromOutputItem(item) {
+    return [...super.filesFromOutputItem(item), ...xaiCodeExecFiles(item)];
+  }
 };
 
 // src/util/json-schema.ts
@@ -28199,6 +28374,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
@@ -28395,6 +28571,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
@@ -36790,12 +36967,16 @@ var DEFAULT_TAGS = {
   huge: "context:large"
 };
 var CAP_KEYS = {
-  search: "webSearch",
   vision: "vision",
   tools: "toolUse",
   audio: "audio",
   structured: "structuredOutput"
 };
+var BUILTIN_TOOL_KEYS = {
+  search: "web_search",
+  web_search: "web_search",
+  code_interpreter: "code_interpreter"
+};
 var KNOWN_KEYS = /* @__PURE__ */ new Set([
   "price",
   "context",
@@ -36805,7 +36986,8 @@ var KNOWN_KEYS = /* @__PURE__ */ new Set([
   "status",
   "provider",
   "active",
-  ...Object.keys(CAP_KEYS)
+  ...Object.keys(CAP_KEYS),
+  ...Object.keys(BUILTIN_TOOL_KEYS)
 ]);
 function parseNum(v) {
   const m = /^([\d.]+)\s*([kKmM]?)$/.exec(v.trim());
@@ -36874,6 +37056,13 @@ function matches(m, c, th, tier) {
     case "active":
       return isNo(c.value) ? m.active === false : m.active !== false;
     default: {
+      const tool = BUILTIN_TOOL_KEYS[c.key];
+      if (tool) {
+        const inList = m.capabilities.builtinTools?.includes(tool) ?? false;
+        const legacy = tool === "web_search" && !!m.capabilities.webSearch;
+        const has2 = inList || legacy;
+        return isNo(c.value) ? !has2 : has2;
+      }
       const cap = CAP_KEYS[c.key];
       const has = !!m.capabilities[cap];
       return isNo(c.value) ? !has : has;

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/builtin-tools.d.ts

@@ -0,0 +1,15 @@
+/** Hosted server-side tools each provider's chat models support.
+ *
+ *  This is ADAPTER-SOURCED: it reflects what the provider adapters actually map
+ *  the unified `{ type: 'web_search' | 'code_interpreter' }` builtins onto (each
+ *  to the provider's native shape), verified by the live tools-parity test. It is
+ *  applied PROVIDER-LEVEL to tool-capable (chat-family) models at catalog load —
+ *  a deliberate first pass; a reliable per-model source can refine it later.
+ *
+ *  Coverage (verified live 2026-07):
+ *    - web_search       → anthropic, openai, google, xai, openrouter
+ *    - code_interpreter → anthropic, openai, google, xai   (NOT openrouter: it
+ *      proxies function tools + its own plugins, but does not route hosted code
+ *      execution — confirmed against the API). */
+import type { ProviderName } from '../types/provider';
+export declare const PROVIDER_BUILTIN_TOOLS: Record<ProviderName, readonly string[]>;

package/dist/llm/providers/openai/responses.d.ts

@@ -5,7 +5,7 @@
 import type { SSEEvent } from '../../../network/types';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
-import { type CompletionResponse, type Usage } from '../../types/response';
+import { type CompletionResponse, type FileOutput, type Usage } from '../../types/response';
 import type { StreamEvent } from '../../types/stream';
 export interface OpenAIResponsesAdapterConfig {
     apiKey: string;
@@ -28,5 +28,9 @@ export declare class OpenAIResponsesAdapter implements ProviderAdapter {
     /** Stateless — each output item finalizes with all its file annotations in a
      *  single response.output_item.done event. */
     createStreamParser(): (event: SSEEvent) => StreamEvent[];
+    /** Hosted code-execution output files from one output item. Overridable so
+     *  Responses-compatible providers with a different file shape (e.g. xAI, which
+     *  embeds files in the code-interpreter `logs` payload) can extend it. */
+    protected filesFromOutputItem(item: Record<string, unknown>): FileOutput[];
     protected parseUsage(u: Record<string, unknown> | undefined): Usage;
 }

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/providers/xai/responses.d.ts

@@ -7,6 +7,7 @@
  */
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
+import type { FileOutput } from '../../types/response';
 import { OpenAIResponsesAdapter } from '../openai/responses';
 export interface XAIResponsesAdapterConfig {
     apiKey: string;
@@ -17,4 +18,7 @@ export declare class XAIResponsesAdapter extends OpenAIResponsesAdapter {
     constructor(config: XAIResponsesAdapterConfig);
     baseURL(): string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** xAI embeds code-execution files inline in the `logs` payload — extend the base
+     *  extraction (which handles OpenAI-style annotations / image URLs) with the xAI shape. */
+    protected filesFromOutputItem(item: Record<string, unknown>): FileOutput[];
 }

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/dist/plugins/model-catalog/catalog.d.ts

@@ -140,6 +140,11 @@ export declare class ModelCatalog {
     getPreferredApi(provider: string, model: string): ApiType | null;
     supportsApi(provider: string, model: string, api: ApiType): boolean;
     supportsTools(provider: string, model: string): boolean;
+    /** Hosted server-side builtin tools this model supports (e.g. `['web_search',
+     *  'code_interpreter']`). Empty when unknown or the model isn't tool-capable. */
+    builtinToolsFor(provider: string, model: string): string[];
+    /** Whether this model supports a specific hosted builtin tool. */
+    supportsBuiltinTool(provider: string, model: string, tool: string): boolean;
     supportsPreviousResponseId(provider: string, model: string): boolean;
     /** Server-state retention as a duration string ("30d", "72h"), or null if unsupported. */
     getStateRetention(provider: string, model: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "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",