@combycode/llm-sdk 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-06
+
+### Added
+- **Streaming file parity.** `stream()` now surfaces hosted code-execution output files with the
+  same coverage as `complete()`: a new `{ type: 'file', file }` `StreamEvent` is emitted as each
+  file finalizes mid-stream, and the files are collected onto the streamed final response's
+  `files` (via `onCompletion` / the agent final response). New `ProviderAdapter.createStreamParser()`
+  returns a per-stream parser so adapters can hold per-stream state — used by Google to route an
+  inline code-execution artifact (whose "code ran" marker and bytes arrive in separate SSE events)
+  to `files` rather than conversational `media`. Verified live on Anthropic, OpenAI, and Google.
+- **File-content retrieval** for hosted-tool output files. `CompleteResult`, `LLMClient`, and
+  the agent result now expose `retrieveFile(file)` → `{ blob, name, mimeType, size }` and
+  `streamFile(file)` → `{ stream, name, mimeType, size }`, resolving a `FileOutput`'s inline
+  `data`, `url`, or provider file `id` through the same model + key the call used — no
+  re-passing credentials. `streamFile` pipes large files to a sink without buffering. Name /
+  mime / size come from the download response headers (Content-Disposition / Content-Type /
+  Content-Length, with a filename-extension mime fallback). New network `responseType: 'stream'`
+  returns the raw body and releases the queue slot immediately. Exports `RetrievedFile`,
+  `FileStream`. Auth is sent only to the provider's own host.
+
 ## [1.2.0] - 2026-07-05
 
 ### Fixed

package/README.md

@@ -64,6 +64,28 @@ for await (const ev of llm.stream('Count to 5.')) {
 }
 ```
 
+### Hosted code execution + output files
+
+Run the provider's code interpreter and pull the files it produces (charts, CSVs) — one
+interface, any provider. `retrieveFile` / `streamFile` fetch the bytes plus `name` / `mimeType`
+/ `size`, bound to the same model + key:
+
+```ts
+import { complete } from '@combycode/llm-sdk';
+
+const { response, retrieveFile } = await complete({
+  model: 'anthropic/claude-haiku-4.5',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  prompt: 'Plot y = x**2 for x in 1..5, save a PNG, and return the file.',
+  tools: [{ type: 'code_interpreter' }],
+  maxTokens: 6000,
+});
+
+for (const file of response.files ?? []) {
+  const { blob, name, mimeType, size } = await retrieveFile(file); // or streamFile for large files
+}
+```
+
 ## Documentation
 
 Full guide pages covering all export groups:
@@ -77,6 +99,8 @@ Full guide pages covering all export groups:
   - [Cost Tracking + estimate()](./docs/guide/cost.md)
   - [Observability / Telemetry](./docs/guide/telemetry.md)
   - [Media / Files / Batch](./docs/guide/media-files-batch.md)
+  - [Hosted Code Execution](./docs/guide/code-execution.md)
+  - [Retrieving Output Files](./docs/guide/retrieving-files.md)
   - [MCP (Model Context Protocol)](./docs/guide/mcp.md)
   - [Context Guard + Permissions + Persistence + Cache](./docs/guide/context-guard.md)
   - [OpenAI-Compatible Server](./docs/guide/server.md)

package/dist/agent/loop.d.ts

@@ -13,7 +13,8 @@
 import { HookBus } from '../bus/hook-bus';
 import { type ContentPart, type Message } from '../llm/types/messages';
 import type { ExecuteOptions } from '../llm/types/options';
-import { type CompletionResponse } from '../llm/types/response';
+import { type CompletionResponse, type FileOutput } from '../llm/types/response';
+import type { FileStream, RetrievedFile } from '../llm/files/retrieve';
 import type { LLMClient } from '../llm/client';
 import { ConversationHistory } from './history';
 import type { AgentLoopSnapshot, AgentRunReport, AgentStreamEvent, AgentTool } from './types';
@@ -52,6 +53,14 @@ export declare class AgentLoop {
     destroy(): void;
     /** Model is owned by client. */
     get model(): string;
+    /** 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: FileOutput): Promise<RetrievedFile>;
+    /** Stream a hosted-tool output file (large files) — a `ReadableStream` plus
+     *  best-effort `name` / `mimeType` / `size`. Delegates to the underlying client. */
+    streamFile(file: FileOutput): Promise<FileStream>;
     get system(): string;
     set system(v: string);
     get context(): string;

package/dist/helpers/one-shot.d.ts

@@ -18,7 +18,8 @@ import type { AgentTool } from '../agent/types';
 import type { LLMClientConfig } from '../llm/client-config';
 import type { AudioOptions } from '../llm/types/audio';
 import type { ContentPart, Message } from '../llm/types/messages';
-import type { CompletionResponse } from '../llm/types/response';
+import type { CompletionResponse, FileOutput } from '../llm/types/response';
+import type { FileStream, RetrievedFile } from '../llm/files/retrieve';
 import type { ProviderName } from '../llm/types/provider';
 import type { ServiceTier } from '../llm/types/tiers';
 import type { BuiltinTool } from '../llm/types/tools';
@@ -82,5 +83,11 @@ export interface CompleteResult<T = unknown> {
      *  otherwise `undefined`. The generic on `complete<T>(...)` types this. */
     parsed?: T;
     response: CompletionResponse;
+    /** Fetch a hosted-tool output file (from `response.files`): bytes (`Blob`) +
+     *  `name` / `mimeType` / `size` — bound to the SAME model + key this call used. */
+    retrieveFile(file: FileOutput): Promise<RetrievedFile>;
+    /** Stream a hosted-tool output file (`ReadableStream` + `name` / `mimeType` /
+     *  `size`) — for large files piped straight to a sink. Same model + key. */
+    streamFile(file: FileOutput): Promise<FileStream>;
 }
 export declare function complete<T = unknown>(opts: CompleteOptions): Promise<CompleteResult<T>>;

package/dist/index.browser.js

@@ -2524,7 +2524,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;
@@ -22427,6 +22427,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,
@@ -22669,6 +22823,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);
@@ -22880,17 +23056,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;
@@ -22928,6 +23105,9 @@ var LLMClient = class {
         case "done":
           finishReason = event.finishReason;
           break;
+        case "file":
+          files.push(event.file);
+          break;
         case "moderation":
           moderationReport = this.mergeModeration(
             moderationReport,
@@ -22950,6 +23130,7 @@ var LLMClient = class {
       toolCalls: [],
       thinking: thinking || null,
       media: [],
+      ...files.length ? { files } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -23210,6 +23391,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;
@@ -23390,15 +23587,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, {
@@ -23437,6 +23627,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") {
     }
@@ -23460,6 +23652,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;
@@ -23984,6 +24181,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];
@@ -23997,6 +24206,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 });
@@ -24004,10 +24216,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;
@@ -24302,6 +24521,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;
@@ -25267,6 +25490,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;
@@ -25782,6 +26009,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;
@@ -25962,6 +26216,7 @@ var OpenAIResponsesAdapter = class {
     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) {
@@ -25969,22 +26224,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" });
           }
         }
       }
@@ -26079,6 +26318,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 ?? "" });
       }
@@ -26109,6 +26349,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;
@@ -27830,6 +28075,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;
   }
@@ -34464,7 +34722,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/index.d.ts

@@ -49,6 +49,7 @@ 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 { FileStream, RetrievedFile } from './llm/files/retrieve';
 export type { NormalizedRequest, ReasoningContext, ThinkingConfig, CacheConfig } from './llm/types/request';
 export type { MediaStreamType, StreamEvent } from './llm/types/stream';
 export type { ExecuteOptions } from './llm/types/options';

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;
@@ -23317,15 +23514,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 +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") {
     }
@@ -23387,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;
@@ -23911,6 +24108,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 +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 });
@@ -23931,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;
@@ -24229,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;
@@ -25194,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;
@@ -25709,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;
@@ -25889,6 +26143,7 @@ var OpenAIResponsesAdapter = class {
     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) {
@@ -25896,22 +26151,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 +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 ?? "" });
       }
@@ -26036,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;
@@ -27757,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;
   }
@@ -34391,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>;

package/dist/llm/providers/anthropic/messages.d.ts

@@ -26,5 +26,8 @@ export declare class AnthropicAdapter implements ProviderAdapter {
     private buildContentPart;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — every event is self-contained (code-execution result blocks
+     *  arrive complete in a single content_block_start). */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

package/dist/llm/providers/google/generate.d.ts

@@ -23,5 +23,12 @@ export declare class GoogleAdapter implements ProviderAdapter {
     private buildContent;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** 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(): (event: SSEEvent) => StreamEvent[];
+    private streamEvents;
     private parseUsage;
 }

package/dist/llm/providers/google/interactions.d.ts

@@ -26,5 +26,7 @@ export declare class GoogleInteractionsAdapter implements ProviderAdapter {
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — the Interactions adapter surfaces no code-execution file outputs. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

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

@@ -21,5 +21,7 @@ export declare class OpenAIAdapter implements ProviderAdapter {
     enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — Chat Completions has no hosted code-execution file outputs. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

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

@@ -25,5 +25,8 @@ export declare class OpenAIResponsesAdapter implements ProviderAdapter {
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — each output item finalizes with all its file annotations in a
+     *  single response.output_item.done event. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     protected parseUsage(u: Record<string, unknown> | undefined): Usage;
 }

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

@@ -25,8 +25,16 @@ export interface ProviderAdapter {
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
     /** Parse provider's raw HTTP response body to a normalized CompletionResponse. */
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
-    /** Convert one SSE event from the provider stream into zero or more StreamEvents. */
+    /** Convert one SSE event from the provider stream into zero or more StreamEvents.
+     *  Stateless per-event primitive — see `createStreamParser` for the per-stream
+     *  entry point the client actually calls. */
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Create a per-stream parser. Returns a function that converts each SSE event
+     *  into zero or more StreamEvents, holding any per-stream state (e.g. whether the
+     *  turn has begun hosted code execution) in its closure. The client calls this
+     *  once per `stream()` so each stream gets isolated state. Stateless adapters
+     *  return `parseStreamEvent` bound to themselves. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     /** Auth headers (Bearer / x-api-key / etc.). */
     authHeaders(): Record<string, string>;
     /** Base URL — provider's domain root. */

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

@@ -39,6 +39,10 @@ export interface FileOutput {
     url?: string;
     /** What produced it (e.g. 'code_execution'). */
     source?: string;
+    /** Provider-specific retrieval hints, used by `retrieveFile`/`streamFile` when the
+     *  file is fetched by `id` (e.g. OpenAI container files set `{ containerId }`).
+     *  Absent for providers that don't need extra context. */
+    ref?: Record<string, unknown>;
 }
 export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
 export interface Usage {

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

@@ -1,6 +1,6 @@
 /** Universal streaming event types. */
 import type { ModerationEntry } from '../moderation/types';
-import type { Usage } from './response';
+import type { FileOutput, Usage } from './response';
 export type MediaStreamType = 'image' | 'audio' | 'video';
 export type StreamEvent = {
     type: 'text';
@@ -41,6 +41,14 @@ export type StreamEvent = {
     type: 'media_end';
     mediaId?: string;
 }
+/** A hosted-tool output file (e.g. a code-execution chart/CSV) became available.
+ *  Carries the `FileOutput` descriptor (id / url / inline data + name / mimeType),
+ *  not the bytes — fetch those via `retrieveFile` / `streamFile`. The same file
+ *  is also collected onto the streamed final response's `files`. */
+ | {
+    type: 'file';
+    file: FileOutput;
+}
 /** 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/network/types.d.ts

@@ -15,8 +15,10 @@ export interface HttpRequest {
     model: string;
     /** How to parse the response body. Default 'json' (LLM responses, image-gen
      *  with b64_json, video-status JSON). Use 'arraybuffer' for binary downloads
-     *  (TTS audio bytes, video file bytes). 'text' for plain-text responses. */
-    responseType?: 'json' | 'arraybuffer' | 'text';
+     *  (TTS audio bytes, video file bytes). 'text' for plain-text responses.
+     *  'stream' returns the raw `ReadableStream<Uint8Array>` body un-buffered (large
+     *  file downloads that pipe straight to a sink). */
+    responseType?: 'json' | 'arraybuffer' | 'text' | 'stream';
     /** When the request body is already a Uint8Array / ArrayBuffer (binary
      *  upload like multipart) the queue should NOT JSON.stringify it. Default
      *  false → body is JSON.stringify'd. */

package/package.json

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