@combycode/llm-sdk 1.0.0-rc.0

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

@@ -0,0 +1,13 @@
+/** OpenAI service-tier mapping — provider-specific, kept here (shared by the
+ *  responses + completions adapters), never leaked into the SDK core.
+ *  Request param + response value share the enum: auto|default|flex|scale|priority. */
+import type { ServiceTier } from '../../types/tiers';
+/** Map a unified tier to OpenAI's `service_tier`. Unknown values pass through if
+ *  OpenAI accepts them, otherwise fall back to `auto`. Undefined → omit. */
+export declare function openaiRequestTier(t?: ServiceTier): string | undefined;
+/** OpenAI billed `service_tier` (response) → {raw, normalized catalog key}.
+ *  `default` is OpenAI's word for the standard tier. */
+export declare function openaiBilledTier(raw: unknown): {
+    serviceTier?: string;
+    pricingTier?: string;
+};

package/dist/llm/providers/openai/transcription.d.ts

@@ -0,0 +1,20 @@
+/** OpenAI transcription adapter — POST /v1/audio/transcriptions (multipart).
+ *  All HTTP flows through the injected EngineFetch (rawBody multipart, like the
+ *  batch file upload). gpt-4o-transcribe / whisper return `{ text }`. */
+import type { EngineFetch } from '../../../network/types';
+export interface OpenAITranscriptionAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export interface TranscriptionRequest {
+    bytes: Uint8Array;
+    mimeType: string;
+    model: string;
+    language?: string;
+}
+export declare class OpenAITranscriptionAdapter {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAITranscriptionAdapterConfig);
+    transcribe(req: TranscriptionRequest, fetch: EngineFetch): Promise<string>;
+}

package/dist/llm/providers/openrouter/completions.d.ts

@@ -0,0 +1,15 @@
+/** OpenRouter provider adapter — OpenAI-compatible with extensions. */
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { OpenAIAdapter } from '../openai/completions';
+export interface OpenRouterAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenRouterAdapter extends OpenAIAdapter {
+    readonly name: ProviderAdapter['name'];
+    constructor(config: OpenRouterAdapterConfig);
+    baseURL(): string;
+    completionPath(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+}

package/dist/llm/providers/openrouter/embeddings.d.ts

@@ -0,0 +1,7 @@
+/** OpenRouter embeddings adapter — OpenAI-compatible at openrouter.ai/api/v1. */
+import { OpenAIEmbeddingAdapter, type OpenAIEmbeddingAdapterConfig } from '../openai/embeddings';
+export declare class OpenRouterEmbeddingAdapter extends OpenAIEmbeddingAdapter {
+    readonly name: string;
+    constructor(config: OpenAIEmbeddingAdapterConfig);
+    protected embeddingsPath(): string;
+}

package/dist/llm/providers/openrouter/media.d.ts

@@ -0,0 +1,25 @@
+/** OpenRouter media adapter. OpenRouter has NO dedicated media endpoints —
+ *  image (and audio) generation go through `POST /api/v1/chat/completions` with
+ *  a `modalities` field; output comes back on `message.images[]` /
+ *  `message.audio`. Cost is the provider-reported `usage.cost`. */
+import type { EngineFetch } from '../../../network/types';
+import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult } from '../../../plugins/media/types';
+export interface OpenRouterMediaAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenRouterMediaAdapter implements MediaProviderAdapter {
+    readonly name = "openrouter";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenRouterMediaAdapterConfig);
+    capabilities(): MediaCapabilities;
+    private authHeaders;
+    generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    editImage(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
+    /** image_config from normalized params (aspect_ratio / image_size / strength). */
+    private imageConfig;
+    private chat;
+    private chatImage;
+}

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

@@ -0,0 +1,17 @@
+/** OpenRouter Responses API adapter.
+ *  Drop-in replacement for OpenAI Responses API at openrouter.ai/api/v1/responses.
+ *  Stateless: no previous_response_id support (beta limitation). */
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { OpenAIResponsesAdapter } from '../openai/responses';
+export interface OpenRouterResponsesAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenRouterResponsesAdapter extends OpenAIResponsesAdapter {
+    readonly name: ProviderAdapter['name'];
+    constructor(config: OpenRouterResponsesAdapterConfig);
+    baseURL(): string;
+    completionPath(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+}

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

@@ -0,0 +1,19 @@
+/** xAI batch adapter — create batch, add requests, poll, get results.
+ *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
+import type { EngineFetch } from '../../../network/types';
+import type { BatchProviderAdapter, BatchRequest, BatchResult, BatchStatus } from '../../../plugins/batch/types';
+export interface XAIBatchAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class XAIBatchAdapter implements BatchProviderAdapter {
+    readonly name = "xai";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: XAIBatchAdapterConfig);
+    private bearer;
+    submit(requests: BatchRequest[], fetch: EngineFetch): Promise<string>;
+    getStatus(batchId: string, fetch: EngineFetch): Promise<BatchStatus>;
+    getResults(batchId: string, fetch: EngineFetch): Promise<BatchResult[]>;
+    cancel(batchId: string, fetch: EngineFetch): Promise<void>;
+}

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

@@ -0,0 +1,24 @@
+/** xAI (Grok) provider adapter — OpenAI-compatible Chat Completions.
+ *  Key differences from OpenAI:
+ *  - Uses max_tokens (not max_completion_tokens)
+ *  - Reasoning via model variant (grok-*-reasoning), not reasoning param
+ *  - Returns reasoning_content in message (plain text, unlike OpenAI which hides it)
+ */
+import type { SSEEvent } from '../../../network/types';
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import type { CompletionResponse } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
+import { OpenAIAdapter } from '../openai/completions';
+export interface XAIAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class XAIAdapter extends OpenAIAdapter {
+    readonly name: ProviderAdapter['name'];
+    constructor(config: XAIAdapterConfig);
+    baseURL(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+}

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

@@ -0,0 +1,23 @@
+/** xAI file adapter — POST /v1/files (purpose=assistants).
+ *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
+import type { EngineFetch } from '../../../network/types';
+import type { FileAttachment } from '../../../plugins/files/attachment';
+import type { FileProviderAdapter, FileUploadResult, RemoteFileInfo } from '../../../plugins/files/provider-adapter';
+export interface XAIFileAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class XAIFileAdapter implements FileProviderAdapter {
+    readonly name = "xai";
+    readonly expiresAfter: null;
+    readonly maxFileSize = 48000000;
+    readonly supportedTypes: string[];
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: XAIFileAdapterConfig);
+    private bearer;
+    upload(file: FileAttachment, fetch: EngineFetch): Promise<FileUploadResult>;
+    delete(remoteId: string, fetch: EngineFetch): Promise<void>;
+    getInfo(remoteId: string, fetch: EngineFetch): Promise<RemoteFileInfo | null>;
+    list(fetch: EngineFetch): Promise<RemoteFileInfo[]>;
+}

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

@@ -0,0 +1,27 @@
+/** xAI media adapter — images, TTS, video. All HTTP through EngineFetch. */
+import type { EngineFetch } from '../../../network/types';
+import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult, VideoGenRequest, VideoStatus } from '../../../plugins/media/types';
+export interface XAIMediaAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class XAIMediaAdapter implements MediaProviderAdapter {
+    readonly name = "xai";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: XAIMediaAdapterConfig);
+    capabilities(): MediaCapabilities;
+    private authHeaders;
+    generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    /** Image-to-image edit via `/v1/images/edits` (JSON; base64 data-URL or
+     *  file_id, no multipart, no mask). */
+    editImage(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    /** Parse an images response (b64_json inline or url to download), attaching
+     *  xAI's provider cost (usage.cost_in_usd_ticks) to the first item. */
+    private parseImages;
+    generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
+    submitVideo(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
+    getVideoStatus(operationId: string, fetch: EngineFetch): Promise<VideoStatus>;
+    downloadVideo(operationId: string, fetch: EngineFetch): Promise<RawMediaResult>;
+    cancelVideo(operationId: string, fetch: EngineFetch): Promise<void>;
+}

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

@@ -0,0 +1,20 @@
+/** xAI Responses API adapter.
+ *  Mirrors OpenAI Responses API at api.x.ai/v1/responses.
+ *  Differences:
+ *  - System prompt via role:system in input (not instructions)
+ *  - Reasoning automatic for reasoning models (no effort param needed)
+ *  - Encrypted reasoning via include: ["reasoning.encrypted_content"]
+ */
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { OpenAIResponsesAdapter } from '../openai/responses';
+export interface XAIResponsesAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class XAIResponsesAdapter extends OpenAIResponsesAdapter {
+    readonly name: ProviderAdapter['name'];
+    constructor(config: XAIResponsesAdapterConfig);
+    baseURL(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+}

package/dist/llm/realtime/session.d.ts

@@ -0,0 +1,34 @@
+/** BaseRealtimeSession — wires an engine RealtimeConnection to the normalized
+ *  RealtimeSession event model. Providers subclass it and implement just the
+ *  protocol mapping (onOpen handshake, frame → event, input → wire frames). */
+import type { RealtimeConnection, RealtimeFrame } from '../../network/types';
+import type { RealtimeEvent, RealtimeEventType, RealtimeInput, RealtimeSession } from './types';
+export declare abstract class BaseRealtimeSession implements RealtimeSession {
+    protected readonly conn: RealtimeConnection;
+    private readonly listeners;
+    private ready;
+    private readonly outbox;
+    constructor(conn: RealtimeConnection);
+    on<E extends RealtimeEventType>(type: E, cb: (e: Extract<RealtimeEvent, {
+        type: E;
+    }>) => void): () => void;
+    close(): void;
+    abstract send(input: RealtimeInput, opts?: {
+        turnComplete?: boolean;
+    }): void;
+    /** Fan an event out to subscribers. */
+    protected emit(event: RealtimeEvent): void;
+    /** Mark the session ready: flush any buffered sends and emit `open`. Idempotent.
+     *  Called by the subclass once its handshake is complete (OpenAI: on socket
+     *  open; Google: on `setupComplete`). */
+    protected markReady(): void;
+    /** Run a wire-send now if ready, else buffer it until markReady(). Lets callers
+     *  `createRealtime(...).send(...)` without first awaiting an `open` event. */
+    protected whenReady(fn: () => void): void;
+    /** Send a JSON object as a text frame (the common wire form for both providers). */
+    protected sendJSON(obj: unknown): void;
+    /** Provider handshake on socket open (e.g. session.update / setup). */
+    protected abstract onOpen(): void;
+    /** Map one inbound provider frame onto zero or more normalized events. */
+    protected abstract onFrame(frame: RealtimeFrame): void;
+}

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

@@ -0,0 +1,66 @@
+/** Realtime / live session — the provider-agnostic DX surface.
+ *
+ *  A RealtimeSession normalizes two very different provider protocols (OpenAI's
+ *  typed event stream, Google's turn-based bidi) onto one event model. Provider
+ *  adapters own the wire mapping; the engine owns the WebSocket transport
+ *  (engine.connect — queue-exempt). */
+import type { EngineConnect } from '../../network/types';
+import type { Usage } from '../types/response';
+export type RealtimeModality = 'text' | 'audio';
+export interface RealtimeSessionConfig {
+    /** Bare model id (provider is fixed by the adapter). */
+    model: string;
+    /** Desired output modalities. Default `['text']`. Note: some models are
+     *  audio-native (Gemini Live streams audio regardless). */
+    modalities?: RealtimeModality[];
+    /** Voice id for audio output, where the provider supports selection. */
+    voice?: string;
+    /** System instructions for the session. */
+    instructions?: string;
+}
+/** One input turn (or partial turn) from the user. */
+export interface RealtimeInput {
+    text?: string;
+    /** Raw audio bytes (provider-specific encoding, e.g. PCM16). */
+    audio?: Uint8Array;
+}
+/** Normalized session events. Adapters map provider frames onto these. */
+export type RealtimeEvent = {
+    type: 'open';
+} | {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'audio';
+    chunk: Uint8Array;
+    mimeType: string;
+    sampleRate?: number;
+} | {
+    type: 'turnComplete';
+} | {
+    type: 'usage';
+    usage: Usage;
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'close';
+};
+export type RealtimeEventType = RealtimeEvent['type'];
+export interface RealtimeSession {
+    /** Send an input turn. `turnComplete` defaults to true (commit + request a
+     *  response now); pass false to stream a turn across multiple sends. */
+    send(input: RealtimeInput, opts?: {
+        turnComplete?: boolean;
+    }): void;
+    /** Subscribe to a normalized event. Returns an unsubscribe function. */
+    on<E extends RealtimeEventType>(type: E, cb: (e: Extract<RealtimeEvent, {
+        type: E;
+    }>) => void): () => void;
+    /** Close the underlying socket. */
+    close(): void;
+}
+/** Per-provider realtime adapter. Mirrors ProviderAdapter for request/response. */
+export interface RealtimeProviderAdapter {
+    connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
+}

package/dist/llm/server-state.d.ts

@@ -0,0 +1,32 @@
+/** Server-state decision — the unified "send id vs resend history" brain.
+ *
+ *  Several providers keep conversation state server-side (OpenAI Responses
+ *  `previous_response_id`, xAI, Google Interactions `previous_interaction_id`).
+ *  When the prior assistant turn carries a server id we produced, we can send
+ *  just that id + the new turn instead of the whole transcript.
+ *
+ *  Safe by default — reuse only when ALL hold:
+ *    - the caller didn't opt out (`stateful !== false`),
+ *    - the prior id was produced by the SAME provider (cross-provider ids are
+ *      meaningless elsewhere — history stays portable),
+ *    - the provider/model supports it (catalog),
+ *    - it's within the retention TTL (catalog duration),
+ *    - the model matches, OR the provider is not model-bound (catalog).
+ *  Otherwise we fall back to resending full history (always correct). */
+import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { Message } from './types/messages';
+import type { ProviderName } from './types/provider';
+export interface ServerStateDecision {
+    /** Provider-agnostic id to continue from (adapter maps to its own param). */
+    previousResponseId?: string;
+    /** Messages to actually send: trimmed to the new turn(s) when chaining, else full. */
+    messages: Message[];
+}
+export declare function resolveServerState(args: {
+    messages: Message[];
+    provider: ProviderName;
+    model: string;
+    catalog: ModelCatalog;
+    stateful: boolean;
+    now: number;
+}): ServerStateDecision;

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

@@ -0,0 +1,18 @@
+/** Shared audio types — one shape for voice/format options and raw audio input
+ *  across complete() / generateAudio() / createRealtime() / transcribe(). */
+export type AudioFormat = 'wav' | 'mp3' | 'pcm16' | 'opus' | 'flac' | 'aac';
+/** Output audio controls. `voice` accepts a provider voice id OR a unified alias
+ *  (see resolveVoice). */
+export interface AudioOptions {
+    voice?: string;
+    format?: AudioFormat;
+    /** Sample rate (Hz) for raw/PCM output. */
+    sampleRate?: number;
+}
+/** Audio input source. A file path is MIME-detected; raw bytes should declare
+ *  `mimeType` (and `sampleRate` for PCM). */
+export interface AudioInput {
+    data: Uint8Array | string;
+    mimeType?: string;
+    sampleRate?: number;
+}

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

@@ -0,0 +1,125 @@
+/** Universal message and content types — shared by LLM, Agent, Server. */
+import type { ProviderName } from './provider';
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+/** Producer-bound provenance for an assistant turn.
+ *
+ *  History is portable across providers, but some state is only valid for the
+ *  provider that produced it: a server-side conversation id (interaction_id /
+ *  response_id) and opaque signatures (Gemini thought-signatures, reasoning
+ *  blobs). Anything here MUST be ignored by a different provider — adapters
+ *  consume it only when `origin.provider === self`. */
+export interface MessageOrigin {
+    /** Provider that produced this assistant turn. The gate for cross-provider use. */
+    provider: ProviderName;
+    /** Model that produced it (for model-bound server-state checks). */
+    model?: string;
+    /** Server-side conversation id for stateful continuation (interaction_id / response_id). */
+    serverStateId?: string;
+    /** Opaque provider signatures to echo back (thought-signature, encrypted reasoning). */
+    signatures?: unknown;
+}
+export type ContentPart = TextPart | ImagePart | DocumentPart | AudioPart | VideoPart | ToolCallPart | ToolResultPart | ImageOutputPart | AudioOutputPart | VideoOutputPart;
+export interface TextPart {
+    type: 'text';
+    text: string;
+    cache?: boolean;
+}
+export interface ImagePart {
+    type: 'image';
+    source: DataSource;
+    detail?: 'auto' | 'low' | 'high';
+}
+export interface DocumentPart {
+    type: 'document';
+    source: DataSource;
+    citations?: boolean;
+}
+export interface AudioPart {
+    type: 'audio';
+    source: DataSource;
+}
+export interface VideoPart {
+    type: 'video';
+    source: DataSource;
+}
+export interface ToolCallPart {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    /** Provider-specific metadata (e.g. Google thought signatures). */
+    _meta?: Record<string, unknown>;
+}
+export interface ToolResultPart {
+    type: 'tool_result';
+    id: string;
+    content: string | ContentPart[];
+    isError?: boolean;
+}
+export interface ImageOutputPart {
+    type: 'image_output';
+    mediaId: string;
+    mimeType: string;
+    revisedPrompt?: string;
+    width?: number;
+    height?: number;
+    /** Transient: raw base64 from provider. Stripped after storage. */
+    _data?: string;
+}
+export interface AudioOutputPart {
+    type: 'audio_output';
+    mediaId: string;
+    mimeType: string;
+    durationMs?: number;
+    sampleRate?: number;
+    _data?: string;
+}
+export interface VideoOutputPart {
+    type: 'video_output';
+    mediaId: string;
+    mimeType: string;
+    durationMs?: number;
+    width?: number;
+    height?: number;
+    _data?: string;
+}
+export type MediaOutputPart = ImageOutputPart | AudioOutputPart | VideoOutputPart;
+export type DataSource = {
+    type: 'base64';
+    mimeType: string;
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'file';
+    fileId: string;
+} | {
+    type: 'path';
+    mimeType: string;
+    path: string;
+} | {
+    type: 'buffer';
+    mimeType: string;
+    data: Uint8Array;
+} | {
+    type: 'provider_ref';
+    mimeType: string;
+    refId: string;
+};
+export type Content = string | ContentPart[];
+export interface Message {
+    role: Role;
+    content: Content;
+    cache?: boolean;
+    /** Universal message id (ours) — for dedup / referencing / editing. */
+    id?: string;
+    /** Creation timestamp (ms epoch) — universal; drives server-state TTL checks. */
+    createdAt?: number;
+    /** Producer-bound provenance (assistant turns). See {@link MessageOrigin}. */
+    origin?: MessageOrigin;
+}
+/** Normalize any content to ContentPart array. */
+export declare function contentParts(content: Content): ContentPart[];
+/** Extract plain text from content. */
+export declare function contentText(content: Content): string;

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

@@ -0,0 +1,51 @@
+/** ExecuteOptions — per-call overrides for client.complete()/.stream(). */
+import type { ConversationHistory } from '../../agent/history';
+import type { RequestContext } from '../../types/request-context';
+import type { AudioOptions } from './audio';
+import type { CacheConfig, ThinkingConfig } from './request';
+import type { ServiceTier } from './tiers';
+import type { Tool, ToolChoice } from './tools';
+export interface ExecuteOptions {
+    /** Per-call system prompt. Stacked with LLMClient.system + any role:'system'
+     *  messages from the input (in this priority order). When AgentLoop calls
+     *  the client it passes its composed registry-system here so that layered
+     *  prompts (role / context / facts / chat.facts / context-guard.summary)
+     *  flow through to the request without depending on the immutable
+     *  LLMClient.system. */
+    system?: string;
+    /** Conversation reference, propagated into onMessageResolve so listeners
+     *  (ContextGuard, FilesRegistry) can route per-conversation. */
+    history?: ConversationHistory;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stop?: string[];
+    tools?: Tool[];
+    toolChoice?: ToolChoice;
+    structured?: {
+        schema: Record<string, unknown>;
+        name?: string;
+        strict?: boolean;
+    };
+    audio?: AudioOptions;
+    outputModalities?: Array<'text' | 'audio'>;
+    thinking?: ThinkingConfig;
+    cache?: CacheConfig;
+    /** Service tier for this call — 'auto' | 'standard' | 'priority' | 'flex' (or
+     *  any provider-accepted string). Maps per-provider; unsupported → no-op.
+     *  `batch` is the separate Batch API, not a value here. */
+    serviceTier?: ServiceTier;
+    providerOptions?: Record<string, unknown>;
+    previousResponseId?: string;
+    /** Server-state optimization: when the prior assistant turn carries a usable
+     *  server id (same provider, within TTL, model ok), send the id + only the new
+     *  turn instead of the full transcript. Default ON; set false to always resend
+     *  history (fully portable). Ignored if `previousResponseId` is set manually. */
+    stateful?: boolean;
+    signal?: AbortSignal;
+    timeout?: number;
+    cacheKey?: string;
+    cacheName?: string;
+    configName?: string;
+    ctx?: Partial<RequestContext>;
+}

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

@@ -0,0 +1,39 @@
+/** ProviderAdapter — each provider implements this. The LLMClient calls
+ *  buildRequest(NormalizedRequest) → ProviderHttpRequest, sends via the
+ *  injected fetch fn, then parseResponse(raw, latencyMs) → CompletionResponse. */
+import type { SSEEvent } from '../../network/types';
+import type { NormalizedRequest } from './request';
+import type { CompletionResponse } from './response';
+import type { StreamEvent } from './stream';
+export type ProviderName = 'anthropic' | 'openai' | 'google' | 'xai' | 'openrouter';
+export type ApiType = 'completions' | 'responses' | 'messages' | 'interactions' | 'generate';
+export interface ProviderConfig {
+    provider: ProviderName;
+    apiKey: string;
+    baseURL?: string;
+}
+export interface ProviderHttpRequest {
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+    /** Override of the default completion path. Used by providers that route
+     *  per-API or per-modality. */
+    path?: string;
+}
+export interface ProviderAdapter {
+    readonly name: ProviderName;
+    /** Convert universal NormalizedRequest to provider HTTP body. */
+    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. */
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Auth headers (Bearer / x-api-key / etc.). */
+    authHeaders(): Record<string, string>;
+    /** Base URL — provider's domain root. */
+    baseURL(): string;
+    /** Path appended to baseURL for the completion endpoint. */
+    completionPath(): string;
+    /** Optional: mutate provider request to enable streaming (set stream:true,
+     *  switch URL, etc.). */
+    enableStreaming?(providerReq: ProviderHttpRequest, req: NormalizedRequest): void;
+}

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

@@ -0,0 +1,51 @@
+/** Internal normalized request — what LLMClient hands to ProviderAdapter.
+ *
+ *  In v2, the public surface is `client.complete(input, options?)` — model
+ *  and system are fixed at construction. The LLMClient internally builds
+ *  this `NormalizedRequest` from (input, options, this.model, this.system). */
+import type { AudioOptions } from './audio';
+import type { Message } from './messages';
+import type { ServiceTier } from './tiers';
+import type { Tool, ToolChoice } from './tools';
+export interface NormalizedRequest {
+    /** From LLMClientConfig.model — fixed at construction. */
+    model: string;
+    /** Resolved messages array (input normalized + agent history if applicable). */
+    messages: Message[];
+    /** From LLMClientConfig.system or per-call override (rare). */
+    system?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stop?: string[];
+    tools?: Tool[];
+    toolChoice?: ToolChoice;
+    structured?: {
+        schema: Record<string, unknown>;
+        name?: string;
+        strict?: boolean;
+    };
+    thinking?: ThinkingConfig;
+    cache?: CacheConfig;
+    serviceTier?: ServiceTier;
+    providerOptions?: Record<string, unknown>;
+    audio?: AudioOptions;
+    outputModalities?: Array<'text' | 'audio'>;
+    previousResponseId?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+export type ThinkingConfig = {
+    mode: 'auto';
+    effort?: 'low' | 'medium' | 'high' | 'max';
+} | {
+    mode: 'on';
+    effort?: 'low' | 'medium' | 'high' | 'max';
+} | {
+    mode: 'off';
+};
+export type CacheConfig = 'auto' | 'off' | {
+    system?: boolean;
+    tools?: boolean;
+    ttl?: string;
+};