@combycode/llm-sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,55 @@ 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
+- Anthropic hosted code-execution **file outputs** now surface on `response.files` (verified
+  live). Three fixes, found by real-key testing: (1) the producer parsed the outdated
+  `code_execution_tool_result` shape, but the current `code_execution_20260521` tool emits
+  `bash_code_execution_tool_result` → `bash_code_execution_output.file_id` (now both are
+  handled); (2) code execution needs the beta endpoint — requests using `code_interpreter` now
+  hit `/v1/messages?beta=true`, without which no file outputs are returned; (3) `AgentLoop`'s
+  final response dropped `files` (and `moderation`) — both are now propagated from the final
+  LLM response in `complete()` and `stream()`.
+
+### Added
+- `AgentLoopConfig.toolInputGuardrails` (`ToolInputGuardrail[]`) — per-tool-call input
+  guardrails that validate a call's arguments before the permission/approval check. A trip
+  denies just that call (error result to the model) without halting the run or invoking the
+  HITL approver; a pass runs the normal permission/approval/execution path.
+- `AgentTool.customDataExtractor` — optional hook to derive out-of-band metadata from a
+  successful tool result, attached to that call's `ToolCallReport.customData`. The model never
+  sees it (for your own telemetry/routing/audit); a throwing extractor is swallowed.
+- Code-execution **file outputs** now surface on `response.files` across **all** providers
+  (completes the channel shipped in 1.1, which had only the Anthropic producer):
+  - OpenAI Responses: code-interpreter image outputs (by URL) and downloadable container
+    files (`container_file_citation` → file id + name).
+  - Google: hosted code-execution `inlineData` artifacts (base64), routed to `files`
+    instead of `media` when the turn used code execution.
+  - xAI: inherited from the OpenAI Responses adapter.
+  - `FileOutput` gains a `url` field (for providers that return a fetchable URL).
+
 ## [1.1.0] - 2026-06-30
 
 ### Added
@@ -53,5 +102,6 @@ First public release.
 - Service tiers end to end (request → bill → cost).
 - Cross-environment: runs on Node, Bun, and the browser. ESM, zero runtime deps.
 
+[1.2.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.2.0
 [1.1.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.1.0
 [1.0.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.0.0

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/guardrail-types.d.ts

@@ -46,6 +46,31 @@ export interface Guardrail {
     /** Return a decision; throw only for unexpected infrastructure errors. */
     check(ctx: GuardrailCheckContext): Promise<GuardrailDecision>;
 }
+/** Context for a tool-input guardrail: the specific tool call about to run. */
+export interface ToolInputGuardrailContext {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    callId: string;
+    step: number;
+    trace: TraceContext;
+}
+/** A tool-input guardrail decision. Unlike message-level guardrails it does NOT
+ *  halt the run — a trip denies just this one tool call. */
+export type ToolInputGuardrailDecision = {
+    pass: true;
+} | {
+    pass: false;
+    reason: string;
+};
+/** Validates a tool call's arguments BEFORE it executes (and before any HITL
+ *  approval interruption). On a trip the call is denied — the model receives the
+ *  denial reason as an error tool result; the run continues and the approver is
+ *  never consulted. Arguments are immutable once the model emits them, so a single
+ *  pre-execution check is sufficient. */
+export interface ToolInputGuardrail {
+    name: string;
+    check(ctx: ToolInputGuardrailContext): Promise<ToolInputGuardrailDecision> | ToolInputGuardrailDecision;
+}
 export interface GuardrailTriggeredContext {
     runId: string;
     agentId: string;

package/dist/agent/loop-config.d.ts

@@ -5,7 +5,7 @@ import type { CacheConfig, ThinkingConfig } from '../llm/types/request';
 import type { ConversationHistory } from './history';
 import type { HistorySnapshot } from './history-types';
 import type { AgentTool } from './types';
-import type { Guardrail } from './guardrail-types';
+import type { Guardrail, ToolInputGuardrail } from './guardrail-types';
 import type { PermissionPolicy } from '../plugins/permissions/policy';
 import type { ApprovalRequest, ApprovalDecision } from './approval-types';
 import type { Persistence } from '../plugins/persistence/types';
@@ -48,6 +48,10 @@ export interface AgentLoopConfig {
      *  output guardrails run after each step's response is produced.
      *  A tripwire decision halts the run with finishReason 'guardrail'. */
     guardrails?: Guardrail[];
+    /** Per-tool-call input guardrails. Each runs against a tool call's arguments
+     *  BEFORE the permission/approval check and execution. A trip denies just that
+     *  call (error result to the model) without halting the run or invoking `approve`. */
+    toolInputGuardrails?: ToolInputGuardrail[];
     /** Permission policy wired into the tool-execution path.
      *  Called after lookup, before execution.
      *  'allow' -> proceed; 'deny' -> tool is blocked (error result to model);

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';
@@ -39,6 +40,7 @@ export declare class AgentLoop {
     private _toolTimeout;
     private _maxSteps;
     private _guardrails;
+    private _toolInputGuardrails;
     private _policy;
     private _approve;
     private _checkpoint;
@@ -51,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/agent/types.d.ts

@@ -39,6 +39,11 @@ export interface AgentTool {
     definition: Tool;
     /** Execute the tool. Return string or structured content. */
     execute: (args: Record<string, unknown>, context: ToolExecutionContext) => Promise<string | ContentPart[]>;
+    /** Optional: derive out-of-band metadata from a successful tool result, attached
+     *  to this call's `ToolCallReport.customData`. The MODEL NEVER SEES IT — it is for
+     *  your own telemetry/routing/audit. Runs after `execute`; may be async. Errors are
+     *  swallowed (opt-in convenience must never break the tool result). */
+    customDataExtractor?: (result: string | ContentPart[], args: Record<string, unknown>, context: Omit<ToolExecutionContext, 'signal'>) => unknown | Promise<unknown>;
 }
 export interface ToolExecutionContext {
     step: number;
@@ -65,6 +70,9 @@ export interface ToolCallReport {
         value: number | string | boolean;
         type: string;
     }>;
+    /** Out-of-band metadata from the tool's `customDataExtractor`, if any. Never sent
+     *  to the model; present only when an extractor returned a value. */
+    customData?: unknown;
 }
 export interface StepReport {
     index: number;

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>>;