@combycode/llm-sdk 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [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
+- Hosted MCP tool `tunnel_id` target (OpenAI Secure MCP Tunnel) — reach a private/local MCP
+  server with no public URL alongside the existing `server_url` / `connector_id` targets. The
+  `mcp` builtin already forwards `params`; added the exported `McpToolParams` type for editor
+  help and a regression test locking the forwarding. (Realtime MCP tooling tracked separately.)
+- `ThinkingConfig.context` (`'auto' | 'current_turn' | 'all_turns'`) — maps to OpenAI's
+  Responses `reasoning.context`, controlling which prior-turn reasoning items are rendered back
+  to the model across a stateful conversation. OpenAI Responses-only; ignored by other providers.
+- Inline moderation via the `moderation` request option on `complete()`/`stream()`
+  (parity with OpenAI's `moderation` request field, extended to all providers). Report-only:
+  results attach to `CompletionResponse.moderation` (`ModerationReport`) and never block the call.
+  Native on the OpenAI provider (one round-trip on both Responses and Chat Completions); emulated
+  via OpenAI's moderations endpoint on every other provider (`mode: 'native' | 'emulate'`).
+  Streaming supports three strategies (`buffer` default / `parallel` / `post`) trading latency for
+  how early the flag reaches the consumer, surfaced as a `moderation` stream event. Emulation
+  requires an OpenAI key (reused from the client when it is the OpenAI provider, else
+  `moderation.apiKey`); missing key throws.
+- Unified `CompletionResponse.files` (`FileOutput[]`) - files produced by hosted tools
+  (code execution, etc.), independent of `media`. The Anthropic adapter surfaces
+  code-execution file outputs there by file id; OpenAI/Google/xAI producers to follow.
+- Model catalog: new `ModelInfo.availability` field (`limited` / `preview`, vs default
+  generally-available) so gated / early-access models are distinguishable from the
+  `status` lifecycle. (Entries for specific limited/preview models are populated by the
+  catalog pipeline.)
+- Anthropic: the unified `code_interpreter` builtin now maps to Anthropic's hosted
+  `code_execution` tool (GA on Messages) - it was previously silently skipped. Hosted
+  code execution is now usable across Anthropic / OpenAI / Google through one interface.
+- Google service tier, both directions (parity with OpenAI/Anthropic): a requested
+  unified `serviceTier` (`flex`/`standard`/`priority`) maps to Google's top-level
+  request field, and the billed `usageMetadata.serviceTier` is read back into
+  `usage.serviceTier` / `usage.pricingTier` for tiered cost tracking.
+  (New `providers/google/tiers.ts`.)
+
 ## [1.0.0] - 2026-06-13
 
 First public release.
@@ -16,4 +82,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

@@ -28,7 +28,7 @@ Requires Node ≥ 18 or Bun ≥ 1.1.
 import { complete } from '@combycode/llm-sdk';
 
 const r = await complete({
-  model: 'anthropic/claude-haiku-4-5', // provider/model, sent verbatim
+  model: 'anthropic/claude-haiku-4.5', // provider/model, sent verbatim
   apiKey: process.env.ANTHROPIC_API_KEY,
   prompt: 'Say hello in one word.',
 });

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

@@ -39,6 +39,7 @@ export declare class AgentLoop {
     private _toolTimeout;
     private _maxSteps;
     private _guardrails;
+    private _toolInputGuardrails;
     private _policy;
     private _approve;
     private _checkpoint;

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;