@combycode/llm-sdk 1.2.0 → 1.4.0

package/dist/index.js

@@ -2451,7 +2451,7 @@ var QueueState = class {
       });
       this.processed++;
       if (response.ok) {
-        const body = await parseResponseBody(response, entry.request.responseType ?? "json");
+        const body = entry.request.responseType === "stream" ? response.body : await parseResponseBody(response, entry.request.responseType ?? "json");
         this.semaphore.release();
         entry.resolve({ status: response.status, headers: resHeaders, body });
         return;
@@ -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")) {
@@ -22354,6 +22379,160 @@ async function* wrapParallel(raw, interval, moderate2) {
   }
 }
 
+// src/llm/files/retrieve.ts
+var DEFAULT_BASE = {
+  anthropic: "https://api.anthropic.com",
+  openai: "https://api.openai.com",
+  xai: "https://api.x.ai",
+  google: "https://generativelanguage.googleapis.com",
+  openrouter: "https://openrouter.ai/api"
+};
+var OCTET_STREAM = "application/octet-stream";
+function contentRequest(ctx, file) {
+  const base = ctx.baseURL ?? DEFAULT_BASE[ctx.provider];
+  const id = file.id;
+  if (ctx.provider === "anthropic") {
+    return {
+      url: `${base}/v1/files/${id}/content?beta=true`,
+      headers: {
+        "x-api-key": ctx.apiKey,
+        "anthropic-version": "2023-06-01",
+        "anthropic-beta": "files-api-2025-04-14",
+        accept: "application/binary"
+      }
+    };
+  }
+  if (ctx.provider === "openai" || ctx.provider === "xai" || ctx.provider === "openrouter") {
+    const containerId = file.ref?.containerId;
+    const path = containerId ? `/v1/containers/${containerId}/files/${id}/content` : `/v1/files/${id}/content`;
+    return { url: `${base}${path}`, headers: { authorization: `Bearer ${ctx.apiKey}` } };
+  }
+  if (ctx.provider === "google") {
+    return {
+      url: `${base}/v1beta/files/${id}:download?alt=media`,
+      headers: { "x-goog-api-key": ctx.apiKey }
+    };
+  }
+  throw new Error(`retrieveFile: no file-content endpoint for provider "${ctx.provider}"`);
+}
+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" };
+  }
+  if (ctx.provider === "google") return { "x-goog-api-key": ctx.apiKey };
+  return { authorization: `Bearer ${ctx.apiKey}` };
+}
+async function fetchFileResponse(ctx, file, responseType) {
+  if (file.url) {
+    return ctx.fetch({
+      url: file.url,
+      method: "GET",
+      headers: providerAuth(ctx, file.url),
+      body: void 0,
+      provider: ctx.provider,
+      model: "files",
+      responseType
+    });
+  }
+  if (file.id) {
+    const { url, headers } = contentRequest(ctx, file);
+    return ctx.fetch({
+      url,
+      method: "GET",
+      headers,
+      body: void 0,
+      provider: ctx.provider,
+      model: "files",
+      responseType
+    });
+  }
+  throw new Error("retrieveFile: FileOutput has neither `data`, `url`, nor `id`");
+}
+function bytesToBlob(bytes, type) {
+  const ab = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(ab).set(bytes);
+  return new Blob([ab], { type });
+}
+function singleChunkStream(bytes) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    }
+  });
+}
+var EXT_MIME = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  bmp: "image/bmp",
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  txt: "text/plain",
+  json: "application/json",
+  xml: "application/xml",
+  html: "text/html",
+  md: "text/markdown",
+  pdf: "application/pdf",
+  zip: "application/zip",
+  parquet: "application/vnd.apache.parquet",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+};
+function mimeFromName(name) {
+  const ext = name?.includes(".") ? name.split(".").pop()?.toLowerCase() : void 0;
+  return ext ? EXT_MIME[ext] : void 0;
+}
+function header(headers, name) {
+  const lower = name.toLowerCase();
+  for (const k in headers) if (k.toLowerCase() === lower) return headers[k];
+  return void 0;
+}
+function filenameFromDisposition(cd) {
+  if (!cd) return void 0;
+  const ext = cd.match(/filename\*=[^']*''([^;]+)/i);
+  if (ext) {
+    try {
+      return decodeURIComponent(ext[1].trim());
+    } catch {
+    }
+  }
+  const plain = cd.match(/filename="?([^";]+)"?/i);
+  return plain ? plain[1].trim() : void 0;
+}
+async function retrieveFile(file, ctx) {
+  if (file.data) {
+    const blob2 = bytesToBlob(base64ToBytes(file.data), file.mimeType ?? OCTET_STREAM);
+    return { blob: blob2, name: file.name, mimeType: blob2.type, size: blob2.size };
+  }
+  const res = await fetchFileResponse(ctx, file, "arraybuffer");
+  const headers = res.headers ?? {};
+  const name = filenameFromDisposition(header(headers, "content-disposition")) ?? file.name;
+  const mimeType = header(headers, "content-type")?.split(";")[0].trim() || file.mimeType || mimeFromName(name) || OCTET_STREAM;
+  const blob = new Blob([res.body], { type: mimeType });
+  return { blob, name, mimeType, size: blob.size };
+}
+async function streamFile(file, ctx) {
+  if (file.data) {
+    const bytes = base64ToBytes(file.data);
+    return { stream: singleChunkStream(bytes), name: file.name, mimeType: file.mimeType, size: bytes.byteLength };
+  }
+  const res = await fetchFileResponse(ctx, file, "stream");
+  const headers = res.headers ?? {};
+  const len = header(headers, "content-length");
+  const name = filenameFromDisposition(header(headers, "content-disposition")) ?? file.name;
+  return {
+    stream: res.body,
+    name,
+    mimeType: header(headers, "content-type")?.split(";")[0].trim() || file.mimeType || mimeFromName(name),
+    size: len ? Number(len) : void 0
+  };
+}
+
 // src/util/duration.ts
 var UNIT_MS = {
   s: 1e3,
@@ -22596,6 +22775,28 @@ var LLMClient = class {
     else next.output = result;
     return next;
   }
+  // ─── File retrieval (hosted-tool output files) ─────────────────────────
+  retrieveContext() {
+    return {
+      provider: this.provider,
+      apiKey: this.apiKey,
+      fetch: this.fetchFn,
+      baseURL: this.adapter.baseURL()
+    };
+  }
+  /** Fetch a hosted-tool output file (e.g. a code-execution file from
+   *  `response.files`): its bytes as a `Blob` plus `name` / `mimeType` / `size`.
+   *  Resolves inline `data`, a `url`, or a provider file `id` — all through this
+   *  client's provider + auth + engine. */
+  retrieveFile(file) {
+    return retrieveFile(file, this.retrieveContext());
+  }
+  /** Stream a hosted-tool output file: a `ReadableStream<Uint8Array>` plus
+   *  best-effort `name` / `mimeType` / `size` (from the response headers). For large
+   *  files piped straight to a file / GridFS / HTTP response without buffering. */
+  streamFile(file) {
+    return streamFile(file, this.retrieveContext());
+  }
   /** Submit a request. Returns the parsed CompletionResponse. */
   async complete(input, options = {}) {
     const rawMessages = normalizeInput(input);
@@ -22807,17 +23008,18 @@ var LLMClient = class {
     let usage = emptyUsage();
     let finishReason = "stop";
     let moderationReport;
+    const files = [];
     const fetchStream = this.fetchStreamFn;
-    const adapter = this.adapter;
     const queueName = this.queueName;
     const priority = this.priority;
+    const parseStream = this.adapter.createStreamParser();
     async function* rawEvents() {
       for await (const sseEvent of fetchStream(httpReq, {
         queueName,
         priority,
         ctx
       })) {
-        for (const ev of adapter.parseStreamEvent(sseEvent)) yield ev;
+        for (const ev of parseStream(sseEvent)) yield ev;
       }
     }
     const mod = options.moderation;
@@ -22855,6 +23057,9 @@ var LLMClient = class {
         case "done":
           finishReason = event.finishReason;
           break;
+        case "file":
+          files.push(event.file);
+          break;
         case "moderation":
           moderationReport = this.mergeModeration(
             moderationReport,
@@ -22877,6 +23082,7 @@ var LLMClient = class {
       toolCalls: [],
       thinking: thinking || null,
       media: [],
+      ...files.length ? { files } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23137,6 +23343,22 @@ function anthropicRequestTier(t) {
 function anthropicBilledTier(raw) {
   return typeof raw === "string" && raw ? { serviceTier: raw, pricingTier: raw } : {};
 }
+function filesFromCodeExecBlock(block) {
+  if (block.type !== "bash_code_execution_tool_result" && block.type !== "code_execution_tool_result") {
+    return [];
+  }
+  const result = block.content;
+  if (!result || result.type !== "bash_code_execution_result" && result.type !== "code_execution_result" || !Array.isArray(result.content)) {
+    return [];
+  }
+  const files = [];
+  for (const out of result.content) {
+    if ((out.type === "bash_code_execution_output" || out.type === "code_execution_output") && typeof out.file_id === "string") {
+      files.push({ id: out.file_id, source: "code_execution" });
+    }
+  }
+  return files;
+}
 var AnthropicAdapter = class {
   name = "anthropic";
   apiKey;
@@ -23317,15 +23539,8 @@ var AnthropicAdapter = class {
         };
         content.push(tc);
         toolCalls.push(tc);
-      } else if (block.type === "bash_code_execution_tool_result" || block.type === "code_execution_tool_result") {
-        const result = block.content;
-        if (result && (result.type === "bash_code_execution_result" || result.type === "code_execution_result") && Array.isArray(result.content)) {
-          for (const out of result.content) {
-            if ((out.type === "bash_code_execution_output" || out.type === "code_execution_output") && typeof out.file_id === "string") {
-              files.push({ id: out.file_id, source: "code_execution" });
-            }
-          }
-        }
+      } else {
+        files.push(...filesFromCodeExecBlock(block));
       }
     }
     const finishReason = extractFinishReason(toolCalls.length > 0, r.stop_reason, {
@@ -23364,6 +23579,8 @@ 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 }));
     }
     if (type === "content_block_stop") {
     }
@@ -23387,6 +23604,11 @@ var AnthropicAdapter = class {
     }
     return [];
   }
+  /** Stateless — every event is self-contained (code-execution result blocks
+   *  arrive complete in a single content_block_start). */
+  createStreamParser() {
+    return (event) => this.parseStreamEvent(event);
+  }
   parseUsage(u) {
     if (!u) return emptyUsage();
     const inputTokens = u.input_tokens ?? 0;
@@ -23911,6 +24133,18 @@ var GoogleAdapter = class {
     };
   }
   parseStreamEvent(event) {
+    return this.streamEvents(event, { codeExec: false });
+  }
+  /** Stateful — Google splits the code-execution marker (`executableCode` /
+   *  `codeExecutionResult`) and the produced file (`inlineData`) across parts and
+   *  often across SSE events. The closure remembers "code execution began in this
+   *  stream" so a later `inlineData` blob is routed to `files` (a code-exec
+   *  artifact) rather than `media` (conversational output). */
+  createStreamParser() {
+    const state = { codeExec: false };
+    return (event) => this.streamEvents(event, state);
+  }
+  streamEvents(event, state) {
     const data = JSON.parse(event.data);
     const candidates = data.candidates ?? [];
     const candidate = candidates[0];
@@ -23924,6 +24158,9 @@ var GoogleAdapter = class {
     const rawContent = candidate.content ?? {};
     const parts = rawContent.parts ?? [];
     const events = [];
+    for (const part of parts) {
+      if (part.executableCode || part.codeExecutionResult) state.codeExec = true;
+    }
     for (const part of parts) {
       if (part.text !== void 0 && !part.thought)
         events.push({ type: "text", text: part.text });
@@ -23931,10 +24168,17 @@ var GoogleAdapter = class {
       if (part.inlineData) {
         const inline = part.inlineData;
         const mime = inline.mimeType;
-        const mediaType = mime.startsWith("image/") ? "image" : mime.startsWith("audio/") ? "audio" : "video";
-        events.push({ type: "media_start", mediaType, mimeType: mime });
-        events.push({ type: "media_chunk", data: inline.data });
-        events.push({ type: "media_end" });
+        if (state.codeExec) {
+          events.push({
+            type: "file",
+            file: { data: inline.data, mimeType: mime, source: "code_execution" }
+          });
+        } else {
+          const mediaType = mime.startsWith("image/") ? "image" : mime.startsWith("audio/") ? "audio" : "video";
+          events.push({ type: "media_start", mediaType, mimeType: mime });
+          events.push({ type: "media_chunk", data: inline.data });
+          events.push({ type: "media_end" });
+        }
       }
       if (part.functionCall) {
         const fc = part.functionCall;
@@ -24229,6 +24473,10 @@ var GoogleInteractionsAdapter = class {
     }
     return events;
   }
+  /** Stateless — the Interactions adapter surfaces no code-execution file outputs. */
+  createStreamParser() {
+    return (event) => this.parseStreamEvent(event);
+  }
   parseUsage(u) {
     if (!u) return emptyUsage();
     const input = u.total_input_tokens ?? u.prompt_tokens ?? 0;
@@ -25194,6 +25442,10 @@ var OpenAIAdapter = class {
     }
     return events;
   }
+  /** Stateless — Chat Completions has no hosted code-execution file outputs. */
+  createStreamParser() {
+    return (event) => this.parseStreamEvent(event);
+  }
   parseUsage(u) {
     if (!u) return emptyUsage();
     const input = u.prompt_tokens ?? u.input_tokens ?? 0;
@@ -25709,6 +25961,33 @@ function filenameForMime(mimeType) {
   if (mimeType.startsWith("image/")) return `file.${mimeType.slice("image/".length)}`;
   return "file.bin";
 }
+function filesFromResponsesOutputItem(item) {
+  const files = [];
+  const type = item.type;
+  if (type === "message") {
+    for (const c of item.content ?? []) {
+      if (c.type !== "output_text") continue;
+      for (const a of c.annotations ?? []) {
+        if (a.type === "container_file_citation" && typeof a.file_id === "string") {
+          files.push({
+            id: a.file_id,
+            ...typeof a.filename === "string" ? { name: a.filename } : {},
+            ...typeof a.container_id === "string" ? { ref: { containerId: a.container_id } } : {},
+            source: "code_execution"
+          });
+        }
+      }
+    }
+  }
+  if (type === "code_interpreter_call") {
+    for (const out of item.outputs ?? []) {
+      if (out.type === "image" && typeof out.url === "string") {
+        files.push({ url: out.url, source: "code_execution" });
+      }
+    }
+  }
+  return files;
+}
 var OpenAIResponsesAdapter = class {
   name = "openai";
   apiKey;
@@ -25889,6 +26168,7 @@ var OpenAIResponsesAdapter = class {
     let text = "";
     for (const item of output) {
       const type = item.type;
+      files.push(...this.filesFromOutputItem(item));
       if (type === "message") {
         const itemContent = item.content ?? [];
         for (const c of itemContent) {
@@ -25896,22 +26176,6 @@ var OpenAIResponsesAdapter = class {
             const t = c.text;
             text += t;
             content.push({ type: "text", text: t });
-            for (const a of c.annotations ?? []) {
-              if (a.type === "container_file_citation" && typeof a.file_id === "string") {
-                files.push({
-                  id: a.file_id,
-                  ...typeof a.filename === "string" ? { name: a.filename } : {},
-                  source: "code_execution"
-                });
-              }
-            }
-          }
-        }
-      }
-      if (type === "code_interpreter_call") {
-        for (const out of item.outputs ?? []) {
-          if (out.type === "image" && typeof out.url === "string") {
-            files.push({ url: out.url, source: "code_execution" });
           }
         }
       }
@@ -26006,6 +26270,7 @@ 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 });
       if (item?.type === "function_call") {
         events.push({ type: "tool_call_end", id: item.call_id ?? "" });
       }
@@ -26036,6 +26301,17 @@ var OpenAIResponsesAdapter = class {
     }
     return events;
   }
+  /** Stateless — each output item finalizes with all its file annotations in a
+   *  single response.output_item.done event. */
+  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;
@@ -26600,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) {
@@ -26619,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
@@ -27757,6 +28068,19 @@ var AgentLoop = class _AgentLoop {
   get model() {
     return this.client.model;
   }
+  // ─── File retrieval (hosted-tool output files) ──────────────────────────
+  /** Fetch a hosted-tool output file from the run's `response.files` — its bytes
+   *  as a `Blob` plus `name` / `mimeType` / `size`. Delegates to the underlying
+   *  client, so it uses this agent's provider + key (same as `retrieveFile` on a
+   *  `complete()` result). */
+  retrieveFile(file) {
+    return this.client.retrieveFile(file);
+  }
+  /** Stream a hosted-tool output file (large files) — a `ReadableStream` plus
+   *  best-effort `name` / `mimeType` / `size`. Delegates to the underlying client. */
+  streamFile(file) {
+    return this.client.streamFile(file);
+  }
   get system() {
     return this._system;
   }
@@ -34391,7 +34715,13 @@ async function complete(opts) {
         serviceTier
       });
     }
-    const result = { text: res.text, response: res };
+    const result = {
+      text: res.text,
+      response: res,
+      // Bound to this call's client (same provider/model/key/engine).
+      retrieveFile: (file) => llm.retrieveFile(file),
+      streamFile: (file) => llm.streamFile(file)
+    };
     if (opts.structured?.schema) {
       result.parsed = parseStructured(res.text);
     }
@@ -36526,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",
@@ -36541,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());
@@ -36610,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/client.d.ts

@@ -18,10 +18,11 @@
  *  Hooks emitted: onClientCreate (in ctor), onMessageResolve, onBeforeSubmit,
  *  onCompletion, onClientDestroy. */
 import type { HookBus } from '../bus/hook-bus';
+import type { FileStream, RetrievedFile } from './files/retrieve';
 import type { ContentPart, Message } from './types/messages';
 import type { ExecuteOptions } from './types/options';
 import type { ApiType, ProviderName } from './types/provider';
-import type { CompletionResponse } from './types/response';
+import type { CompletionResponse, FileOutput } from './types/response';
 import type { StreamEvent } from './types/stream';
 import type { LLMClientConfig } from './client-config';
 export declare class LLMClient {
@@ -67,6 +68,16 @@ export declare class LLMClient {
     private moderationConfig;
     /** Fold a moderation stream event into the accumulating report. */
     private mergeModeration;
+    private retrieveContext;
+    /** Fetch a hosted-tool output file (e.g. a code-execution file from
+     *  `response.files`): its bytes as a `Blob` plus `name` / `mimeType` / `size`.
+     *  Resolves inline `data`, a `url`, or a provider file `id` — all through this
+     *  client's provider + auth + engine. */
+    retrieveFile(file: FileOutput): Promise<RetrievedFile>;
+    /** Stream a hosted-tool output file: a `ReadableStream<Uint8Array>` plus
+     *  best-effort `name` / `mimeType` / `size` (from the response headers). For large
+     *  files piped straight to a file / GridFS / HTTP response without buffering. */
+    streamFile(file: FileOutput): Promise<FileStream>;
     /** Submit a request. Returns the parsed CompletionResponse. */
     complete(input: string | ContentPart[] | Message[], options?: ExecuteOptions): Promise<CompletionResponse>;
     /** Run `complete` with a JSON Schema enforced via `structured`. Strips any