@combycode/llm-sdk 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 
 ## [Unreleased]
 
+## [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")) {
@@ -26216,7 +26241,7 @@ var OpenAIResponsesAdapter = class {
     let text = "";
     for (const item of output) {
       const type = item.type;
-      files.push(...filesFromResponsesOutputItem(item));
+      files.push(...this.filesFromOutputItem(item));
       if (type === "message") {
         const itemContent = item.content ?? [];
         for (const c of itemContent) {
@@ -26318,7 +26343,7 @@ 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 });
       if (item?.type === "function_call") {
         events.push({ type: "tool_call_end", id: item.call_id ?? "" });
       }
@@ -26354,6 +26379,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;
@@ -26918,6 +26949,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 +26991,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
@@ -36863,12 +36929,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 +36948,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 +37018,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.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")) {
@@ -26143,7 +26168,7 @@ var OpenAIResponsesAdapter = class {
     let text = "";
     for (const item of output) {
       const type = item.type;
-      files.push(...filesFromResponsesOutputItem(item));
+      files.push(...this.filesFromOutputItem(item));
       if (type === "message") {
         const itemContent = item.content ?? [];
         for (const c of itemContent) {
@@ -26245,7 +26270,7 @@ 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 });
       if (item?.type === "function_call") {
         events.push({ type: "tool_call_end", id: item.call_id ?? "" });
       }
@@ -26281,6 +26306,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;
@@ -26845,6 +26876,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 +26918,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
@@ -36790,12 +36856,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 +36875,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 +36945,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/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/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/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.4.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",