@providerprotocol/ai 0.0.17 → 0.0.18

package/dist/stream-BjyVzBxV.d.ts

@@ -0,0 +1,1286 @@
+/**
+ * @fileoverview Content block types for multimodal messages.
+ *
+ * Defines the various content block types that can be included in
+ * user and assistant messages, supporting text, images, audio, video,
+ * and arbitrary binary data.
+ *
+ * @module types/content
+ */
+/**
+ * Image source variants for ImageBlock.
+ *
+ * Images can be provided as base64-encoded strings, URLs, or raw bytes.
+ *
+ * @example
+ * ```typescript
+ * // Base64 encoded image
+ * const base64Source: ImageSource = {
+ *   type: 'base64',
+ *   data: 'iVBORw0KGgo...'
+ * };
+ *
+ * // URL reference
+ * const urlSource: ImageSource = {
+ *   type: 'url',
+ *   url: 'https://example.com/image.png'
+ * };
+ *
+ * // Raw bytes
+ * const bytesSource: ImageSource = {
+ *   type: 'bytes',
+ *   data: new Uint8Array([...])
+ * };
+ * ```
+ */
+type ImageSource = {
+    type: 'base64';
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'bytes';
+    data: Uint8Array;
+};
+/**
+ * Text content block.
+ *
+ * The most common content block type, containing plain text content.
+ *
+ * @example
+ * ```typescript
+ * const textBlock: TextBlock = {
+ *   type: 'text',
+ *   text: 'Hello, world!'
+ * };
+ * ```
+ */
+interface TextBlock {
+    /** Discriminator for text blocks */
+    type: 'text';
+    /** The text content */
+    text: string;
+}
+/**
+ * Image content block.
+ *
+ * Contains an image with its source data and metadata.
+ *
+ * @example
+ * ```typescript
+ * const imageBlock: ImageBlock = {
+ *   type: 'image',
+ *   source: { type: 'url', url: 'https://example.com/photo.jpg' },
+ *   mimeType: 'image/jpeg',
+ *   width: 1920,
+ *   height: 1080
+ * };
+ * ```
+ */
+interface ImageBlock {
+    /** Discriminator for image blocks */
+    type: 'image';
+    /** The image data source */
+    source: ImageSource;
+    /** MIME type of the image (e.g., 'image/png', 'image/jpeg') */
+    mimeType: string;
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+}
+/**
+ * Audio content block.
+ *
+ * Contains audio data with its metadata.
+ *
+ * @example
+ * ```typescript
+ * const audioBlock: AudioBlock = {
+ *   type: 'audio',
+ *   data: audioBytes,
+ *   mimeType: 'audio/mp3',
+ *   duration: 120.5
+ * };
+ * ```
+ */
+interface AudioBlock {
+    /** Discriminator for audio blocks */
+    type: 'audio';
+    /** Raw audio data */
+    data: Uint8Array;
+    /** MIME type of the audio (e.g., 'audio/mp3', 'audio/wav') */
+    mimeType: string;
+    /** Duration in seconds */
+    duration?: number;
+}
+/**
+ * Video content block.
+ *
+ * Contains video data with its metadata.
+ *
+ * @example
+ * ```typescript
+ * const videoBlock: VideoBlock = {
+ *   type: 'video',
+ *   data: videoBytes,
+ *   mimeType: 'video/mp4',
+ *   duration: 30,
+ *   width: 1920,
+ *   height: 1080
+ * };
+ * ```
+ */
+interface VideoBlock {
+    /** Discriminator for video blocks */
+    type: 'video';
+    /** Raw video data */
+    data: Uint8Array;
+    /** MIME type of the video (e.g., 'video/mp4', 'video/webm') */
+    mimeType: string;
+    /** Duration in seconds */
+    duration?: number;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+}
+/**
+ * Binary content block for arbitrary data.
+ *
+ * A generic block type for data that doesn't fit other categories.
+ *
+ * @example
+ * ```typescript
+ * const binaryBlock: BinaryBlock = {
+ *   type: 'binary',
+ *   data: pdfBytes,
+ *   mimeType: 'application/pdf',
+ *   metadata: { filename: 'document.pdf', pages: 10 }
+ * };
+ * ```
+ */
+interface BinaryBlock {
+    /** Discriminator for binary blocks */
+    type: 'binary';
+    /** Raw binary data */
+    data: Uint8Array;
+    /** MIME type of the data */
+    mimeType: string;
+    /** Additional metadata about the binary content */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Union of all content block types.
+ *
+ * Used when a function or property can accept any type of content block.
+ */
+type ContentBlock = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
+/**
+ * Content types allowed in user messages.
+ *
+ * Users can send any type of content block including binary data.
+ */
+type UserContent = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
+/**
+ * Content types allowed in assistant messages.
+ *
+ * Assistants can generate text and media but not arbitrary binary data.
+ */
+type AssistantContent = TextBlock | ImageBlock | AudioBlock | VideoBlock;
+/**
+ * Creates a text content block from a string.
+ *
+ * @param content - The text content
+ * @returns A TextBlock containing the provided text
+ *
+ * @example
+ * ```typescript
+ * const block = text('Hello, world!');
+ * // { type: 'text', text: 'Hello, world!' }
+ * ```
+ */
+declare function text(content: string): TextBlock;
+/**
+ * Type guard for TextBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a TextBlock
+ *
+ * @example
+ * ```typescript
+ * if (isTextBlock(block)) {
+ *   console.log(block.text);
+ * }
+ * ```
+ */
+declare function isTextBlock(block: ContentBlock): block is TextBlock;
+/**
+ * Type guard for ImageBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is an ImageBlock
+ *
+ * @example
+ * ```typescript
+ * if (isImageBlock(block)) {
+ *   console.log(block.mimeType, block.width, block.height);
+ * }
+ * ```
+ */
+declare function isImageBlock(block: ContentBlock): block is ImageBlock;
+/**
+ * Type guard for AudioBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is an AudioBlock
+ *
+ * @example
+ * ```typescript
+ * if (isAudioBlock(block)) {
+ *   console.log(block.mimeType, block.duration);
+ * }
+ * ```
+ */
+declare function isAudioBlock(block: ContentBlock): block is AudioBlock;
+/**
+ * Type guard for VideoBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a VideoBlock
+ *
+ * @example
+ * ```typescript
+ * if (isVideoBlock(block)) {
+ *   console.log(block.mimeType, block.duration);
+ * }
+ * ```
+ */
+declare function isVideoBlock(block: ContentBlock): block is VideoBlock;
+/**
+ * Type guard for BinaryBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a BinaryBlock
+ *
+ * @example
+ * ```typescript
+ * if (isBinaryBlock(block)) {
+ *   console.log(block.mimeType, block.metadata);
+ * }
+ * ```
+ */
+declare function isBinaryBlock(block: ContentBlock): block is BinaryBlock;
+
+/**
+ * @fileoverview JSON Schema types for tool parameters and structured outputs.
+ *
+ * Provides TypeScript interfaces for defining JSON Schema objects used in
+ * LLM tool definitions and structured output specifications.
+ *
+ * @module types/schema
+ */
+/**
+ * Primitive and composite JSON Schema property types.
+ *
+ * These types correspond to the JSON Schema specification's allowed type values.
+ */
+type JSONSchemaPropertyType = 
+/** String values */
+'string'
+/** Floating point numbers */
+ | 'number'
+/** Whole numbers */
+ | 'integer'
+/** Boolean true/false values */
+ | 'boolean'
+/** Ordered lists of values */
+ | 'array'
+/** Key-value mappings */
+ | 'object'
+/** Explicit null value */
+ | 'null';
+/**
+ * JSON Schema property definition.
+ *
+ * Describes a single property within a JSON Schema object, including
+ * type constraints, validation rules, and nested structure definitions.
+ *
+ * @example
+ * ```typescript
+ * const nameProperty: JSONSchemaProperty = {
+ *   type: 'string',
+ *   description: 'User name',
+ *   minLength: 1,
+ *   maxLength: 100
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const tagsProperty: JSONSchemaProperty = {
+ *   type: 'array',
+ *   description: 'List of tags',
+ *   items: { type: 'string' },
+ *   minItems: 1,
+ *   uniqueItems: true
+ * };
+ * ```
+ */
+interface JSONSchemaProperty {
+    /** The JSON type of this property */
+    type: JSONSchemaPropertyType;
+    /** Human-readable description for the LLM */
+    description?: string;
+    /** Allowed values (enumeration) */
+    enum?: unknown[];
+    /** Constant value this property must equal */
+    const?: unknown;
+    /** Default value if not provided */
+    default?: unknown;
+    /** Minimum string length (string type only) */
+    minLength?: number;
+    /** Maximum string length (string type only) */
+    maxLength?: number;
+    /** Regular expression pattern for validation (string type only) */
+    pattern?: string;
+    /** Semantic format hint (string type only) */
+    format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
+    /** Minimum value inclusive (number/integer types only) */
+    minimum?: number;
+    /** Maximum value inclusive (number/integer types only) */
+    maximum?: number;
+    /** Minimum value exclusive (number/integer types only) */
+    exclusiveMinimum?: number;
+    /** Maximum value exclusive (number/integer types only) */
+    exclusiveMaximum?: number;
+    /** Value must be divisible by this (number/integer types only) */
+    multipleOf?: number;
+    /** Schema for array elements (array type only) */
+    items?: JSONSchemaProperty;
+    /** Minimum array length (array type only) */
+    minItems?: number;
+    /** Maximum array length (array type only) */
+    maxItems?: number;
+    /** Whether array elements must be unique (array type only) */
+    uniqueItems?: boolean;
+    /** Nested property definitions (object type only) */
+    properties?: Record<string, JSONSchemaProperty>;
+    /** List of required property names (object type only) */
+    required?: string[];
+    /** Whether additional properties are allowed (object type only) */
+    additionalProperties?: boolean;
+}
+/**
+ * Root JSON Schema for tool parameters or structured outputs.
+ *
+ * This is the top-level schema definition used when defining tool
+ * parameters or requesting structured output from an LLM.
+ *
+ * @example
+ * ```typescript
+ * const weatherToolSchema: JSONSchema = {
+ *   type: 'object',
+ *   description: 'Parameters for getting weather information',
+ *   properties: {
+ *     location: {
+ *       type: 'string',
+ *       description: 'City name or coordinates'
+ *     },
+ *     units: {
+ *       type: 'string',
+ *       enum: ['celsius', 'fahrenheit'],
+ *       description: 'Temperature units'
+ *     }
+ *   },
+ *   required: ['location']
+ * };
+ * ```
+ */
+interface JSONSchema {
+    /** Root schemas are always objects */
+    type: 'object';
+    /** Property definitions for the object */
+    properties: Record<string, JSONSchemaProperty>;
+    /** List of required property names */
+    required?: string[];
+    /** Whether additional properties are allowed beyond those defined */
+    additionalProperties?: boolean;
+    /** Human-readable description of the schema's purpose */
+    description?: string;
+}
+
+/**
+ * @fileoverview Tool types for LLM function calling.
+ *
+ * Defines the interfaces for registering tools with LLMs, handling
+ * tool calls from the model, and managing tool execution strategies.
+ *
+ * @module types/tool
+ */
+
+/**
+ * Provider-namespaced metadata for tools.
+ *
+ * Each provider can attach its own metadata under its namespace,
+ * enabling provider-specific features like caching, strict mode, etc.
+ *
+ * @example
+ * ```typescript
+ * const metadata: ToolMetadata = {
+ *   anthropic: { cache_control: { type: 'ephemeral' } },
+ *   openrouter: { cache_control: { type: 'ephemeral', ttl: '1h' } }
+ * };
+ * ```
+ */
+interface ToolMetadata {
+    [provider: string]: Record<string, unknown> | undefined;
+}
+/**
+ * Tool call requested by the model.
+ *
+ * Represents a single function call request from the LLM, including
+ * the tool name and parsed arguments.
+ *
+ * @example
+ * ```typescript
+ * const toolCall: ToolCall = {
+ *   toolCallId: 'call_abc123',
+ *   toolName: 'get_weather',
+ *   arguments: { location: 'San Francisco', units: 'celsius' }
+ * };
+ * ```
+ */
+interface ToolCall {
+    /** Unique identifier for this tool call, used to match results */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Parsed arguments for the tool call */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Result of tool execution.
+ *
+ * Returned after executing a tool, containing the result data
+ * and whether an error occurred.
+ *
+ * @example
+ * ```typescript
+ * const result: ToolResult = {
+ *   toolCallId: 'call_abc123',
+ *   result: { temperature: 72, conditions: 'sunny' }
+ * };
+ *
+ * // Error result
+ * const errorResult: ToolResult = {
+ *   toolCallId: 'call_abc123',
+ *   result: 'Location not found',
+ *   isError: true
+ * };
+ * ```
+ */
+interface ToolResult {
+    /** The tool call ID this result corresponds to */
+    toolCallId: string;
+    /** The result data (can be any serializable value) */
+    result: unknown;
+    /** Whether the tool execution resulted in an error */
+    isError?: boolean;
+}
+/**
+ * Tool definition for LLM function calling.
+ *
+ * Defines a tool that can be called by the LLM, including its
+ * name, description, parameter schema, and execution function.
+ *
+ * @typeParam TParams - The type of parameters the tool accepts
+ * @typeParam TResult - The type of result the tool returns
+ *
+ * @example
+ * ```typescript
+ * const weatherTool: Tool<{ location: string }, WeatherData> = {
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a location',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       location: { type: 'string', description: 'City name' }
+ *     },
+ *     required: ['location']
+ *   },
+ *   run: async (params) => {
+ *     return fetchWeather(params.location);
+ *   }
+ * };
+ * ```
+ */
+interface Tool<TParams = unknown, TResult = unknown> {
+    /** Tool name (must be unique within an llm() instance) */
+    name: string;
+    /** Human-readable description for the model to understand when to use this tool */
+    description: string;
+    /** JSON Schema defining the tool's parameters */
+    parameters: JSONSchema;
+    /**
+     * Provider-specific metadata, namespaced by provider name.
+     *
+     * Used for provider-specific features like prompt caching:
+     * @example
+     * ```typescript
+     * const tool: Tool = {
+     *   name: 'search_docs',
+     *   description: 'Search documentation',
+     *   parameters: {...},
+     *   run: async (params) => {...},
+     *   metadata: {
+     *     anthropic: { cache_control: { type: 'ephemeral' } }
+     *   }
+     * };
+     * ```
+     */
+    metadata?: ToolMetadata;
+    /**
+     * Executes the tool with the provided parameters.
+     *
+     * @param params - The parameters passed by the model
+     * @returns The tool result, synchronously or as a Promise
+     */
+    run(params: TParams): TResult | Promise<TResult>;
+    /**
+     * Optional approval handler for sensitive operations.
+     *
+     * If provided, this function is called before the tool executes.
+     * Return false to prevent execution.
+     *
+     * @param params - The parameters the tool would be called with
+     * @returns Whether to approve the execution
+     */
+    approval?(params: TParams): boolean | Promise<boolean>;
+}
+/**
+ * Result from onBeforeCall hook indicating whether to proceed and optionally transformed params.
+ */
+interface BeforeCallResult {
+    /** Whether to proceed with tool execution */
+    proceed: boolean;
+    /** Transformed parameters to use instead of the original (optional) */
+    params?: unknown;
+}
+/**
+ * Result from onAfterCall hook optionally containing a transformed result.
+ */
+interface AfterCallResult {
+    /** Transformed result to use instead of the original */
+    result: unknown;
+}
+/**
+ * Strategy for controlling tool execution behavior.
+ *
+ * Provides hooks for monitoring, controlling, and transforming the tool execution
+ * loop during LLM inference.
+ *
+ * @example
+ * ```typescript
+ * const strategy: ToolUseStrategy = {
+ *   maxIterations: 5,
+ *   onToolCall: (tool, params) => {
+ *     console.log(`Calling ${tool.name} with`, params);
+ *   },
+ *   // Transform input parameters
+ *   onBeforeCall: (tool, params) => {
+ *     if (tool.name === 'search') {
+ *       return { proceed: true, params: { ...params, limit: 10 } };
+ *     }
+ *     return true;
+ *   },
+ *   // Transform output results
+ *   onAfterCall: (tool, params, result) => {
+ *     if (tool.name === 'fetch_data') {
+ *       return { result: sanitize(result) };
+ *     }
+ *   },
+ *   onMaxIterations: (iterations) => {
+ *     console.warn(`Reached max iterations: ${iterations}`);
+ *   }
+ * };
+ * ```
+ */
+interface ToolUseStrategy {
+    /** Maximum number of tool execution rounds (default: 10) */
+    maxIterations?: number;
+    /**
+     * Called when the model requests a tool call.
+     *
+     * @param tool - The tool being called
+     * @param params - The parameters for the call
+     */
+    onToolCall?(tool: Tool, params: unknown): void | Promise<void>;
+    /**
+     * Called before tool execution. Can skip execution or transform parameters.
+     *
+     * @param tool - The tool about to be executed
+     * @param params - The parameters for the call
+     * @returns One of:
+     *   - `false` to skip execution
+     *   - `true` to proceed with original params
+     *   - `BeforeCallResult` object to control execution and optionally transform params
+     */
+    onBeforeCall?(tool: Tool, params: unknown): boolean | BeforeCallResult | Promise<boolean | BeforeCallResult>;
+    /**
+     * Called after tool execution completes. Can transform the result.
+     *
+     * @param tool - The tool that was executed
+     * @param params - The parameters that were used
+     * @param result - The result from the tool
+     * @returns Void to use original result, or `AfterCallResult` to transform it
+     */
+    onAfterCall?(tool: Tool, params: unknown, result: unknown): void | AfterCallResult | Promise<void | AfterCallResult>;
+    /**
+     * Called when a tool execution throws an error.
+     *
+     * @param tool - The tool that failed
+     * @param params - The parameters that were used
+     * @param error - The error that was thrown
+     */
+    onError?(tool: Tool, params: unknown, error: Error): void | Promise<void>;
+    /**
+     * Called when the maximum iteration limit is reached.
+     *
+     * @param iterations - The number of iterations that were performed
+     */
+    onMaxIterations?(iterations: number): void | Promise<void>;
+}
+/**
+ * Record of a completed tool execution.
+ *
+ * Contains all information about a tool call that was executed,
+ * including timing and result data.
+ *
+ * @example
+ * ```typescript
+ * const execution: ToolExecution = {
+ *   toolName: 'get_weather',
+ *   toolCallId: 'call_abc123',
+ *   arguments: { location: 'San Francisco' },
+ *   result: { temperature: 72 },
+ *   isError: false,
+ *   duration: 150,
+ *   approved: true
+ * };
+ * ```
+ */
+interface ToolExecution {
+    /** Name of the tool that was called */
+    toolName: string;
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Arguments that were passed to the tool */
+    arguments: Record<string, unknown>;
+    /** Result returned by the tool */
+    result: unknown;
+    /** Whether the tool execution resulted in an error */
+    isError: boolean;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Whether approval was required and granted (undefined if no approval handler) */
+    approved?: boolean;
+}
+
+/**
+ * @fileoverview Message types for conversation history.
+ *
+ * Defines the message classes used to represent conversation turns
+ * between users and assistants, including support for multimodal
+ * content and tool calls.
+ *
+ * @module types/messages
+ */
+
+/**
+ * Message serialized to JSON format.
+ * Picks common fields from Message, converts timestamp to string.
+ */
+type MessageJSON = Pick<Message, 'id' | 'type' | 'metadata'> & {
+    timestamp: string;
+    content: ContentBlock[];
+    toolCalls?: ToolCall[];
+    results?: ToolResult[];
+};
+/**
+ * Message type discriminator.
+ *
+ * Used to distinguish between different message types in a conversation.
+ */
+type MessageType = 'user' | 'assistant' | 'tool_result';
+/**
+ * Provider-namespaced metadata for messages.
+ *
+ * Each provider can attach its own metadata under its namespace,
+ * preventing conflicts between different providers.
+ *
+ * @example
+ * ```typescript
+ * const metadata: MessageMetadata = {
+ *   openai: { model: 'gpt-4', finishReason: 'stop' },
+ *   anthropic: { model: 'claude-3', stopReason: 'end_turn' }
+ * };
+ * ```
+ */
+interface MessageMetadata {
+    [provider: string]: Record<string, unknown> | undefined;
+}
+/**
+ * Options for constructing messages.
+ */
+interface MessageOptions {
+    /** Custom message ID (auto-generated if not provided) */
+    id?: string;
+    /** Provider-specific metadata */
+    metadata?: MessageMetadata;
+}
+/**
+ * Abstract base class for all message types.
+ *
+ * Provides common functionality for user, assistant, and tool result
+ * messages, including content accessors and metadata handling.
+ *
+ * @example
+ * ```typescript
+ * // Access text content from any message
+ * const text = message.text;
+ *
+ * // Access images
+ * const images = message.images;
+ * ```
+ */
+declare abstract class Message {
+    /** Unique message identifier */
+    readonly id: string;
+    /** Timestamp when the message was created */
+    readonly timestamp: Date;
+    /** Provider-specific metadata, namespaced by provider name */
+    readonly metadata?: MessageMetadata;
+    /** Message type discriminator (implemented by subclasses) */
+    abstract readonly type: MessageType;
+    /**
+     * Returns the content blocks for this message.
+     * Implemented by subclasses to provide type-specific content.
+     */
+    protected abstract getContent(): ContentBlock[];
+    /**
+     * Creates a new message instance.
+     *
+     * @param options - Optional message ID and metadata
+     */
+    constructor(options?: MessageOptions);
+    /**
+     * Concatenated text content from all text blocks.
+     * Blocks are joined with double newlines.
+     */
+    get text(): string;
+    /**
+     * All image content blocks in this message.
+     */
+    get images(): ImageBlock[];
+    /**
+     * All audio content blocks in this message.
+     */
+    get audio(): AudioBlock[];
+    /**
+     * All video content blocks in this message.
+     */
+    get video(): VideoBlock[];
+}
+/**
+ * User input message.
+ *
+ * Represents a message from the user, which can contain text and/or
+ * multimodal content like images, audio, or video.
+ *
+ * @example
+ * ```typescript
+ * // Simple text message
+ * const msg = new UserMessage('Hello, world!');
+ *
+ * // Multimodal message
+ * const msg = new UserMessage([
+ *   { type: 'text', text: 'What is in this image?' },
+ *   { type: 'image', source: { type: 'url', url: '...' }, mimeType: 'image/png' }
+ * ]);
+ * ```
+ */
+declare class UserMessage extends Message {
+    /** Message type discriminator */
+    readonly type: "user";
+    /** Content blocks in this message */
+    readonly content: UserContent[];
+    /**
+     * Creates a new user message.
+     *
+     * @param content - String (converted to TextBlock) or array of content blocks
+     * @param options - Optional message ID and metadata
+     */
+    constructor(content: string | UserContent[], options?: MessageOptions);
+    protected getContent(): ContentBlock[];
+}
+/**
+ * Assistant response message.
+ *
+ * Represents a response from the AI assistant, which may contain
+ * text, media content, and/or tool call requests.
+ *
+ * @example
+ * ```typescript
+ * // Simple text response
+ * const msg = new AssistantMessage('Hello! How can I help?');
+ *
+ * // Response with tool calls
+ * const msg = new AssistantMessage(
+ *   'Let me check the weather...',
+ *   [{ toolCallId: 'call_1', toolName: 'get_weather', arguments: { location: 'NYC' } }]
+ * );
+ * ```
+ */
+declare class AssistantMessage extends Message {
+    /** Message type discriminator */
+    readonly type: "assistant";
+    /** Content blocks in this message */
+    readonly content: AssistantContent[];
+    /** Tool calls requested by the model (if any) */
+    readonly toolCalls?: ToolCall[];
+    /**
+     * Creates a new assistant message.
+     *
+     * @param content - String (converted to TextBlock) or array of content blocks
+     * @param toolCalls - Tool calls requested by the model
+     * @param options - Optional message ID and metadata
+     */
+    constructor(content: string | AssistantContent[], toolCalls?: ToolCall[], options?: MessageOptions);
+    protected getContent(): ContentBlock[];
+    /**
+     * Whether this message contains tool call requests.
+     */
+    get hasToolCalls(): boolean;
+}
+/**
+ * Tool execution result message.
+ *
+ * Contains the results of executing one or more tool calls,
+ * sent back to the model for further processing.
+ *
+ * @example
+ * ```typescript
+ * const msg = new ToolResultMessage([
+ *   { toolCallId: 'call_1', result: { temperature: 72, conditions: 'sunny' } },
+ *   { toolCallId: 'call_2', result: 'File not found', isError: true }
+ * ]);
+ * ```
+ */
+declare class ToolResultMessage extends Message {
+    /** Message type discriminator */
+    readonly type: "tool_result";
+    /** Results from tool executions */
+    readonly results: ToolResult[];
+    /**
+     * Creates a new tool result message.
+     *
+     * @param results - Array of tool execution results
+     * @param options - Optional message ID and metadata
+     */
+    constructor(results: ToolResult[], options?: MessageOptions);
+    protected getContent(): ContentBlock[];
+}
+/**
+ * Type guard for UserMessage.
+ *
+ * @param msg - The message to check
+ * @returns True if the message is a UserMessage
+ *
+ * @example
+ * ```typescript
+ * if (isUserMessage(msg)) {
+ *   console.log('User said:', msg.text);
+ * }
+ * ```
+ */
+declare function isUserMessage(msg: Message): msg is UserMessage;
+/**
+ * Type guard for AssistantMessage.
+ *
+ * @param msg - The message to check
+ * @returns True if the message is an AssistantMessage
+ *
+ * @example
+ * ```typescript
+ * if (isAssistantMessage(msg)) {
+ *   console.log('Assistant said:', msg.text);
+ *   if (msg.hasToolCalls) {
+ *     console.log('Tool calls:', msg.toolCalls);
+ *   }
+ * }
+ * ```
+ */
+declare function isAssistantMessage(msg: Message): msg is AssistantMessage;
+/**
+ * Type guard for ToolResultMessage.
+ *
+ * @param msg - The message to check
+ * @returns True if the message is a ToolResultMessage
+ *
+ * @example
+ * ```typescript
+ * if (isToolResultMessage(msg)) {
+ *   for (const result of msg.results) {
+ *     console.log(`Tool ${result.toolCallId}:`, result.result);
+ *   }
+ * }
+ * ```
+ */
+declare function isToolResultMessage(msg: Message): msg is ToolResultMessage;
+
+/**
+ * @fileoverview Turn types for inference results.
+ *
+ * A Turn represents the complete result of one inference call, including
+ * all messages produced during tool execution loops, token usage, and
+ * optional structured output data.
+ *
+ * @module types/turn
+ */
+
+/**
+ * Token usage information for an inference request.
+ *
+ * Tracks input and output tokens across all inference cycles,
+ * with optional per-cycle breakdown and cache metrics.
+ *
+ * @example
+ * ```typescript
+ * const usage: TokenUsage = {
+ *   inputTokens: 150,
+ *   outputTokens: 50,
+ *   totalTokens: 200,
+ *   cacheReadTokens: 100,
+ *   cacheWriteTokens: 50,
+ *   cycles: [
+ *     { inputTokens: 100, outputTokens: 30, cacheReadTokens: 0, cacheWriteTokens: 50 },
+ *     { inputTokens: 50, outputTokens: 20, cacheReadTokens: 100, cacheWriteTokens: 0 }
+ *   ]
+ * };
+ * ```
+ */
+interface TokenUsage {
+    /** Total input tokens across all cycles */
+    inputTokens: number;
+    /** Total output tokens across all cycles */
+    outputTokens: number;
+    /** Sum of input and output tokens */
+    totalTokens: number;
+    /**
+     * Tokens read from cache (cache hits).
+     * Returns 0 for providers that don't support or report cache metrics.
+     */
+    cacheReadTokens: number;
+    /**
+     * Tokens written to cache (cache misses that were cached).
+     * Only Anthropic reports this metric; returns 0 for other providers.
+     */
+    cacheWriteTokens: number;
+    /** Per-cycle token breakdown (if multiple cycles occurred) */
+    cycles?: Array<{
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    }>;
+}
+/**
+ * A Turn represents the complete result of one inference call.
+ *
+ * Includes all messages produced during tool execution loops,
+ * the final assistant response, token usage, and optional
+ * structured output data.
+ *
+ * @typeParam TData - Type of the structured output data
+ *
+ * @example
+ * ```typescript
+ * const turn = await instance.generate('Hello');
+ * console.log(turn.response.text);
+ * console.log(`Used ${turn.usage.totalTokens} tokens in ${turn.cycles} cycles`);
+ *
+ * // With structured output
+ * interface WeatherData { temperature: number; conditions: string; }
+ * const turn = await instance.generate<WeatherData>('Get weather');
+ * console.log(turn.data?.temperature);
+ * ```
+ */
+interface Turn<TData = unknown> {
+    /**
+     * All messages produced during this inference, in chronological order.
+     * Includes UserMessage, AssistantMessage (may include toolCalls), and ToolResultMessage.
+     */
+    readonly messages: Message[];
+    /** The final assistant response (last AssistantMessage in the turn) */
+    readonly response: AssistantMessage;
+    /** Tool executions that occurred during this turn */
+    readonly toolExecutions: ToolExecution[];
+    /** Aggregate token usage for the entire turn */
+    readonly usage: TokenUsage;
+    /** Total number of inference cycles (1 + number of tool rounds) */
+    readonly cycles: number;
+    /**
+     * Structured output data (if a structure schema was provided).
+     * Type is inferred from the schema when using TypeScript.
+     */
+    readonly data?: TData;
+}
+/**
+ * Turn serialized to JSON format.
+ * Messages are converted to MessageJSON, response is omitted (computed from messages).
+ */
+type TurnJSON = Omit<Turn, 'messages' | 'response'> & {
+    messages: MessageJSON[];
+};
+/**
+ * Creates a Turn from accumulated inference data.
+ *
+ * @typeParam TData - Type of the structured output data
+ * @param messages - All messages produced during the inference
+ * @param toolExecutions - Record of all tool executions
+ * @param usage - Aggregate token usage
+ * @param cycles - Number of inference cycles
+ * @param data - Optional structured output data
+ * @returns A complete Turn object
+ * @throws Error if no assistant message is found in the messages
+ *
+ * @example
+ * ```typescript
+ * const turn = createTurn(
+ *   [userMsg, assistantMsg],
+ *   [],
+ *   { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+ *   1
+ * );
+ * ```
+ */
+declare function createTurn<TData = unknown>(messages: Message[], toolExecutions: ToolExecution[], usage: TokenUsage, cycles: number, data?: TData): Turn<TData>;
+/**
+ * Creates an empty TokenUsage object.
+ *
+ * @returns A TokenUsage with all values set to zero
+ *
+ * @example
+ * ```typescript
+ * const usage = emptyUsage();
+ * // { inputTokens: 0, outputTokens: 0, totalTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, cycles: [] }
+ * ```
+ */
+declare function emptyUsage(): TokenUsage;
+/**
+ * Aggregates token usage from multiple inference cycles.
+ *
+ * @param usages - Array of TokenUsage objects to aggregate
+ * @returns Combined TokenUsage with per-cycle breakdown
+ *
+ * @example
+ * ```typescript
+ * const cycle1 = { inputTokens: 100, outputTokens: 30, totalTokens: 130, cacheReadTokens: 50, cacheWriteTokens: 0 };
+ * const cycle2 = { inputTokens: 150, outputTokens: 40, totalTokens: 190, cacheReadTokens: 100, cacheWriteTokens: 0 };
+ * const total = aggregateUsage([cycle1, cycle2]);
+ * // { inputTokens: 250, outputTokens: 70, totalTokens: 320, cacheReadTokens: 150, cacheWriteTokens: 0, cycles: [...] }
+ * ```
+ */
+declare function aggregateUsage(usages: TokenUsage[]): TokenUsage;
+
+/**
+ * @fileoverview Streaming types for real-time LLM responses.
+ *
+ * Defines the event types and interfaces for streaming LLM inference,
+ * including text deltas, tool call deltas, and control events.
+ *
+ * @module types/stream
+ */
+
+/**
+ * Stream event type discriminators.
+ *
+ * Each event type represents a different kind of streaming update
+ * from the LLM provider.
+ */
+type StreamEventType = 
+/** Incremental text output */
+'text_delta'
+/** Incremental reasoning/thinking output */
+ | 'reasoning_delta'
+/** Incremental image data */
+ | 'image_delta'
+/** Incremental audio data */
+ | 'audio_delta'
+/** Incremental video data */
+ | 'video_delta'
+/** Incremental tool call data (arguments being streamed) */
+ | 'tool_call_delta'
+/** Tool execution has started */
+ | 'tool_execution_start'
+/** Tool execution has completed */
+ | 'tool_execution_end'
+/** Beginning of a message */
+ | 'message_start'
+/** End of a message */
+ | 'message_stop'
+/** Beginning of a content block */
+ | 'content_block_start'
+/** End of a content block */
+ | 'content_block_stop';
+/**
+ * Event delta data payload.
+ *
+ * Contains the type-specific data for a streaming event.
+ * Different fields are populated depending on the event type.
+ */
+interface EventDelta {
+    /** Incremental text content (for text_delta, reasoning_delta) */
+    text?: string;
+    /** Incremental binary data (for image_delta, audio_delta, video_delta) */
+    data?: Uint8Array;
+    /** Tool call identifier (for tool_call_delta, tool_execution_start/end) */
+    toolCallId?: string;
+    /** Tool name (for tool_call_delta, tool_execution_start/end) */
+    toolName?: string;
+    /** Incremental JSON arguments string (for tool_call_delta) */
+    argumentsJson?: string;
+    /** Tool execution result (for tool_execution_end) */
+    result?: unknown;
+    /** Whether tool execution resulted in an error (for tool_execution_end) */
+    isError?: boolean;
+    /** Timestamp in milliseconds (for tool_execution_start/end) */
+    timestamp?: number;
+}
+/**
+ * A single streaming event from the LLM.
+ *
+ * Events are emitted in order as the model generates output,
+ * allowing for real-time display of responses.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of stream) {
+ *   if (event.type === 'text_delta') {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   } else if (event.type === 'tool_call_delta') {
+ *     console.log('Tool:', event.delta.toolName);
+ *   }
+ * }
+ * ```
+ */
+interface StreamEvent {
+    /** Event type discriminator */
+    type: StreamEventType;
+    /** Index of the content block this event belongs to */
+    index: number;
+    /** Event-specific data payload */
+    delta: EventDelta;
+}
+/**
+ * Stream result - an async iterable that also provides the final turn.
+ *
+ * Allows consuming streaming events while also awaiting the complete
+ * Turn result after streaming finishes.
+ *
+ * @typeParam TData - Type of the structured output data
+ *
+ * @example
+ * ```typescript
+ * const stream = instance.stream('Tell me a story');
+ *
+ * // Consume streaming events
+ * for await (const event of stream) {
+ *   if (event.type === 'text_delta') {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   }
+ * }
+ *
+ * // Get the complete turn after streaming
+ * const turn = await stream.turn;
+ * console.log('\n\nTokens used:', turn.usage.totalTokens);
+ * ```
+ */
+interface StreamResult<TData = unknown> extends AsyncIterable<StreamEvent> {
+    /**
+     * Promise that resolves to the complete Turn after streaming finishes.
+     */
+    readonly turn: Promise<Turn<TData>>;
+    /**
+     * Aborts the stream, stopping further events and cancelling the request.
+     */
+    abort(): void;
+}
+/**
+ * Creates a StreamResult from an async generator and completion promise.
+ *
+ * @typeParam TData - Type of the structured output data
+ * @param generator - Async generator that yields stream events
+ * @param turnPromise - Promise that resolves to the complete Turn
+ * @param abortController - Controller for aborting the stream
+ * @returns A StreamResult that can be iterated and awaited
+ *
+ * @example
+ * ```typescript
+ * const abortController = new AbortController();
+ * const stream = createStreamResult(
+ *   eventGenerator(),
+ *   turnPromise,
+ *   abortController
+ * );
+ * ```
+ */
+declare function createStreamResult<TData = unknown>(generator: AsyncGenerator<StreamEvent, void, unknown>, turnPromise: Promise<Turn<TData>>, abortController: AbortController): StreamResult<TData>;
+/**
+ * Creates a text delta stream event.
+ *
+ * @param text - The incremental text content
+ * @param index - Content block index (default: 0)
+ * @returns A text_delta StreamEvent
+ */
+declare function textDelta(text: string, index?: number): StreamEvent;
+/**
+ * Creates a tool call delta stream event.
+ *
+ * @param toolCallId - Unique identifier for the tool call
+ * @param toolName - Name of the tool being called
+ * @param argumentsJson - Incremental JSON arguments string
+ * @param index - Content block index (default: 0)
+ * @returns A tool_call_delta StreamEvent
+ */
+declare function toolCallDelta(toolCallId: string, toolName: string, argumentsJson: string, index?: number): StreamEvent;
+/**
+ * Creates a message start stream event.
+ *
+ * @returns A message_start StreamEvent
+ */
+declare function messageStart(): StreamEvent;
+/**
+ * Creates a message stop stream event.
+ *
+ * @returns A message_stop StreamEvent
+ */
+declare function messageStop(): StreamEvent;
+/**
+ * Creates a content block start stream event.
+ *
+ * @param index - The content block index starting
+ * @returns A content_block_start StreamEvent
+ */
+declare function contentBlockStart(index: number): StreamEvent;
+/**
+ * Creates a content block stop stream event.
+ *
+ * @param index - The content block index stopping
+ * @returns A content_block_stop StreamEvent
+ */
+declare function contentBlockStop(index: number): StreamEvent;
+
+export { type TurnJSON as $, type AssistantContent as A, type BinaryBlock as B, type ContentBlock as C, isUserMessage as D, isAssistantMessage as E, isToolResultMessage as F, type MessageMetadata as G, type MessageOptions as H, type ImageSource as I, type JSONSchema as J, createTurn as K, emptyUsage as L, Message as M, aggregateUsage as N, type StreamEventType as O, type EventDelta as P, createStreamResult as Q, textDelta as R, type StreamResult as S, type Turn as T, type UserContent as U, type VideoBlock as V, toolCallDelta as W, messageStart as X, messageStop as Y, contentBlockStart as Z, contentBlockStop as _, type MessageType as a, type MessageJSON as b, type Tool as c, type ToolUseStrategy as d, AssistantMessage as e, type TokenUsage as f, type StreamEvent as g, type ImageBlock as h, type JSONSchemaProperty as i, type JSONSchemaPropertyType as j, type TextBlock as k, type AudioBlock as l, isTextBlock as m, isImageBlock as n, isAudioBlock as o, isVideoBlock as p, isBinaryBlock as q, type ToolCall as r, type ToolResult as s, text as t, type ToolMetadata as u, type BeforeCallResult as v, type AfterCallResult as w, type ToolExecution as x, UserMessage as y, ToolResultMessage as z };