@providerprotocol/ai 0.0.27 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerprotocol/ai",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "description": "UPP: Unified Provider Protocol for AI inference",
   "license": "MIT",
   "homepage": "https://providerprotocol.org",

package/dist/chunk-6AZVUI6H.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/utils/id.ts","../src/types/messages.ts","../src/core/provider-handlers.ts","../src/core/provider.ts"],"sourcesContent":["/**\n * @fileoverview ID generation utilities for the Universal Provider Protocol.\n *\n * Provides functions for generating unique identifiers used throughout UPP,\n * including message IDs, tool call IDs, and other internal references.\n *\n * @module utils/id\n */\n\n/**\n * Generates a unique UUID v4 identifier.\n *\n * Uses the native `crypto.randomUUID()` when available for cryptographically\n * secure randomness. Falls back to a Math.random-based implementation for\n * environments without Web Crypto API support.\n *\n * @returns A UUID v4 string in the format `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`\n *\n * @example\n * ```typescript\n * const messageId = generateId();\n * // => \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\n * ```\n */\nexport function generateId(): string {\n  if (typeof crypto !== 'undefined' && crypto.randomUUID) {\n    return crypto.randomUUID();\n  }\n\n  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {\n    const r = (Math.random() * 16) | 0;\n    const v = c === 'x' ? r : (r & 0x3) | 0x8;\n    return v.toString(16);\n  });\n}\n\n/**\n * Generates a short alphanumeric identifier.\n *\n * Creates a 12-character random string using alphanumeric characters (a-z, A-Z, 0-9).\n * Useful for tool call IDs and other cases where a full UUID is not required.\n *\n * @param prefix - Optional prefix to prepend to the generated ID\n * @returns A string containing the prefix followed by 12 random alphanumeric characters\n *\n * @example\n * ```typescript\n * const toolCallId = generateShortId('call_');\n * // => \"call_aB3xY9mK2pQr\"\n *\n * const simpleId = generateShortId();\n * // => \"Tz4wN8vL1sHj\"\n * ```\n */\nexport function generateShortId(prefix = ''): string {\n  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';\n  let result = prefix;\n  for (let i = 0; i < 12; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\n  }\n  return result;\n}\n","/**\n * @fileoverview Message types for conversation history.\n *\n * Defines the message classes used to represent conversation turns\n * between users and assistants, including support for multimodal\n * content and tool calls.\n *\n * @module types/messages\n */\n\nimport { generateId } from '../utils/id.ts';\nimport type {\n  ContentBlock,\n  TextBlock,\n  ReasoningBlock,\n  ImageBlock,\n  AudioBlock,\n  VideoBlock,\n  UserContent,\n  AssistantContent,\n} from './content.ts';\nimport type { ToolCall, ToolResult } from './tool.ts';\n\n/**\n * Message serialized to JSON format.\n * Picks common fields from Message, converts timestamp to string.\n */\nexport type MessageJSON = Pick<Message, 'id' | 'type' | 'metadata'> & {\n  timestamp: string;\n  content: ContentBlock[];\n  toolCalls?: ToolCall[];\n  results?: ToolResult[];\n};\n\n/**\n * Message role/type constants.\n *\n * Use these constants instead of raw strings for type-safe message handling:\n *\n * @example\n * ```typescript\n * import { MessageRole, isUserMessage } from 'upp';\n *\n * if (message.type === MessageRole.User) {\n *   console.log('User said:', message.text);\n * } else if (message.type === MessageRole.Assistant) {\n *   console.log('Assistant replied:', message.text);\n * }\n * ```\n */\nexport const MessageRole = {\n  /** User message */\n  User: 'user',\n  /** Assistant/model response */\n  Assistant: 'assistant',\n  /** Tool execution result */\n  ToolResult: 'tool_result',\n} as const;\n\n/**\n * Message type discriminator union.\n *\n * This type is derived from {@link MessageRole} constants. The name `MessageType`\n * is kept for backward compatibility; `MessageRole` works as both the const\n * object and this type.\n */\nexport type MessageType = (typeof MessageRole)[keyof typeof MessageRole];\n\n/**\n * Type alias for MessageType, allowing `MessageRole` to work as both const and type.\n */\nexport type MessageRole = MessageType;\n\n/**\n * Provider-namespaced metadata for messages.\n *\n * Each provider can attach its own metadata under its namespace,\n * preventing conflicts between different providers.\n *\n * @example\n * ```typescript\n * const metadata: MessageMetadata = {\n *   openai: { model: 'gpt-4', finishReason: 'stop' },\n *   anthropic: { model: 'claude-3', stopReason: 'end_turn' }\n * };\n * ```\n */\nexport interface MessageMetadata {\n  [provider: string]: Record<string, unknown> | undefined;\n}\n\n/**\n * Options for constructing messages.\n */\nexport interface MessageOptions {\n  /** Custom message ID (auto-generated if not provided) */\n  id?: string;\n\n  /** Provider-specific metadata */\n  metadata?: MessageMetadata;\n}\n\n/**\n * Abstract base class for all message types.\n *\n * Provides common functionality for user, assistant, and tool result\n * messages, including content accessors and metadata handling.\n *\n * @example\n * ```typescript\n * // Access text content from any message\n * const text = message.text;\n *\n * // Access images\n * const images = message.images;\n * ```\n */\nexport abstract class Message {\n  /** Unique message identifier */\n  readonly id: string;\n\n  /** Timestamp when the message was created */\n  readonly timestamp: Date;\n\n  /** Provider-specific metadata, namespaced by provider name */\n  readonly metadata?: MessageMetadata;\n\n  /** Message type discriminator (implemented by subclasses) */\n  abstract readonly type: MessageType;\n\n  /**\n   * Returns the content blocks for this message.\n   * Implemented by subclasses to provide type-specific content.\n   */\n  protected abstract getContent(): ContentBlock[];\n\n  /**\n   * Creates a new message instance.\n   *\n   * @param options - Optional message ID and metadata\n   */\n  constructor(options?: MessageOptions) {\n    this.id = options?.id ?? generateId();\n    this.timestamp = new Date();\n    this.metadata = options?.metadata;\n  }\n\n  /**\n   * Concatenated text content from all text blocks.\n   * Blocks are joined with double newlines.\n   */\n  get text(): string {\n    return this.getContent()\n      .filter((block): block is TextBlock => block.type === 'text')\n      .map((block) => block.text)\n      .join('\\n\\n');\n  }\n\n  /**\n   * All image content blocks in this message.\n   */\n  get images(): ImageBlock[] {\n    return this.getContent().filter((block): block is ImageBlock => block.type === 'image');\n  }\n\n  /**\n   * All audio content blocks in this message.\n   */\n  get audio(): AudioBlock[] {\n    return this.getContent().filter((block): block is AudioBlock => block.type === 'audio');\n  }\n\n  /**\n   * All video content blocks in this message.\n   */\n  get video(): VideoBlock[] {\n    return this.getContent().filter((block): block is VideoBlock => block.type === 'video');\n  }\n\n  /**\n   * All reasoning/thinking content blocks in this message.\n   * Available when using extended thinking models.\n   */\n  get reasoning(): ReasoningBlock[] {\n    return this.getContent().filter((block): block is ReasoningBlock => block.type === 'reasoning');\n  }\n}\n\n/**\n * User input message.\n *\n * Represents a message from the user, which can contain text and/or\n * multimodal content like images, audio, or video.\n *\n * @example\n * ```typescript\n * // Simple text message\n * const msg = new UserMessage('Hello, world!');\n *\n * // Multimodal message\n * const msg = new UserMessage([\n *   { type: 'text', text: 'What is in this image?' },\n *   { type: 'image', source: { type: 'url', url: '...' }, mimeType: 'image/png' }\n * ]);\n * ```\n */\nexport class UserMessage extends Message {\n  /** Message type discriminator */\n  readonly type = 'user' as const;\n\n  /** Content blocks in this message */\n  readonly content: UserContent[];\n\n  /**\n   * Creates a new user message.\n   *\n   * @param content - String (converted to TextBlock) or array of content blocks\n   * @param options - Optional message ID and metadata\n   */\n  constructor(content: string | UserContent[], options?: MessageOptions) {\n    super(options);\n    if (typeof content === 'string') {\n      this.content = [{ type: 'text', text: content }];\n    } else {\n      this.content = content;\n    }\n  }\n\n  protected getContent(): ContentBlock[] {\n    return this.content;\n  }\n}\n\n/**\n * Assistant response message.\n *\n * Represents a response from the AI assistant, which may contain\n * text, media content, and/or tool call requests.\n *\n * @example\n * ```typescript\n * // Simple text response\n * const msg = new AssistantMessage('Hello! How can I help?');\n *\n * // Response with tool calls\n * const msg = new AssistantMessage(\n *   'Let me check the weather...',\n *   [{ toolCallId: 'call_1', toolName: 'get_weather', arguments: { location: 'NYC' } }]\n * );\n * ```\n */\nexport class AssistantMessage extends Message {\n  /** Message type discriminator */\n  readonly type = 'assistant' as const;\n\n  /** Content blocks in this message */\n  readonly content: AssistantContent[];\n\n  /** Tool calls requested by the model (if any) */\n  readonly toolCalls?: ToolCall[];\n\n  /**\n   * Creates a new assistant message.\n   *\n   * @param content - String (converted to TextBlock) or array of content blocks\n   * @param toolCalls - Tool calls requested by the model\n   * @param options - Optional message ID and metadata\n   */\n  constructor(\n    content: string | AssistantContent[],\n    toolCalls?: ToolCall[],\n    options?: MessageOptions\n  ) {\n    super(options);\n    if (typeof content === 'string') {\n      this.content = [{ type: 'text', text: content }];\n    } else {\n      this.content = content;\n    }\n    this.toolCalls = toolCalls;\n  }\n\n  protected getContent(): ContentBlock[] {\n    return this.content;\n  }\n\n  /**\n   * Whether this message contains tool call requests.\n   */\n  get hasToolCalls(): boolean {\n    return this.toolCalls !== undefined && this.toolCalls.length > 0;\n  }\n}\n\n/**\n * Tool execution result message.\n *\n * Contains the results of executing one or more tool calls,\n * sent back to the model for further processing.\n *\n * @example\n * ```typescript\n * const msg = new ToolResultMessage([\n *   { toolCallId: 'call_1', result: { temperature: 72, conditions: 'sunny' } },\n *   { toolCallId: 'call_2', result: 'File not found', isError: true }\n * ]);\n * ```\n */\nexport class ToolResultMessage extends Message {\n  /** Message type discriminator */\n  readonly type = 'tool_result' as const;\n\n  /** Results from tool executions */\n  readonly results: ToolResult[];\n\n  /**\n   * Creates a new tool result message.\n   *\n   * @param results - Array of tool execution results\n   * @param options - Optional message ID and metadata\n   */\n  constructor(results: ToolResult[], options?: MessageOptions) {\n    super(options);\n    this.results = results;\n  }\n\n  protected getContent(): ContentBlock[] {\n    return this.results.map((result) => ({\n      type: 'text' as const,\n      text:\n        typeof result.result === 'string'\n          ? result.result\n          : JSON.stringify(result.result),\n    }));\n  }\n}\n\n/**\n * Type guard for UserMessage.\n *\n * @param msg - The message to check\n * @returns True if the message is a UserMessage\n *\n * @example\n * ```typescript\n * if (isUserMessage(msg)) {\n *   console.log('User said:', msg.text);\n * }\n * ```\n */\nexport function isUserMessage(msg: Message): msg is UserMessage {\n  return msg.type === MessageRole.User;\n}\n\n/**\n * Type guard for AssistantMessage.\n *\n * @param msg - The message to check\n * @returns True if the message is an AssistantMessage\n *\n * @example\n * ```typescript\n * if (isAssistantMessage(msg)) {\n *   console.log('Assistant said:', msg.text);\n *   if (msg.hasToolCalls) {\n *     console.log('Tool calls:', msg.toolCalls);\n *   }\n * }\n * ```\n */\nexport function isAssistantMessage(msg: Message): msg is AssistantMessage {\n  return msg.type === MessageRole.Assistant;\n}\n\n/**\n * Type guard for ToolResultMessage.\n *\n * @param msg - The message to check\n * @returns True if the message is a ToolResultMessage\n *\n * @example\n * ```typescript\n * if (isToolResultMessage(msg)) {\n *   for (const result of msg.results) {\n *     console.log(`Tool ${result.toolCallId}:`, result.result);\n *   }\n * }\n * ```\n */\nexport function isToolResultMessage(msg: Message): msg is ToolResultMessage {\n  return msg.type === MessageRole.ToolResult;\n}\n","/**\n * @fileoverview Internal handler registry and resolver utilities.\n *\n * @module core/provider-handlers\n */\n\nimport type {\n  ProviderIdentity,\n  LLMHandler,\n  EmbeddingHandler,\n  ImageHandler,\n} from '../types/provider.ts';\n\n/**\n * Resolver for dynamically selecting LLM handlers based on model options.\n *\n * Used by providers that support multiple API modes (e.g., OpenAI with responses/completions).\n * The resolver eliminates shared mutable state by storing the mode on the ModelReference\n * and resolving the correct handler at request time.\n *\n * @typeParam TOptions - Provider-specific options type\n */\nexport interface LLMHandlerResolver<TOptions = unknown> {\n  /** Map of mode identifiers to their corresponding LLM handlers */\n  handlers: Record<string, LLMHandler>;\n  /** The default mode when options don't specify one */\n  defaultMode: string;\n  /** Function to extract the mode from provider options */\n  getMode: (options: TOptions | undefined) => string;\n}\n\n/**\n * Type guard to check if a value is an LLMHandlerResolver.\n */\nexport function isHandlerResolver<TOptions>(\n  value: LLMHandler | LLMHandlerResolver<TOptions> | undefined\n): value is LLMHandlerResolver<TOptions> {\n  return value !== undefined && 'handlers' in value && 'getMode' in value;\n}\n\ntype ProviderHandlers<TOptions = unknown> = {\n  llm?: LLMHandler;\n  embedding?: EmbeddingHandler;\n  image?: ImageHandler;\n  llmResolver?: LLMHandlerResolver<TOptions>;\n};\n\nconst providerHandlers = new WeakMap<object, ProviderHandlers<unknown>>();\n\n/**\n * Registers handler implementations for a provider.\n */\nexport function registerProviderHandlers<TOptions>(\n  provider: ProviderIdentity,\n  handlers: ProviderHandlers<TOptions>\n): void {\n  providerHandlers.set(provider as object, handlers as ProviderHandlers<unknown>);\n}\n\nfunction getProviderHandlers<TOptions>(\n  provider: ProviderIdentity\n): ProviderHandlers<TOptions> | undefined {\n  return providerHandlers.get(provider as object) as ProviderHandlers<TOptions> | undefined;\n}\n\n/**\n * Resolves the correct LLM handler based on model reference options.\n *\n * For providers with multiple LLM handlers (e.g., OpenAI with responses/completions APIs),\n * this function determines which handler to use based on the options stored on the\n * ModelReference. This eliminates race conditions from shared mutable state.\n *\n * For providers with a single LLM handler, this simply returns that handler.\n *\n * @typeParam TOptions - Provider-specific options type\n * @param provider - The provider to resolve the handler from\n * @param options - The options from the ModelReference\n * @returns The resolved LLM handler, or undefined if LLM is not supported\n *\n * @internal\n */\nexport function resolveLLMHandler<TOptions = unknown>(\n  provider: ProviderIdentity,\n  options: TOptions | undefined\n): LLMHandler | undefined {\n  const handlers = getProviderHandlers(provider);\n  const resolver = handlers?.llmResolver;\n\n  if (resolver) {\n    const mode = resolver.getMode(options);\n    return resolver.handlers[mode] ?? handlers?.llm;\n  }\n\n  return handlers?.llm;\n}\n\n/**\n * Resolves the embedding handler for a provider, if supported.\n *\n * @internal\n */\nexport function resolveEmbeddingHandler<TParams = unknown>(\n  provider: ProviderIdentity\n): EmbeddingHandler<TParams> | undefined {\n  const handlers = getProviderHandlers(provider);\n  return handlers?.embedding as EmbeddingHandler<TParams> | undefined;\n}\n\n/**\n * Resolves the image handler for a provider, if supported.\n *\n * @internal\n */\nexport function resolveImageHandler<TParams = unknown>(\n  provider: ProviderIdentity\n): ImageHandler<TParams> | undefined {\n  const handlers = getProviderHandlers(provider);\n  return handlers?.image as ImageHandler<TParams> | undefined;\n}\n","/**\n * @fileoverview Base provider interface and factory for the Universal Provider Protocol.\n *\n * This module provides the foundation for creating AI providers that conform to the\n * UPP specification. Providers are callable functions that create model references\n * and register internal handlers for LLM, embedding, and image modalities.\n *\n * @module core/provider\n */\n\nimport type {\n  Provider,\n  ModelReference,\n  LLMHandler,\n  EmbeddingHandler,\n  ImageHandler,\n  LLMProvider,\n  EmbeddingProvider,\n  ImageProvider,\n} from '../types/provider.ts';\nimport type { LLMHandlerResolver } from './provider-handlers.ts';\nimport { isHandlerResolver, registerProviderHandlers } from './provider-handlers.ts';\n\n\n/**\n * Configuration options for creating a new provider.\n *\n * @typeParam TOptions - Provider-specific options type\n *\n * @example\n * ```typescript\n * // Simple provider with single handler\n * const options: CreateProviderOptions = {\n *   name: 'my-provider',\n *   version: '1.0.0',\n *   handlers: {\n *     llm: createLLMHandler(),\n *     embedding: createEmbeddingHandler(),\n *   },\n * };\n *\n * // Provider with multiple LLM handlers (API modes)\n * const options: CreateProviderOptions<OpenAIOptions> = {\n *   name: 'openai',\n *   version: '1.0.0',\n *   handlers: {\n *     llm: {\n *       handlers: { responses: handler1, completions: handler2 },\n *       defaultMode: 'responses',\n *       getMode: (opts) => opts?.api ?? 'responses',\n *     },\n *   },\n * };\n * ```\n */\nexport interface CreateProviderOptions<TOptions = unknown> {\n  /** Unique identifier for the provider */\n  name: string;\n  /** Semantic version string for the provider implementation */\n  version: string;\n  /** Handlers for supported modalities (LLM, embedding, image generation) */\n  handlers: {\n    /** Handler for language model completions, or resolver for multi-handler providers */\n    llm?: LLMHandler | LLMHandlerResolver<TOptions>;\n    /** Handler for text embeddings */\n    embedding?: EmbeddingHandler;\n    /** Handler for image generation */\n    image?: ImageHandler;\n  };\n  /**\n   * Custom function to create model references from options.\n   * Use this to map provider options to providerConfig (e.g., betas to headers).\n   */\n  createModelReference?: (\n    modelId: string,\n    options: TOptions | undefined,\n    provider: Provider<TOptions>\n  ) => ModelReference<TOptions>;\n}\n\n\n/**\n * Creates a provider factory function with registered modality handlers.\n *\n * The returned provider is a callable function that creates model references\n * when invoked with a model ID. It exposes `name` and `version` metadata.\n *\n * @typeParam TOptions - Provider-specific options type (defaults to unknown)\n * @param options - Provider configuration including name, version, and handlers\n * @returns A callable Provider with handlers registered internally\n *\n * @example\n * ```typescript\n * // Create a basic provider\n * const anthropic = createProvider({\n *   name: 'anthropic',\n *   version: '1.0.0',\n *   handlers: { llm: createLLMHandler() },\n * });\n *\n * // Use the provider to create a model reference\n * const model = anthropic('claude-sonnet-4-20250514');\n *\n * // Provider with custom options type\n * interface MyOptions { apiVersion?: 'v1' | 'v2' }\n * const myProvider = createProvider<MyOptions>({\n *   name: 'my-provider',\n *   version: '1.0.0',\n *   handlers: { llm: handler },\n * });\n *\n * // Provider with multiple LLM handlers (API modes)\n * const openai = createProvider<OpenAIOptions>({\n *   name: 'openai',\n *   version: '1.0.0',\n *   handlers: {\n *     llm: {\n *       handlers: { responses: responsesHandler, completions: completionsHandler },\n *       defaultMode: 'responses',\n *       getMode: (opts) => opts?.api ?? 'responses',\n *     },\n *   },\n * });\n * ```\n */\nexport function createProvider<TOptions = unknown>(\n  options: CreateProviderOptions<TOptions>\n): Provider<TOptions> {\n  // Resolve the default LLM handler for capabilities/bind\n  const llmInput = options.handlers.llm;\n  const hasResolver = isHandlerResolver<TOptions>(llmInput);\n  const defaultLLMHandler = hasResolver ? llmInput.handlers[llmInput.defaultMode] : llmInput;\n\n  if (hasResolver && !defaultLLMHandler) {\n    throw new Error(\n      `Provider '${options.name}' LLM resolver defaultMode '${llmInput.defaultMode}' has no handler`\n    );\n  }\n\n  // Create the factory function\n  const fn = function (modelId: string, modelOptions?: TOptions): ModelReference<TOptions> {\n    if (options.createModelReference) {\n      return options.createModelReference(modelId, modelOptions, provider);\n    }\n    // Default: store options on the reference for handler resolution\n    return { modelId, provider, options: modelOptions };\n  };\n\n  Object.defineProperties(fn, {\n    name: {\n      value: options.name,\n      writable: false,\n      configurable: true,\n    },\n    version: {\n      value: options.version,\n      writable: false,\n      configurable: true,\n    },\n  });\n\n  const provider = fn as Provider<TOptions>;\n\n  // If there's a resolver, set provider on all handlers\n  if (hasResolver) {\n    for (const handler of Object.values(llmInput.handlers)) {\n      handler._setProvider?.(provider as unknown as LLMProvider);\n    }\n  } else if (defaultLLMHandler?._setProvider) {\n    defaultLLMHandler._setProvider(provider as unknown as LLMProvider);\n  }\n\n  if (options.handlers.embedding?._setProvider) {\n    options.handlers.embedding._setProvider(provider as unknown as EmbeddingProvider);\n  }\n  if (options.handlers.image?._setProvider) {\n    options.handlers.image._setProvider(provider as unknown as ImageProvider);\n  }\n\n  registerProviderHandlers(provider, {\n    llm: defaultLLMHandler,\n    embedding: options.handlers.embedding,\n    image: options.handlers.image,\n    ...(hasResolver ? { llmResolver: llmInput } : {}),\n  });\n\n  return provider;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-MKDLXV4O.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/types/turn.ts"],"sourcesContent":["/**\n * @fileoverview Turn types for inference results.\n *\n * A Turn represents the complete result of one inference call, including\n * all messages produced during tool execution loops, token usage, and\n * optional structured output data.\n *\n * @module types/turn\n */\n\nimport type { Message, AssistantMessage } from './messages.ts';\nimport type { ToolExecution } from './tool.ts';\nimport type { MessageJSON } from './thread.ts';\n\n/**\n * Token usage information for an inference request.\n *\n * Tracks input and output tokens across all inference cycles,\n * with optional per-cycle breakdown and cache metrics.\n *\n * @example\n * ```typescript\n * const usage: TokenUsage = {\n *   inputTokens: 150,\n *   outputTokens: 50,\n *   totalTokens: 200,\n *   cacheReadTokens: 100,\n *   cacheWriteTokens: 50,\n *   cycles: [\n *     { inputTokens: 100, outputTokens: 30, cacheReadTokens: 0, cacheWriteTokens: 50 },\n *     { inputTokens: 50, outputTokens: 20, cacheReadTokens: 100, cacheWriteTokens: 0 }\n *   ]\n * };\n * ```\n */\nexport interface TokenUsage {\n  /** Total input tokens across all cycles */\n  inputTokens: number;\n\n  /** Total output tokens across all cycles */\n  outputTokens: number;\n\n  /** Sum of input and output tokens */\n  totalTokens: number;\n\n  /**\n   * Tokens read from cache (cache hits).\n   * Returns 0 for providers that don't support or report cache metrics.\n   */\n  cacheReadTokens: number;\n\n  /**\n   * Tokens written to cache (cache misses that were cached).\n   * Only Anthropic reports this metric; returns 0 for other providers.\n   */\n  cacheWriteTokens: number;\n\n  /** Per-cycle token breakdown (if multiple cycles occurred) */\n  cycles?: Array<{\n    inputTokens: number;\n    outputTokens: number;\n    cacheReadTokens: number;\n    cacheWriteTokens: number;\n  }>;\n}\n\n/**\n * A Turn represents the complete result of one inference call.\n *\n * Includes all messages produced during tool execution loops,\n * the final assistant response, token usage, and optional\n * structured output data.\n *\n * @typeParam TData - Type of the structured output data\n *\n * @example\n * ```typescript\n * const turn = await instance.generate('Hello');\n * console.log(turn.response.text);\n * console.log(`Used ${turn.usage.totalTokens} tokens in ${turn.cycles} cycles`);\n *\n * // With structured output\n * interface WeatherData { temperature: number; conditions: string; }\n * const turn = await instance.generate<WeatherData>('Get weather');\n * console.log(turn.data?.temperature);\n * ```\n */\nexport interface Turn<TData = unknown> {\n  /**\n   * All messages produced during this inference, in chronological order.\n   * Includes UserMessage, AssistantMessage (may include toolCalls), and ToolResultMessage.\n   */\n  readonly messages: Message[];\n\n  /** The final assistant response (last AssistantMessage in the turn) */\n  readonly response: AssistantMessage;\n\n  /**\n   * Tool executions that occurred during this turn.\n   *\n   * Execution order reflects completion timing, not call order.\n   * Correlate with tool calls using toolCallId.\n   */\n  readonly toolExecutions: ToolExecution[];\n\n  /** Aggregate token usage for the entire turn */\n  readonly usage: TokenUsage;\n\n  /** Total number of inference cycles (1 + number of tool rounds) */\n  readonly cycles: number;\n\n  /**\n   * Structured output data (if a structure schema was provided).\n   * Type is inferred from the schema when using TypeScript.\n   */\n  readonly data?: TData;\n}\n\n/**\n * Turn serialized to JSON format.\n * Messages are converted to MessageJSON, response is omitted (computed from messages).\n *\n * @remarks\n * This type is derived from {@link Turn} and should stay in sync with it.\n */\nexport type TurnJSON = Omit<Turn, 'messages' | 'response'> & {\n  messages: MessageJSON[];\n};\n\n/**\n * Creates a Turn from accumulated inference data.\n *\n * @typeParam TData - Type of the structured output data\n * @param messages - All messages produced during the inference\n * @param toolExecutions - Record of all tool executions\n * @param usage - Aggregate token usage\n * @param cycles - Number of inference cycles\n * @param data - Optional structured output data\n * @returns A complete Turn object\n * @throws Error if no assistant message is found in the messages\n *\n * @example\n * ```typescript\n * const turn = createTurn(\n *   [userMsg, assistantMsg],\n *   [],\n *   { inputTokens: 100, outputTokens: 50, totalTokens: 150 },\n *   1\n * );\n * ```\n */\nexport function createTurn<TData = unknown>(\n  messages: Message[],\n  toolExecutions: ToolExecution[],\n  usage: TokenUsage,\n  cycles: number,\n  data?: TData\n): Turn<TData> {\n  const response = messages\n    .filter((m): m is AssistantMessage => m.type === 'assistant')\n    .pop();\n\n  if (!response) {\n    throw new Error('Turn must contain at least one assistant message');\n  }\n\n  return {\n    messages,\n    response,\n    toolExecutions,\n    usage,\n    cycles,\n    data,\n  };\n}\n\n/**\n * Creates an empty TokenUsage object.\n *\n * @returns A TokenUsage with all values set to zero\n *\n * @example\n * ```typescript\n * const usage = emptyUsage();\n * // { inputTokens: 0, outputTokens: 0, totalTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, cycles: [] }\n * ```\n */\nexport function emptyUsage(): TokenUsage {\n  return {\n    inputTokens: 0,\n    outputTokens: 0,\n    totalTokens: 0,\n    cacheReadTokens: 0,\n    cacheWriteTokens: 0,\n    cycles: [],\n  };\n}\n\n/**\n * Aggregates token usage from multiple inference cycles.\n *\n * @param usages - Array of TokenUsage objects to aggregate\n * @returns Combined TokenUsage with per-cycle breakdown\n *\n * @example\n * ```typescript\n * const cycle1 = { inputTokens: 100, outputTokens: 30, totalTokens: 130, cacheReadTokens: 50, cacheWriteTokens: 0 };\n * const cycle2 = { inputTokens: 150, outputTokens: 40, totalTokens: 190, cacheReadTokens: 100, cacheWriteTokens: 0 };\n * const total = aggregateUsage([cycle1, cycle2]);\n * // { inputTokens: 250, outputTokens: 70, totalTokens: 320, cacheReadTokens: 150, cacheWriteTokens: 0, cycles: [...] }\n * ```\n */\nexport function aggregateUsage(usages: TokenUsage[]): TokenUsage {\n  const cycles: TokenUsage['cycles'] = [];\n  let inputTokens = 0;\n  let outputTokens = 0;\n  let cacheReadTokens = 0;\n  let cacheWriteTokens = 0;\n\n  for (const usage of usages) {\n    inputTokens += usage.inputTokens;\n    outputTokens += usage.outputTokens;\n    cacheReadTokens += usage.cacheReadTokens;\n    cacheWriteTokens += usage.cacheWriteTokens;\n    cycles.push({\n      inputTokens: usage.inputTokens,\n      outputTokens: usage.outputTokens,\n      cacheReadTokens: usage.cacheReadTokens,\n      cacheWriteTokens: usage.cacheWriteTokens,\n    });\n  }\n\n  return {\n    inputTokens,\n    outputTokens,\n    totalTokens: inputTokens + outputTokens,\n    cacheReadTokens,\n    cacheWriteTokens,\n    cycles,\n  };\n}\n"],"mappings":";AAuJO,SAAS,WACd,UACA,gBACA,OACA,QACA,MACa;AACb,QAAM,WAAW,SACd,OAAO,CAAC,MAA6B,EAAE,SAAS,WAAW,EAC3D,IAAI;AAEP,MAAI,CAAC,UAAU;AACb,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAaO,SAAS,aAAyB;AACvC,SAAO;AAAA,IACL,aAAa;AAAA,IACb,cAAc;AAAA,IACd,aAAa;AAAA,IACb,iBAAiB;AAAA,IACjB,kBAAkB;AAAA,IAClB,QAAQ,CAAC;AAAA,EACX;AACF;AAgBO,SAAS,eAAe,QAAkC;AAC/D,QAAM,SAA+B,CAAC;AACtC,MAAI,cAAc;AAClB,MAAI,eAAe;AACnB,MAAI,kBAAkB;AACtB,MAAI,mBAAmB;AAEvB,aAAW,SAAS,QAAQ;AAC1B,mBAAe,MAAM;AACrB,oBAAgB,MAAM;AACtB,uBAAmB,MAAM;AACzB,wBAAoB,MAAM;AAC1B,WAAO,KAAK;AAAA,MACV,aAAa,MAAM;AAAA,MACnB,cAAc,MAAM;AAAA,MACpB,iBAAiB,MAAM;AAAA,MACvB,kBAAkB,MAAM;AAAA,IAC1B,CAAC;AAAA,EACH;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,aAAa,cAAc;AAAA,IAC3B;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}