@combycode/llm-sdk 1.1.0 → 1.3.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;
@@ -22354,6 +22354,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 +22750,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 +22983,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 +23032,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 +23057,7 @@ var LLMClient = class {
       toolCalls: [],
       thinking: thinking || null,
       media: [],
+      ...files.length ? { files } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23137,6 +23318,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;
@@ -23232,7 +23429,10 @@ var AnthropicAdapter = class {
     });
     const headers = {};
     if (hasFileRef) headers["anthropic-beta"] = "files-api-2025-04-14";
-    return { body, headers };
+    const usesCodeExec = req.tools?.some(
+      (t) => !isFunctionTool(t) && t.type === "code_interpreter"
+    );
+    return { body, headers, ...usesCodeExec ? { path: "/v1/messages?beta=true" } : {} };
   }
   enableStreaming(providerReq, _req) {
     providerReq.body.stream = true;
@@ -23314,15 +23514,8 @@ var AnthropicAdapter = class {
         };
         content.push(tc);
         toolCalls.push(tc);
-      } else if (block.type === "code_execution_tool_result") {
-        const result = block.content;
-        if (result?.type === "code_execution_result" && Array.isArray(result.content)) {
-          for (const out of result.content) {
-            if (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, {
@@ -23361,6 +23554,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") {
     }
@@ -23384,6 +23579,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;
@@ -23826,7 +24026,9 @@ var GoogleAdapter = class {
     const content = [];
     const toolCalls = [];
     const media = [];
+    const files = [];
     let thinking = null;
+    const hasCodeExec = parts.some((p) => p.executableCode || p.codeExecutionResult);
     for (const part of parts) {
       if (part.text !== void 0 && !part.thought) {
         content.push({ type: "text", text: part.text });
@@ -23837,7 +24039,9 @@ var GoogleAdapter = class {
       if (part.inlineData) {
         const inline = part.inlineData;
         const mime = inline.mimeType;
-        if (mime.startsWith("image/")) {
+        if (hasCodeExec) {
+          files.push({ data: inline.data, mimeType: mime, source: "code_execution" });
+        } else if (mime.startsWith("image/")) {
           const p = {
             type: "image_output",
             mediaId: "",
@@ -23898,11 +24102,24 @@ var GoogleAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...files.length ? { files } : {},
       latencyMs,
       raw
     };
   }
   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];
@@ -23916,6 +24133,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 });
@@ -23923,10 +24143,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;
@@ -24221,6 +24448,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;
@@ -25186,6 +25417,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;
@@ -25701,6 +25936,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;
@@ -25876,10 +26138,12 @@ var OpenAIResponsesAdapter = class {
     const content = [];
     const toolCalls = [];
     const media = [];
+    const files = [];
     let thinking = null;
     let text = "";
     for (const item of output) {
       const type = item.type;
+      files.push(...filesFromResponsesOutputItem(item));
       if (type === "message") {
         const itemContent = item.content ?? [];
         for (const c of itemContent) {
@@ -25939,6 +26203,7 @@ var OpenAIResponsesAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...files.length ? { files } : {},
       ...moderation ? { moderation } : {},
       latencyMs,
       raw
@@ -25980,6 +26245,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 });
       if (item?.type === "function_call") {
         events.push({ type: "tool_call_end", id: item.call_id ?? "" });
       }
@@ -26010,6 +26276,11 @@ 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);
+  }
   parseUsage(u) {
     if (!u) return emptyUsage();
     const input = u.input_tokens ?? 0;
@@ -27665,6 +27936,7 @@ var AgentLoop = class _AgentLoop {
   _toolTimeout;
   _maxSteps;
   _guardrails;
+  _toolInputGuardrails;
   _policy;
   _approve;
   _checkpoint;
@@ -27692,6 +27964,7 @@ var AgentLoop = class _AgentLoop {
     this._toolTimeout = config.toolTimeout ?? DEFAULT_TOOL_TIMEOUT_MS;
     this._maxSteps = config.maxSteps !== void 0 && config.maxSteps > 0 ? config.maxSteps : DEFAULT_MAX_STEPS;
     this._guardrails = config.guardrails ?? [];
+    this._toolInputGuardrails = config.toolInputGuardrails ?? [];
     this._policy = config.policy ?? null;
     this._approve = config.approve ?? null;
     this._checkpoint = config.checkpoint ?? null;
@@ -27729,6 +28002,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;
   }
@@ -27910,6 +28196,10 @@ var AgentLoop = class _AgentLoop {
       toolCalls: lastResponse?.toolCalls ?? [],
       thinking: lastResponse?.thinking ?? null,
       media: lastResponse?.media ?? [],
+      // 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?.moderation ? { moderation: lastResponse.moderation } : {},
       latencyMs: performance.now() - startPerf,
       raw: lastResponse?.raw ?? null
     };
@@ -28104,6 +28394,8 @@ var AgentLoop = class _AgentLoop {
       toolCalls: lastResponse?.toolCalls ?? [],
       thinking: lastResponse?.thinking ?? null,
       media: [],
+      ...lastResponse?.files ? { files: lastResponse.files } : {},
+      ...lastResponse?.moderation ? { moderation: lastResponse.moderation } : {},
       latencyMs: performance.now() - startPerf,
       raw: null
     };
@@ -28190,6 +28482,18 @@ var AgentLoop = class _AgentLoop {
       runTrace
     );
     if (!lookup.found) return lookup.errorResult;
+    for (const g of this._toolInputGuardrails) {
+      const decision = await g.check({
+        toolName: tc.name,
+        arguments: tc.arguments,
+        callId: tc.id,
+        step,
+        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id }
+      });
+      if (!decision.pass) {
+        return this.buildDeniedResult(tc, decision.reason, reports);
+      }
+    }
     if (this._policy !== null) {
       const target = {
         kind: "tool",
@@ -28206,7 +28510,7 @@ var AgentLoop = class _AgentLoop {
     try {
       const baseCtx = { step, callId: tc.id, metrics, trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id } };
       const result = await executeWithTimeout(lookup.tool, tc, baseCtx, this._toolTimeout);
-      return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace);
+      return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, lookup.tool, baseCtx);
     } catch (e) {
       return handleToolError(e, tc, this.hooks, runId, this.id, step, metrics, reports, toolStart, runTrace);
     }
@@ -28297,7 +28601,7 @@ var AgentLoop = class _AgentLoop {
       try {
         const baseCtx = { step, callId: tc.id, metrics, trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id } };
         const result = await executeWithTimeout(tool, tc, baseCtx, this._toolTimeout);
-        return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace);
+        return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, tool, baseCtx);
       } catch (e) {
         return handleToolError(e, tc, this.hooks, runId, this.id, step, metrics, reports, toolStart, runTrace);
       }
@@ -28309,9 +28613,16 @@ var AgentLoop = class _AgentLoop {
     return this.buildDeniedResult(tc, denyMsg, reports);
   }
   /** Emit onToolCallComplete, push report, and return success content part. */
-  async buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace) {
+  async buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, tool, context) {
     const latencyMs = performance.now() - toolStart;
     const resultStr = typeof result === "string" ? result : JSON.stringify(result);
+    let customData;
+    if (tool?.customDataExtractor && context) {
+      try {
+        customData = await tool.customDataExtractor(result, tc.arguments, context);
+      } catch {
+      }
+    }
     await this.hooks.emit("onToolCallComplete", {
       runId,
       agentId: this.id,
@@ -28333,7 +28644,8 @@ var AgentLoop = class _AgentLoop {
       latencyMs,
       skipped: false,
       error: null,
-      metrics: Object.fromEntries(metrics)
+      metrics: Object.fromEntries(metrics),
+      ...customData !== void 0 ? { customData } : {}
     });
     return { type: "tool_result", id: tc.id, content: resultStr };
   }
@@ -34337,7 +34649,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);
     }

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

package/dist/llm/files/retrieve.d.ts

@@ -0,0 +1,44 @@
+/** Retrieve the bytes of a hosted-tool output file (e.g. code-execution files).
+ *
+ *  A `FileOutput` may carry inline base64 `data` (Google), a `url` (OpenAI
+ *  code-interpreter images), or an `id` fetched from the provider's files API
+ *  (Anthropic, OpenAI container files). These helpers resolve all three into
+ *  bytes — buffered (`retrieveFile` → Blob) or streamed (`streamFile` →
+ *  ReadableStream, for large files piped straight to a sink).
+ *
+ *  All HTTP flows through the injected `EngineFetch` (auth, queue, cost, traces). */
+import type { EngineFetch } from '../../network/types';
+import type { ProviderName } from '../types/provider';
+import type { FileOutput } from '../types/response';
+export interface RetrieveContext {
+    provider: ProviderName;
+    apiKey: string;
+    fetch: EngineFetch;
+    /** Provider API base URL; defaults per provider when omitted. */
+    baseURL?: string;
+}
+/** A retrieved file's bytes plus the metadata an end user needs to display and
+ *  open it as an attachment (correct name + type). */
+export interface RetrievedFile {
+    blob: Blob;
+    /** Filename (from Content-Disposition, else the FileOutput name). */
+    name?: string;
+    /** MIME type (from Content-Type, else the FileOutput mime). */
+    mimeType: string;
+    /** Size in bytes. */
+    size: number;
+}
+/** A streamed file: its byte stream plus best-effort metadata (from the response
+ *  headers). The stream itself carries only bytes — name/type/size come from here. */
+export interface FileStream {
+    stream: ReadableStream<Uint8Array>;
+    name?: string;
+    mimeType?: string;
+    /** From Content-Length, when the provider sends it. */
+    size?: number;
+}
+/** Fetch the whole file as bytes (buffered) plus its name/type/size. */
+export declare function retrieveFile(file: FileOutput, ctx: RetrieveContext): Promise<RetrievedFile>;
+/** Stream the file's bytes (un-buffered) plus best-effort name/type/size. Pipe the
+ *  stream straight to a file, GridFS, or an HTTP response — nothing is buffered. */
+export declare function streamFile(file: FileOutput, ctx: RetrieveContext): Promise<FileStream>;