@combycode/llm-sdk 1.2.0 → 1.4.0

package/CHANGELOG.md

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