@combycode/llm-sdk 1.2.0 → 1.4.0

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/builtin-tools.d.ts

@@ -0,0 +1,15 @@
+/** Hosted server-side tools each provider's chat models support.
+ *
+ *  This is ADAPTER-SOURCED: it reflects what the provider adapters actually map
+ *  the unified `{ type: 'web_search' | 'code_interpreter' }` builtins onto (each
+ *  to the provider's native shape), verified by the live tools-parity test. It is
+ *  applied PROVIDER-LEVEL to tool-capable (chat-family) models at catalog load —
+ *  a deliberate first pass; a reliable per-model source can refine it later.
+ *
+ *  Coverage (verified live 2026-07):
+ *    - web_search       → anthropic, openai, google, xai, openrouter
+ *    - code_interpreter → anthropic, openai, google, xai   (NOT openrouter: it
+ *      proxies function tools + its own plugins, but does not route hosted code
+ *      execution — confirmed against the API). */
+import type { ProviderName } from '../types/provider';
+export declare const PROVIDER_BUILTIN_TOOLS: Record<ProviderName, readonly string[]>;

package/dist/llm/providers/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

@@ -5,7 +5,7 @@
 import type { SSEEvent } from '../../../network/types';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
-import { type CompletionResponse, type Usage } from '../../types/response';
+import { type CompletionResponse, type FileOutput, type Usage } from '../../types/response';
 import type { StreamEvent } from '../../types/stream';
 export interface OpenAIResponsesAdapterConfig {
     apiKey: string;
@@ -25,5 +25,12 @@ 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[];
+    /** Hosted code-execution output files from one output item. Overridable so
+     *  Responses-compatible providers with a different file shape (e.g. xAI, which
+     *  embeds files in the code-interpreter `logs` payload) can extend it. */
+    protected filesFromOutputItem(item: Record<string, unknown>): FileOutput[];
     protected parseUsage(u: Record<string, unknown> | undefined): Usage;
 }

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

@@ -7,6 +7,7 @@
  */
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
+import type { FileOutput } from '../../types/response';
 import { OpenAIResponsesAdapter } from '../openai/responses';
 export interface XAIResponsesAdapterConfig {
     apiKey: string;
@@ -17,4 +18,7 @@ export declare class XAIResponsesAdapter extends OpenAIResponsesAdapter {
     constructor(config: XAIResponsesAdapterConfig);
     baseURL(): string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** xAI embeds code-execution files inline in the `logs` payload — extend the base
+     *  extraction (which handles OpenAI-style annotations / image URLs) with the xAI shape. */
+    protected filesFromOutputItem(item: Record<string, unknown>): FileOutput[];
 }

package/dist/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/dist/plugins/model-catalog/catalog.d.ts

@@ -140,6 +140,11 @@ export declare class ModelCatalog {
     getPreferredApi(provider: string, model: string): ApiType | null;
     supportsApi(provider: string, model: string, api: ApiType): boolean;
     supportsTools(provider: string, model: string): boolean;
+    /** Hosted server-side builtin tools this model supports (e.g. `['web_search',
+     *  'code_interpreter']`). Empty when unknown or the model isn't tool-capable. */
+    builtinToolsFor(provider: string, model: string): string[];
+    /** Whether this model supports a specific hosted builtin tool. */
+    supportsBuiltinTool(provider: string, model: string, tool: string): boolean;
     supportsPreviousResponseId(provider: string, model: string): boolean;
     /** Server-state retention as a duration string ("30d", "72h"), or null if unsupported. */
     getStateRetention(provider: string, model: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",