@combycode/llm-sdk 1.5.0 → 1.6.0

package/dist/llm/client-internal.d.ts

@@ -7,8 +7,19 @@ import type { LLMClientConfig } from './client-config';
 import type { ContentPart, Message } from './types/messages';
 import type { ExecuteOptions } from './types/options';
 import type { ApiType, ProviderAdapter, ProviderName } from './types/provider';
+import type { CompletionResponse } from './types/response';
 export declare const PRIORITY_INTERACTIVE = 1;
 export declare const PRIORITY_BACKGROUND = 2;
+/** Build a history assistant message from a response, stamped with provenance
+ *  (id, createdAt, origin). On a stateful API (responses / interactions) the origin
+ *  carries the server-state id so a later turn can continue server-side instead of
+ *  resending the transcript. Shared by `LLMClient.assistantMessage` (manual multi-turn)
+ *  and the agent loop (so its tool turns also chain server-side). */
+export declare function buildAssistantMessage(response: CompletionResponse, origin: {
+    provider: ProviderName;
+    model: string;
+    api: ApiType;
+}): Message;
 export declare function normalizeInput(input: string | ContentPart[] | Message[]): Message[];
 /** Lift any role:'system' messages out of the input array.
  *  Anthropic and some other providers expect `system` as a top-level

package/dist/llm/output-errors.d.ts

@@ -0,0 +1,24 @@
+/** Typed errors for abnormal agent-run / structured-output outcomes.
+ *
+ *  `AgentRunError` is the shared base so callers can differentiate the failure
+ *  reason (`error.reason` or `instanceof`). Today only `invalid_final_output` is an
+ *  exception; `max_steps` / `model_refusal` remain returned results (differentiated
+ *  by `finishReason` / `AgentRunReport.reason`). A future run-error-handler config
+ *  can add `MaxStepsError` / `ModelRefusalError` under this base without a break. */
+export declare class AgentRunError extends Error {
+    /** Machine-readable failure reason (e.g. `'invalid_final_output'`). */
+    readonly reason: string;
+    constructor(reason: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The model's final output could not be parsed / validated against the requested
+ *  JSON schema. Carries the raw text so a caller can inspect, log, or retry. */
+export declare class InvalidFinalOutputError extends AgentRunError {
+    readonly reason: "invalid_final_output";
+    /** The raw model output that failed to parse. */
+    readonly rawText: string;
+    constructor(rawText: string, options?: {
+        cause?: unknown;
+    });
+}

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

@@ -26,8 +26,11 @@ 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). */
+    /** Stateful — Anthropic streams `server_tool_use` input via `input_json_delta`
+     *  (empty at block start) and returns the result in a separate `*_tool_result`
+     *  block. The closure accumulates each call's input (code / query) and attaches it
+     *  to the matching `builtin_tool_end`. */
     createStreamParser(): (event: SSEEvent) => StreamEvent[];
+    private streamEvents;
     private parseUsage;
 }

package/dist/llm/providers/builtin-tools.d.ts

@@ -10,6 +10,9 @@
  *    - 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). */
+ *      execution — confirmed against the API).
+ *    - web_fetch        → anthropic (web_fetch_20260318), google (urlContext).
+ *      OpenAI has no separate fetch tool (its web_search does page-open); xAI /
+ *      openrouter expose none. */
 import type { ProviderName } from '../types/provider';
 export declare const PROVIDER_BUILTIN_TOOLS: Record<ProviderName, readonly string[]>;

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

@@ -25,8 +25,18 @@ export declare class GoogleInteractionsAdapter implements ProviderAdapter {
     private toolCallNames;
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    /** Translate one Interactions SSE event to unified events. The 2.10 wire is a
+     *  step machine (verified live): `step.start` opens a typed step (`model_output`,
+     *  `function_call`, `thought`…), `step.delta` streams its payload (`{type:'text'}`,
+     *  `{type:'arguments_delta'}`, `{type:'thought_summary'}`, internal
+     *  `thought_signature`), `step.stop` closes it, and `interaction.completed` /
+     *  `interaction.failed` finish the turn (usage under `interaction.usage`). A
+     *  function call's `arguments_delta` carries no id, so we correlate it to the
+     *  currently-open call id held in `state`. */
+    private streamEvents;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
-    /** Stateless — the Interactions adapter surfaces no code-execution file outputs. */
+    /** Per-stream stateful parser — correlates a function call's streamed arguments
+     *  and end to the call opened by its `step.start`. */
     createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

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

@@ -0,0 +1,12 @@
+/** xAI service-tier mapping — provider-specific, kept out of the SDK core.
+ *
+ *  xAI's `ServiceTier` enum accepts only `SERVICE_TIER_DEFAULT` / `SERVICE_TIER_PRIORITY`
+ *  (verified against the xai-sdk proto). The OpenAI-inherited map emits `auto` / `flex` /
+ *  `scale`, which xAI rejects — so the xAI adapter remaps here instead of inheriting.
+ *  `standard` → xAI's `default`; anything xAI can't honor is omitted (the server then
+ *  uses its own default tier). The billed response value (`default` / `priority`) parses
+ *  correctly through the shared `openaiBilledTier` (`default` → `standard`), so only the
+ *  request direction needs an xAI-specific map. */
+import type { ServiceTier } from '../../types/tiers';
+/** unified → xAI request `service_tier` (`default` | `priority`), or `undefined` to omit. */
+export declare function xaiRequestTier(t?: ServiceTier): 'default' | 'priority' | undefined;

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

@@ -20,6 +20,12 @@ export interface ExecuteOptions {
     maxTokens?: number;
     temperature?: number;
     topP?: number;
+    /** Penalise tokens by prior presence ([-2, 2]). Honoured by OpenAI/xAI chat-completions,
+     *  OpenRouter, and Google (generateContent + Interactions); ignored by OpenAI/xAI Responses
+     *  and Anthropic, which don't accept it. */
+    presencePenalty?: number;
+    /** Penalise tokens by prior frequency ([-2, 2]). Same provider support as `presencePenalty`. */
+    frequencyPenalty?: number;
     stop?: string[];
     tools?: Tool[];
     toolChoice?: ToolChoice;
@@ -27,6 +33,10 @@ export interface ExecuteOptions {
         schema: Record<string, unknown>;
         name?: string;
         strict?: boolean;
+        /** Opt-in repair: if the model's final output fails to parse, re-prompt this
+         *  many times with the parse error before throwing `InvalidFinalOutputError`.
+         *  Default 0 (throw immediately). Honoured by `LLMClient.structuredComplete`. */
+        repairAttempts?: number;
     };
     audio?: AudioOptions;
     outputModalities?: Array<'text' | 'audio'>;

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

@@ -18,6 +18,10 @@ export interface NormalizedRequest {
     maxTokens?: number;
     temperature?: number;
     topP?: number;
+    /** Penalise tokens by prior presence (OpenAI/xAI chat-completions, OpenRouter, Google). */
+    presencePenalty?: number;
+    /** Penalise tokens by prior frequency (OpenAI/xAI chat-completions, OpenRouter, Google). */
+    frequencyPenalty?: number;
     stop?: string[];
     tools?: Tool[];
     toolChoice?: ToolChoice;
@@ -25,6 +29,8 @@ export interface NormalizedRequest {
         schema: Record<string, unknown>;
         name?: string;
         strict?: boolean;
+        /** Opt-in repair-retry count for `structuredComplete` (default 0). */
+        repairAttempts?: number;
     };
     thinking?: ThinkingConfig;
     cache?: CacheConfig;

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

@@ -48,13 +48,23 @@ export interface FileOutput {
      *  Absent for providers that don't need extra context. */
     ref?: Record<string, unknown>;
 }
-/** A hosted builtin tool the model invoked (provider-run). */
+/** A hosted builtin tool the model invoked (provider-run), with its inputs/outputs. */
 export interface BuiltinToolCall {
     /** Unified tool name: `'web_search'` | `'code_interpreter'` | … (normalized from
      *  each provider's native name — e.g. Anthropic `code_execution`). */
     tool: string;
     /** Provider call id, when available (correlates the stream start/end events). */
     id?: string;
+    /** `code_interpreter`: the code the model executed. */
+    code?: string;
+    /** `code_interpreter`: the code's textual output (stdout / logs). */
+    output?: string;
+    /** `web_search`: the query the model searched for (the first, if it issued several).
+     *  Absent for page-open/read steps — see `url`. */
+    query?: string;
+    /** `web_search`: the URL the model opened/read (OpenAI/xAI `open_page`/`find`
+     *  actions, which carry a URL instead of a query). Absent for plain searches. */
+    url?: string;
 }
 export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
 export interface Usage {

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

@@ -60,11 +60,17 @@ export type StreamEvent = {
     tool: string;
     id?: string;
 }
-/** A hosted builtin tool finished executing server-side. */
+/** A hosted builtin tool finished executing server-side. Carries its inputs/outputs
+ *  (`code` + `output` for code execution, `query` for web search) — the same payload
+ *  the client collects onto `response.builtinToolCalls`. */
  | {
     type: 'builtin_tool_end';
     tool: string;
     id?: string;
+    code?: string;
+    output?: string;
+    query?: string;
+    url?: string;
 }
 /** A moderation result for the input or output. `source` distinguishes a
  *  provider-native result from a client-emulated one. Emitted by the moderation

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

@@ -8,7 +8,7 @@ export interface FunctionTool {
     cache?: boolean;
 }
 export interface BuiltinTool {
-    type: 'image_generation' | 'web_search' | 'code_interpreter' | 'file_search' | 'mcp';
+    type: 'image_generation' | 'web_search' | 'web_fetch' | 'code_interpreter' | 'file_search' | 'mcp';
     params?: Record<string, unknown>;
 }
 /** Typed shape for an `mcp` builtin's `params` (OpenAI hosted MCP tool). The

package/package.json

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