@tanstack/ai 0.24.0 → 0.26.0

package/dist/esm/activities/chat/adapter.d.ts

@@ -1,4 +1,4 @@
-import { DefaultMessageMetadataByModality, JSONSchema, Modality, StreamChunk, TextOptions } from '../../types.js';
+import { DefaultMessageMetadataByModality, JSONSchema, Modality, StreamChunk, TextOptions, TokenUsage } from '../../types.js';
 /**
  * Configuration for adapter instances
  */
@@ -31,6 +31,8 @@ export interface StructuredOutputResult<T = unknown> {
     data: T;
     /** The raw text response from the model before parsing */
     rawText: string;
+    /** Token usage information (if provided by the adapter) */
+    usage?: TokenUsage;
 }
 /**
  * Text adapter interface with pre-resolved generics.

package/dist/esm/activities/chat/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n} from '../../types'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AAkKO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAYC;AAAA,EAEV,YAAY,SAA4B,CAAA,GAAI,OAAe;AACzD,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAcU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}
+{"version":3,"file":"adapter.js","sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AAqKO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAYC;AAAA,EAEV,YAAY,SAA4B,CAAA,GAAI,OAAe;AACzD,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAcU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}

package/dist/esm/activities/chat/middleware/types.d.ts

@@ -1,4 +1,4 @@
-import { JSONSchema, ModelMessage, StreamChunk, Tool, ToolCall, UsageTotals } from '../../../types.js';
+import { JSONSchema, ModelMessage, StreamChunk, TokenUsage, Tool, ToolCall } from '../../../types.js';
 import { SystemPrompt } from '../../../system-prompts.js';
 /**
  * Phase of the chat middleware lifecycle.
@@ -204,11 +204,11 @@ export interface ToolPhaseCompleteInfo {
  * Token usage statistics passed to the onUsage hook.
  * Extracted from the RUN_FINISHED chunk when usage data is present.
  *
- * Includes optional provider-reported `cost`/`costDetails` (see {@link UsageTotals}).
- * Kept as an interface extending `UsageTotals` to preserve declaration merging for
+ * Includes optional provider-reported `cost`/`costDetails` (see {@link TokenUsage}).
+ * Kept as an interface extending `TokenUsage` to preserve declaration merging for
  * this publicly exported type.
  */
-export interface UsageInfo extends UsageTotals {
+export interface UsageInfo extends TokenUsage {
 }
 /**
  * Information passed to onFinish.
@@ -221,7 +221,7 @@ export interface FinishInfo {
     /** Final accumulated text content */
     content: string;
     /** Final usage totals, if available (optionally including provider-reported cost) */
-    usage?: UsageTotals | undefined;
+    usage?: TokenUsage | undefined;
 }
 /**
  * Information passed to onAbort.

package/dist/esm/activities/generateAudio/index.js

@@ -45,6 +45,15 @@ async function runGenerateAudio(options) {
       modelOptions: rest.modelOptions,
       timestamp: Date.now()
     });
+    if (result.usage) {
+      aiEventClient.emit("audio:usage", {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions,
+        timestamp: Date.now()
+      });
+    }
     logger.output(`activity=generateAudio provider=${providerName}`, {
       contentType: result.audio.contentType,
       audioDuration: result.audio.duration

package/dist/esm/activities/generateAudio/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateAudio/index.ts"],"sourcesContent":["/**\n * Audio Generation Activity\n *\n * Generates audio (music, sound effects, etc.) from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { AudioAdapter } from './adapter'\nimport type { AudioGenerationResult, StreamChunk } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'audio' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from an AudioAdapter via ~types.\n */\nexport type AudioProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the audio generation activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The audio adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface AudioActivityOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The audio adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Provider-specific options for audio generation */\n  modelOptions?: AudioProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<AudioGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the audio generation activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<AudioGenerationResult>\n */\nexport type AudioActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<AudioGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Audio generation activity - generates audio from text prompts.\n *\n * Uses AI models to create music, sound effects, and other audio content.\n *\n * @example Generate music from a prompt\n * ```ts\n * import { generateAudio } from '@tanstack/ai'\n * import { falAudio } from '@tanstack/ai-fal'\n *\n * const result = await generateAudio({\n *   adapter: falAudio('fal-ai/diffrhythm'),\n *   prompt: 'An upbeat electronic track with synths',\n *   duration: 10\n * })\n *\n * console.log(result.audio.url) // URL to generated audio\n * ```\n */\nexport function generateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateAudio(options),\n    ) as AudioActivityResult<TStream>\n  }\n  return runGenerateAudio(options) as AudioActivityResult<TStream>\n}\n\n/**\n * Run the core audio generation logic (non-streaming).\n */\nasync function runGenerateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n>(\n  options: AudioActivityOptions<TAdapter, boolean>,\n): Promise<AudioGenerationResult> {\n  const { adapter, stream: _stream, debug: _debug, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('audio')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  aiEventClient.emit('audio:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    duration: rest.duration,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateAudio provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateAudio({ ...rest, model, logger })\n    const elapsedMs = Date.now() - startTime\n\n    aiEventClient.emit('audio:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    logger.output(`activity=generateAudio provider=${providerName}`, {\n      contentType: result.audio.contentType,\n      audioDuration: result.audio.duration,\n    })\n\n    return result\n  } catch (error) {\n    const elapsedMs = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('audio:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    logger.errors('generateAudio activity failed', {\n      error,\n      source: 'generateAudio',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateAudio() function without executing.\n */\nexport function createAudioOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  AudioAdapter,\n  AudioAdapterConfig,\n  AnyAudioAdapter,\n} from './adapter'\nexport { BaseAudioAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAoEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAyBO,SAAS,cAId,SAC8B;AAC9B,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,iBAAiB,OAAO;AAAA,IAAA;AAAA,EAE5B;AACA,SAAO,iBAAiB,OAAO;AACjC;AAKA,eAAe,iBAGb,SACgC;AAChC,QAAM,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,GAAG,SAAS;AAC7D,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,OAAO;AAClC,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,gBAAc,KAAK,yBAAyB;AAAA,IAC1C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,UAAU,KAAK;AAAA,IACf,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,mCAAmC,YAAY,IAAI;AAAA,IAChE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,cAAc,EAAE,GAAG,MAAM,OAAO,QAAQ;AACrE,UAAM,YAAY,KAAK,IAAA,IAAQ;AAE/B,kBAAc,KAAK,2BAA2B;AAAA,MAC5C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO,OAAO,mCAAmC,YAAY,IAAI;AAAA,MAC/D,aAAa,OAAO,MAAM;AAAA,MAC1B,eAAe,OAAO,MAAM;AAAA,IAAA,CAC7B;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,YAAY,KAAK,IAAA,IAAQ;AAC/B,UAAM,MAAM;AACZ,kBAAc,KAAK,uBAAuB;AAAA,MACxC;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,KAAA;AAAA,MACzC,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AACD,WAAO,OAAO,iCAAiC;AAAA,MAC7C;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,mBAId,SACyC;AACzC,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateAudio/index.ts"],"sourcesContent":["/**\n * Audio Generation Activity\n *\n * Generates audio (music, sound effects, etc.) from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { AudioAdapter } from './adapter'\nimport type { AudioGenerationResult, StreamChunk } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'audio' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from an AudioAdapter via ~types.\n */\nexport type AudioProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the audio generation activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The audio adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface AudioActivityOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The audio adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Provider-specific options for audio generation */\n  modelOptions?: AudioProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<AudioGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the audio generation activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<AudioGenerationResult>\n */\nexport type AudioActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<AudioGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Audio generation activity - generates audio from text prompts.\n *\n * Uses AI models to create music, sound effects, and other audio content.\n *\n * @example Generate music from a prompt\n * ```ts\n * import { generateAudio } from '@tanstack/ai'\n * import { falAudio } from '@tanstack/ai-fal'\n *\n * const result = await generateAudio({\n *   adapter: falAudio('fal-ai/diffrhythm'),\n *   prompt: 'An upbeat electronic track with synths',\n *   duration: 10\n * })\n *\n * console.log(result.audio.url) // URL to generated audio\n * ```\n */\nexport function generateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateAudio(options),\n    ) as AudioActivityResult<TStream>\n  }\n  return runGenerateAudio(options) as AudioActivityResult<TStream>\n}\n\n/**\n * Run the core audio generation logic (non-streaming).\n */\nasync function runGenerateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n>(\n  options: AudioActivityOptions<TAdapter, boolean>,\n): Promise<AudioGenerationResult> {\n  const { adapter, stream: _stream, debug: _debug, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('audio')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  aiEventClient.emit('audio:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    duration: rest.duration,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateAudio provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateAudio({ ...rest, model, logger })\n    const elapsedMs = Date.now() - startTime\n\n    aiEventClient.emit('audio:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('audio:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateAudio provider=${providerName}`, {\n      contentType: result.audio.contentType,\n      audioDuration: result.audio.duration,\n    })\n\n    return result\n  } catch (error) {\n    const elapsedMs = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('audio:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    logger.errors('generateAudio activity failed', {\n      error,\n      source: 'generateAudio',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateAudio() function without executing.\n */\nexport function createAudioOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  AudioAdapter,\n  AudioAdapterConfig,\n  AnyAudioAdapter,\n} from './adapter'\nexport { BaseAudioAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAoEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAyBO,SAAS,cAId,SAC8B;AAC9B,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,iBAAiB,OAAO;AAAA,IAAA;AAAA,EAE5B;AACA,SAAO,iBAAiB,OAAO;AACjC;AAKA,eAAe,iBAGb,SACgC;AAChC,QAAM,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,GAAG,SAAS;AAC7D,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,OAAO;AAClC,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,gBAAc,KAAK,yBAAyB;AAAA,IAC1C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,UAAU,KAAK;AAAA,IACf,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,mCAAmC,YAAY,IAAI;AAAA,IAChE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,cAAc,EAAE,GAAG,MAAM,OAAO,QAAQ;AACrE,UAAM,YAAY,KAAK,IAAA,IAAQ;AAE/B,kBAAc,KAAK,2BAA2B;AAAA,MAC5C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,QAAI,OAAO,OAAO;AAChB,oBAAc,KAAK,eAAe;AAAA,QAChC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,QACd,cAAc,KAAK;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAEA,WAAO,OAAO,mCAAmC,YAAY,IAAI;AAAA,MAC/D,aAAa,OAAO,MAAM;AAAA,MAC1B,eAAe,OAAO,MAAM;AAAA,IAAA,CAC7B;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,YAAY,KAAK,IAAA,IAAQ;AAC/B,UAAM,MAAM;AACZ,kBAAc,KAAK,uBAAuB;AAAA,MACxC;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,KAAA;AAAA,MACzC,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AACD,WAAO,OAAO,iCAAiC;AAAA,MAC7C;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,mBAId,SACyC;AACzC,SAAO;AACT;"}

package/dist/esm/activities/generateSpeech/index.js

@@ -50,6 +50,15 @@ async function runGenerateSpeech(options) {
       modelOptions: rest.modelOptions,
       timestamp: Date.now()
     });
+    if (result.usage) {
+      aiEventClient.emit("speech:usage", {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions,
+        timestamp: Date.now()
+      });
+    }
     logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {
       bytes: result.audio.length,
       contentType: result.contentType

package/dist/esm/activities/generateSpeech/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { TTSAdapter } from './adapter'\nimport type { StreamChunk, TTSResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> =\n  TAdapter extends TTSAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TTSResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the TTS activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TTSResult>\n */\nexport type TTSActivityResult<TStream extends boolean = false> =\n  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiSpeech } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport function generateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateSpeech(options),\n    ) as TTSActivityResult<TStream>\n  }\n  return runGenerateSpeech(options) as TTSActivityResult<TStream>\n}\n\n/**\n * Run the core TTS generation logic (non-streaming).\n */\nasync function runGenerateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n>(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {\n  const { adapter, stream: _stream, debug: _debug, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('speech')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: rest.text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateSpeech provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateSpeech({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {\n      bytes: result.audio.length,\n      contentType: result.contentType,\n    })\n\n    return result\n  } catch (error) {\n    const duration = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('speech:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    logger.errors('generateSpeech activity failed', {\n      error,\n      source: 'generateSpeech',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: TTSActivityOptions<TAdapter, TStream>,\n): TTSActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAqEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAoCO,SAAS,eAGd,SAA4E;AAC5E,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,kBAAkB,OAAO;AAAA,IAAA;AAAA,EAE7B;AACA,SAAO,kBAAkB,OAAO;AAClC;AAKA,eAAe,kBAEb,SAAoE;AACpE,QAAM,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,GAAG,SAAS;AAC7D,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,QAAQ;AACnC,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,gBAAc,KAAK,0BAA0B;AAAA,IAC3C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,MAAM,KAAK;AAAA,IACX,OAAO,KAAK;AAAA,IACZ,QAAQ,KAAK;AAAA,IACb,OAAO,KAAK;AAAA,IACZ,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,oCAAoC,YAAY,IAAI;AAAA,IACjE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,QAAQ;AACtE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,4BAA4B;AAAA,MAC7C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,MACf,eAAe,OAAO;AAAA,MACtB,aAAa,OAAO;AAAA,MACpB;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO,OAAO,iCAAiC,OAAO,MAAM,MAAM,IAAI;AAAA,MACpE,OAAO,OAAO,MAAM;AAAA,MACpB,aAAa,OAAO;AAAA,IAAA,CACrB;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,WAAW,KAAK,IAAA,IAAQ;AAC9B,UAAM,MAAM;AACZ,kBAAc,KAAK,wBAAwB;AAAA,MACzC;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,KAAA;AAAA,MACzC;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AACD,WAAO,OAAO,kCAAkC;AAAA,MAC9C;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,oBAId,SACuC;AACvC,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { TTSAdapter } from './adapter'\nimport type { StreamChunk, TTSResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> =\n  TAdapter extends TTSAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TTSResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the TTS activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TTSResult>\n */\nexport type TTSActivityResult<TStream extends boolean = false> =\n  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiSpeech } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport function generateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateSpeech(options),\n    ) as TTSActivityResult<TStream>\n  }\n  return runGenerateSpeech(options) as TTSActivityResult<TStream>\n}\n\n/**\n * Run the core TTS generation logic (non-streaming).\n */\nasync function runGenerateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n>(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {\n  const { adapter, stream: _stream, debug: _debug, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('speech')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: rest.text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateSpeech provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateSpeech({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('speech:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {\n      bytes: result.audio.length,\n      contentType: result.contentType,\n    })\n\n    return result\n  } catch (error) {\n    const duration = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('speech:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    logger.errors('generateSpeech activity failed', {\n      error,\n      source: 'generateSpeech',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: TTSActivityOptions<TAdapter, TStream>,\n): TTSActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAqEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAoCO,SAAS,eAGd,SAA4E;AAC5E,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,kBAAkB,OAAO;AAAA,IAAA;AAAA,EAE7B;AACA,SAAO,kBAAkB,OAAO;AAClC;AAKA,eAAe,kBAEb,SAAoE;AACpE,QAAM,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,GAAG,SAAS;AAC7D,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,QAAQ;AACnC,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,gBAAc,KAAK,0BAA0B;AAAA,IAC3C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,MAAM,KAAK;AAAA,IACX,OAAO,KAAK;AAAA,IACZ,QAAQ,KAAK;AAAA,IACb,OAAO,KAAK;AAAA,IACZ,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,oCAAoC,YAAY,IAAI;AAAA,IACjE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,QAAQ;AACtE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,4BAA4B;AAAA,MAC7C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,MACf,eAAe,OAAO;AAAA,MACtB,aAAa,OAAO;AAAA,MACpB;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,QAAI,OAAO,OAAO;AAChB,oBAAc,KAAK,gBAAgB;AAAA,QACjC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,QACd,cAAc,KAAK;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAEA,WAAO,OAAO,iCAAiC,OAAO,MAAM,MAAM,IAAI;AAAA,MACpE,OAAO,OAAO,MAAM;AAAA,MACpB,aAAa,OAAO;AAAA,IAAA,CACrB;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,WAAW,KAAK,IAAA,IAAQ;AAC9B,UAAM,MAAM;AACZ,kBAAc,KAAK,wBAAwB;AAAA,MACzC;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,KAAA;AAAA,MACzC;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AACD,WAAO,OAAO,kCAAkC;AAAA,MAC9C;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,oBAId,SACuC;AACvC,SAAO;AACT;"}

package/dist/esm/extend-adapter.d.ts

@@ -13,13 +13,24 @@ import { Modality } from './types.js';
  * ] as const
  * ```
  */
-export interface ExtendedModelDef<TName extends string = string, TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TOptions = unknown> {
+export interface ExtendedModelDef<TName extends string = string, TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TOptions = unknown, TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>, TTools extends ReadonlyArray<string> = ReadonlyArray<string>> {
     /** The model name identifier */
     name: TName;
     /** Supported input modalities for this model */
     input: TInput;
     /** Type brand for provider options - use `{} as YourOptionsType` */
     modelOptions: TOptions;
+    /** Optional declared features (e.g. 'reasoning', 'structured_outputs') */
+    features?: TFeatures;
+    /** Optional declared provider tools (e.g. 'web_search') */
+    tools?: TTools;
+}
+/** Capability bag accepted by the object form of `createModel`. */
+export interface ModelCapabilities<TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>, TTools extends ReadonlyArray<string> = ReadonlyArray<string>, TOptions = unknown> {
+    input?: TInput;
+    features?: TFeatures;
+    tools?: TTools;
+    modelOptions?: TOptions;
 }
 /**
  * Creates a custom model definition for use with `extendAdapter`.
@@ -47,8 +58,19 @@ export interface ExtendedModelDef<TName extends string = string, TInput extends
  *
  * const myOpenai = extendAdapter(openaiText, customModels)
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Capabilities object form - declare features and provider tools
+ * const reasoner = createModel('reasoner', {
+ *   input: ['text'],
+ *   features: ['reasoning', 'structured_outputs'],
+ *   tools: ['web_search'],
+ * })
+ * ```
  */
 export declare function createModel<const TName extends string, const TInput extends ReadonlyArray<Modality>>(name: TName, input: TInput): ExtendedModelDef<TName, TInput>;
+export declare function createModel<const TName extends string, const TCaps extends ModelCapabilities>(name: TName, capabilities: TCaps): ExtendedModelDef<TName, TCaps['input'] extends ReadonlyArray<Modality> ? TCaps['input'] : ReadonlyArray<Modality>, TCaps['modelOptions'], TCaps['features'] extends ReadonlyArray<string> ? TCaps['features'] : ReadonlyArray<string>, TCaps['tools'] extends ReadonlyArray<string> ? TCaps['tools'] : ReadonlyArray<string>>;
 /**
  * Extract the model name union from an array of model definitions.
  */

package/dist/esm/extend-adapter.js

@@ -1,8 +1,14 @@
-function createModel(name, input) {
+function createModel(name, second) {
+  if (Array.isArray(second)) {
+    return { name, input: second, modelOptions: {} };
+  }
+  const caps = second;
   return {
     name,
-    input,
-    modelOptions: {}
+    input: caps.input ?? ["text"],
+    modelOptions: caps.modelOptions ?? {},
+    features: caps.features,
+    tools: caps.tools
   };
 }
 function extendAdapter(factory, _customModels) {

package/dist/esm/extend-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"extend-adapter.js","sources":["../../src/extend-adapter.ts"],"sourcesContent":["import type { Modality } from './types'\n\n// ===========================\n// Extended Model Definition\n// ===========================\n\n/**\n * Definition for a custom model to add to an adapter.\n *\n * @template TName - The model name as a literal string type\n * @template TInput - Array of supported input modalities\n * @template TOptions - Provider options type for this model\n *\n * @example\n * ```typescript\n * const customModels = [\n *   createModel('my-custom-model', ['text', 'image']),\n * ] as const\n * ```\n */\nexport interface ExtendedModelDef<\n  TName extends string = string,\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TOptions = unknown,\n> {\n  /** The model name identifier */\n  name: TName\n  /** Supported input modalities for this model */\n  input: TInput\n  /** Type brand for provider options - use `{} as YourOptionsType` */\n  modelOptions: TOptions\n}\n\n/**\n * Creates a custom model definition for use with `extendAdapter`.\n *\n * This is a helper function that provides proper type inference without\n * requiring manual `as const` casts on individual properties.\n *\n * @template TName - The model name (inferred from argument)\n * @template TInput - The input modalities array (inferred from argument)\n *\n * @param name - The model name identifier (literal string)\n * @param input - Array of supported input modalities\n * @returns A properly typed model definition for use with `extendAdapter`\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models with full type inference\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * const myOpenai = extendAdapter(openaiText, customModels)\n * ```\n */\nexport function createModel<\n  const TName extends string,\n  const TInput extends ReadonlyArray<Modality>,\n>(name: TName, input: TInput): ExtendedModelDef<TName, TInput> {\n  return {\n    name,\n    input,\n    modelOptions: {},\n  }\n}\n\n// ===========================\n// Type Extraction Utilities\n// ===========================\n\n/**\n * Extract the model name union from an array of model definitions.\n */\ntype ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =\n  TDefs[number]['name']\n\n// ===========================\n// Factory Type Inference\n// ===========================\n\n/**\n * Infer the model parameter type from an adapter factory function.\n * For generic functions like `<T extends Union>(model: T)`, this gets `T` which\n * TypeScript treats as the constraint union when used in parameter position.\n */\ntype InferFactoryModels<TFactory> = TFactory extends (\n  model: infer TModel,\n  ...args: Array<any>\n) => any\n  ? TModel extends string\n    ? TModel\n    : string\n  : string\n\n/**\n * Infer the config parameter type from an adapter factory function.\n */\ntype InferConfig<TFactory> = TFactory extends (\n  model: any,\n  config?: infer TConfig,\n) => any\n  ? TConfig\n  : undefined\n\n/**\n * Infer the adapter return type from a factory function.\n */\ntype InferAdapterReturn<TFactory> = TFactory extends (\n  ...args: Array<any>\n) => infer TReturn\n  ? TReturn\n  : never\n\n// ===========================\n// extendAdapter Function\n// ===========================\n\n/**\n * Extends an existing adapter factory with additional custom models.\n *\n * The extended adapter accepts both original models (with full original type inference)\n * and custom models (with types from your definitions).\n *\n * At runtime, this simply passes through to the original factory - no validation is performed.\n * The original factory's signature is fully preserved, including any config parameters.\n *\n * @param factory - The original adapter factory function (e.g., `openaiText`, `anthropicText`)\n * @param models - Array of custom model definitions with `name` and `input`\n * @returns A new factory function that accepts both original and custom models\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * // Create extended adapter\n * const myOpenai = extendAdapter(openaiText, customModels)\n *\n * // Use with original models - full type inference preserved\n * const gpt4 = myOpenai('gpt-4o')\n *\n * // Use with custom models\n * const custom = myOpenai('my-fine-tuned-gpt4')\n *\n * // Type error: 'invalid-model' is not a valid model\n * // myOpenai('invalid-model')\n *\n * // Works with chat()\n * chat({\n *   adapter: myOpenai('my-fine-tuned-gpt4'),\n *   messages: [...]\n * })\n * ```\n */\nexport function extendAdapter<\n  TFactory extends (...args: Array<any>) => any,\n  const TDefs extends ReadonlyArray<ExtendedModelDef>,\n>(\n  factory: TFactory,\n  _customModels: TDefs,\n): (\n  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,\n  ...args: InferConfig<TFactory> extends undefined\n    ? []\n    : [config?: InferConfig<TFactory>]\n) => InferAdapterReturn<TFactory> {\n  // At runtime, we simply pass through to the original factory.\n  // The _customModels parameter is only used for type inference.\n  // No runtime validation - users are trusted to pass valid model names.\n  return factory as any\n}\n"],"names":[],"mappings":"AA4DO,SAAS,YAGd,MAAa,OAAgD;AAC7D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,cAAc,CAAA;AAAA,EAAC;AAEnB;AAgGO,SAAS,cAId,SACA,eAMgC;AAIhC,SAAO;AACT;"}
+{"version":3,"file":"extend-adapter.js","sources":["../../src/extend-adapter.ts"],"sourcesContent":["import type { Modality } from './types'\n\n// ===========================\n// Extended Model Definition\n// ===========================\n\n/**\n * Definition for a custom model to add to an adapter.\n *\n * @template TName - The model name as a literal string type\n * @template TInput - Array of supported input modalities\n * @template TOptions - Provider options type for this model\n *\n * @example\n * ```typescript\n * const customModels = [\n *   createModel('my-custom-model', ['text', 'image']),\n * ] as const\n * ```\n */\nexport interface ExtendedModelDef<\n  TName extends string = string,\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TOptions = unknown,\n  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,\n> {\n  /** The model name identifier */\n  name: TName\n  /** Supported input modalities for this model */\n  input: TInput\n  /** Type brand for provider options - use `{} as YourOptionsType` */\n  modelOptions: TOptions\n  /** Optional declared features (e.g. 'reasoning', 'structured_outputs') */\n  features?: TFeatures\n  /** Optional declared provider tools (e.g. 'web_search') */\n  tools?: TTools\n}\n\n/** Capability bag accepted by the object form of `createModel`. */\nexport interface ModelCapabilities<\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TOptions = unknown,\n> {\n  input?: TInput\n  features?: TFeatures\n  tools?: TTools\n  modelOptions?: TOptions\n}\n\n/**\n * Creates a custom model definition for use with `extendAdapter`.\n *\n * This is a helper function that provides proper type inference without\n * requiring manual `as const` casts on individual properties.\n *\n * @template TName - The model name (inferred from argument)\n * @template TInput - The input modalities array (inferred from argument)\n *\n * @param name - The model name identifier (literal string)\n * @param input - Array of supported input modalities\n * @returns A properly typed model definition for use with `extendAdapter`\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models with full type inference\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * const myOpenai = extendAdapter(openaiText, customModels)\n * ```\n *\n * @example\n * ```typescript\n * // Capabilities object form - declare features and provider tools\n * const reasoner = createModel('reasoner', {\n *   input: ['text'],\n *   features: ['reasoning', 'structured_outputs'],\n *   tools: ['web_search'],\n * })\n * ```\n */\n// Overload 1 — legacy positional input array (unchanged behavior)\nexport function createModel<\n  const TName extends string,\n  const TInput extends ReadonlyArray<Modality>,\n>(name: TName, input: TInput): ExtendedModelDef<TName, TInput>\n// Overload 2 — capabilities object\nexport function createModel<\n  const TName extends string,\n  const TCaps extends ModelCapabilities,\n>(\n  name: TName,\n  capabilities: TCaps,\n): ExtendedModelDef<\n  TName,\n  TCaps['input'] extends ReadonlyArray<Modality>\n    ? TCaps['input']\n    : ReadonlyArray<Modality>,\n  TCaps['modelOptions'],\n  TCaps['features'] extends ReadonlyArray<string>\n    ? TCaps['features']\n    : ReadonlyArray<string>,\n  TCaps['tools'] extends ReadonlyArray<string>\n    ? TCaps['tools']\n    : ReadonlyArray<string>\n>\n// Implementation\nexport function createModel(\n  name: string,\n  second: ReadonlyArray<Modality> | ModelCapabilities,\n): ExtendedModelDef {\n  if (Array.isArray(second)) {\n    return { name, input: second, modelOptions: {} }\n  }\n  const caps = second as ModelCapabilities\n  return {\n    name,\n    input: caps.input ?? (['text'] as ReadonlyArray<Modality>),\n    modelOptions: caps.modelOptions ?? {},\n    features: caps.features,\n    tools: caps.tools,\n  }\n}\n\n// ===========================\n// Type Extraction Utilities\n// ===========================\n\n/**\n * Extract the model name union from an array of model definitions.\n */\ntype ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =\n  TDefs[number]['name']\n\n// ===========================\n// Factory Type Inference\n// ===========================\n\n/**\n * Infer the model parameter type from an adapter factory function.\n * For generic functions like `<T extends Union>(model: T)`, this gets `T` which\n * TypeScript treats as the constraint union when used in parameter position.\n */\ntype InferFactoryModels<TFactory> = TFactory extends (\n  model: infer TModel,\n  ...args: Array<any>\n) => any\n  ? TModel extends string\n    ? TModel\n    : string\n  : string\n\n/**\n * Infer the config parameter type from an adapter factory function.\n */\ntype InferConfig<TFactory> = TFactory extends (\n  model: any,\n  config?: infer TConfig,\n) => any\n  ? TConfig\n  : undefined\n\n/**\n * Infer the adapter return type from a factory function.\n */\ntype InferAdapterReturn<TFactory> = TFactory extends (\n  ...args: Array<any>\n) => infer TReturn\n  ? TReturn\n  : never\n\n// ===========================\n// extendAdapter Function\n// ===========================\n\n/**\n * Extends an existing adapter factory with additional custom models.\n *\n * The extended adapter accepts both original models (with full original type inference)\n * and custom models (with types from your definitions).\n *\n * At runtime, this simply passes through to the original factory - no validation is performed.\n * The original factory's signature is fully preserved, including any config parameters.\n *\n * @param factory - The original adapter factory function (e.g., `openaiText`, `anthropicText`)\n * @param models - Array of custom model definitions with `name` and `input`\n * @returns A new factory function that accepts both original and custom models\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * // Create extended adapter\n * const myOpenai = extendAdapter(openaiText, customModels)\n *\n * // Use with original models - full type inference preserved\n * const gpt4 = myOpenai('gpt-4o')\n *\n * // Use with custom models\n * const custom = myOpenai('my-fine-tuned-gpt4')\n *\n * // Type error: 'invalid-model' is not a valid model\n * // myOpenai('invalid-model')\n *\n * // Works with chat()\n * chat({\n *   adapter: myOpenai('my-fine-tuned-gpt4'),\n *   messages: [...]\n * })\n * ```\n */\nexport function extendAdapter<\n  TFactory extends (...args: Array<any>) => any,\n  const TDefs extends ReadonlyArray<ExtendedModelDef>,\n>(\n  factory: TFactory,\n  _customModels: TDefs,\n): (\n  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,\n  ...args: InferConfig<TFactory> extends undefined\n    ? []\n    : [config?: InferConfig<TFactory>]\n) => InferAdapterReturn<TFactory> {\n  // At runtime, we simply pass through to the original factory.\n  // The _customModels parameter is only used for type inference.\n  // No runtime validation - users are trusted to pass valid model names.\n  return factory as any\n}\n"],"names":[],"mappings":"AAmHO,SAAS,YACd,MACA,QACkB;AAClB,MAAI,MAAM,QAAQ,MAAM,GAAG;AACzB,WAAO,EAAE,MAAM,OAAO,QAAQ,cAAc,CAAA,EAAC;AAAA,EAC/C;AACA,QAAM,OAAO;AACb,SAAO;AAAA,IACL;AAAA,IACA,OAAO,KAAK,SAAU,CAAC,MAAM;AAAA,IAC7B,cAAc,KAAK,gBAAgB,CAAA;AAAA,IACnC,UAAU,KAAK;AAAA,IACf,OAAO,KAAK;AAAA,EAAA;AAEhB;AAgGO,SAAS,cAId,SACA,eAMgC;AAIhC,SAAO;AACT;"}

package/dist/esm/index.d.ts

@@ -17,6 +17,7 @@ export { maxIterations, untilFinishReason, combineStrategies, } from './activiti
 export { createToolRegistry, createFrozenRegistry, type ToolRegistry, } from './tool-registry.js';
 export type { ChatMiddleware, ChatMiddlewareContext, ChatMiddlewarePhase, ChatMiddlewareConfig, StructuredOutputMiddlewareConfig, ToolCallHookContext, BeforeToolCallDecision, AfterToolCallInfo, IterationInfo, ToolPhaseCompleteInfo, UsageInfo, FinishInfo, AbortInfo, ErrorInfo, } from './activities/chat/middleware/index.js';
 export * from './types.js';
+export { buildBaseUsage, type BaseUsageInput } from './utilities/usage.js';
 export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts.js';
 export { normalizeSystemPrompts } from './system-prompts.js';
 export { detectImageMimeType } from './utils.js';
@@ -30,6 +31,6 @@ export { uiMessagesToWire } from './utilities/ag-ui-wire.js';
 export type { WireMessage } from './utilities/ag-ui-wire.js';
 export { isContentPart, isContentPartArray, normalizeToolResult, } from './utilities/tool-result.js';
 export { createModel, extendAdapter } from './extend-adapter.js';
-export type { ExtendedModelDef } from './extend-adapter.js';
+export type { ExtendedModelDef, ModelCapabilities } from './extend-adapter.js';
 export type { Logger, DebugCategories, DebugConfig, DebugOption, } from './logger/types.js';
 export { ConsoleLogger } from './logger/console-logger.js';

package/dist/esm/index.js

@@ -12,6 +12,7 @@ import { ToolCallManager } from "./activities/chat/tools/tool-calls.js";
 import { brandProviderTool } from "./tools/provider-tool.js";
 import { combineStrategies, maxIterations, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
 import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
+import { buildBaseUsage } from "./utilities/usage.js";
 import { normalizeSystemPrompts } from "./system-prompts.js";
 import { detectImageMimeType } from "./utils.js";
 import { realtimeToken } from "./realtime/index.js";
@@ -38,6 +39,7 @@ export {
   ToolCallManager,
   WordBoundaryStrategy,
   brandProviderTool,
+  buildBaseUsage,
   chat,
   chatParamsFromRequest,
   chatParamsFromRequestBody,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/types.d.ts

@@ -1,6 +1,7 @@
 import { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
 import { InternalLogger } from './logger/internal-logger.js';
 import { SystemPrompt } from './system-prompts.js';
+import { CompletionTokensDetails, PromptTokensDetails, ProviderUsageDetails, TokenUsage, UsageCostBreakdown } from '@tanstack/ai-event-client';
 import { BaseEvent as AGUIBaseEvent, CustomEvent as AGUICustomEvent, MessagesSnapshotEvent as AGUIMessagesSnapshotEvent, ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent, ReasoningEndEvent as AGUIReasoningEndEvent, ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent, ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent, ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent, ReasoningStartEvent as AGUIReasoningStartEvent, RunErrorEvent as AGUIRunErrorEvent, RunFinishedEvent as AGUIRunFinishedEvent, RunStartedEvent as AGUIRunStartedEvent, StateDeltaEvent as AGUIStateDeltaEvent, StateSnapshotEvent as AGUIStateSnapshotEvent, StepFinishedEvent as AGUIStepFinishedEvent, StepStartedEvent as AGUIStepStartedEvent, TextMessageContentEvent as AGUITextMessageContentEvent, TextMessageEndEvent as AGUITextMessageEndEvent, TextMessageStartEvent as AGUITextMessageStartEvent, ToolCallArgsEvent as AGUIToolCallArgsEvent, ToolCallEndEvent as AGUIToolCallEndEvent, ToolCallResultEvent as AGUIToolCallResultEvent, ToolCallStartEvent as AGUIToolCallStartEvent, EventType } from '@ag-ui/core';
 /**
  * Tool call states - track the lifecycle of a tool call
@@ -787,37 +788,13 @@ export interface RunStartedEvent extends AGUIRunStartedEvent {
     /** Model identifier for multi-model support */
     model?: string;
 }
+export type { CompletionTokensDetails, PromptTokensDetails, ProviderUsageDetails, TokenUsage, UsageCostBreakdown, };
 /**
- * Provider-reported cost breakdown for a single request, normalized onto a
- * canonical shape so consumer code is portable across gateways. Each adapter's
- * extractor maps its provider-specific wire keys (e.g. OpenRouter's
- * `upstream_inference_prompt_cost`, `upstream_inference_input_cost`) onto these
- * fields at runtime.
+ * @deprecated Renamed to {@link TokenUsage}. Kept as an alias for backward
+ * compatibility with `@tanstack/ai@0.23` and earlier; will be removed in a
+ * future release.
  */
-export interface UsageCostBreakdown {
-    /** Total cost the gateway paid the upstream provider. */
-    upstreamCost?: number;
-    /** Upstream cost for input (prompt) tokens. */
-    upstreamInputCost?: number;
-    /** Upstream cost for output (completion) tokens. */
-    upstreamOutputCost?: number;
-}
-/**
- * Token usage totals for a run, optionally including provider-reported cost.
- *
- * `cost` and `costDetails` are populated only by adapters whose provider returns
- * authoritative per-request cost (e.g. OpenRouter). They are absent for adapters
- * that do not report cost, so consumers must treat them as optional.
- */
-export interface UsageTotals {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-    /** Provider-reported cost for the request, when available. */
-    cost?: number;
-    /** Provider-reported cost breakdown, when available. */
-    costDetails?: UsageCostBreakdown;
-}
+export type UsageTotals = TokenUsage;
 /**
  * Emitted when a run completes successfully.
  *
@@ -829,8 +806,8 @@ export interface RunFinishedEvent extends AGUIRunFinishedEvent {
     model?: string;
     /** Why the generation stopped */
     finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null;
-    /** Token usage statistics, optionally including provider-reported cost. */
-    usage?: UsageTotals;
+    /** Token usage statistics with optional detailed breakdowns and provider-reported cost. */
+    usage?: TokenUsage;
 }
 /**
  * Emitted when an error occurs during a run.
@@ -1219,11 +1196,7 @@ export interface TextCompletionChunk {
     content: string;
     role?: 'assistant';
     finishReason?: 'stop' | 'length' | 'content_filter' | null;
-    usage?: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-    };
+    usage?: TokenUsage;
 }
 export interface SummarizationOptions<TProviderOptions extends object = Record<string, unknown>> {
     model: string;
@@ -1243,11 +1216,7 @@ export interface SummarizationResult {
     id: string;
     model: string;
     summary: string;
-    usage: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-    };
+    usage: TokenUsage;
 }
 /**
  * Options for image generation.
@@ -1303,11 +1272,7 @@ export interface ImageGenerationResult {
     /** Array of generated images */
     images: Array<GeneratedImage>;
     /** Token usage information (if available) */
-    usage?: {
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-    };
+    usage?: TokenUsage;
 }
 /**
  * Options for audio generation (music, sound effects, etc.).
@@ -1349,11 +1314,7 @@ export interface AudioGenerationResult {
     /** The generated audio */
     audio: GeneratedAudio;
     /** Token usage information (if available) */
-    usage?: {
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-    };
+    usage?: TokenUsage;
 }
 /**
  * Options for video generation.
@@ -1457,6 +1418,8 @@ export interface TTSResult {
     duration?: number;
     /** Content type of the audio (e.g., 'audio/mp3') */
     contentType?: string;
+    /** Token usage information (if provided by the adapter) */
+    usage?: TokenUsage;
 }
 /**
  * Options for audio transcription.
@@ -1528,6 +1491,8 @@ export interface TranscriptionResult {
     segments?: Array<TranscriptionSegment>;
     /** Word-level timestamps, if available */
     words?: Array<TranscriptionWord>;
+    /** Token usage information (if provided by the adapter) */
+    usage?: TokenUsage;
 }
 /**
  * Default metadata type for adapters that don't define custom metadata.

package/dist/esm/utilities/usage.d.ts

@@ -0,0 +1,31 @@
+import { ProviderUsageDetails, TokenUsage } from '../types.js';
+/**
+ * Input parameters for building base TokenUsage.
+ * Provider functions should extract these from their SDK's response.
+ */
+export interface BaseUsageInput {
+    /** Total input/prompt tokens */
+    promptTokens: number;
+    /** Total output/completion tokens */
+    completionTokens: number;
+    /** Total tokens (prompt + completion) */
+    totalTokens: number;
+}
+/**
+ * Builds the base TokenUsage object with core fields.
+ * Provider-specific functions should use this and then add their own details.
+ *
+ * @param input - The base token counts
+ * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens
+ *
+ * @example
+ * ```typescript
+ * const base = buildBaseUsage({
+ *   promptTokens: 100,
+ *   completionTokens: 50,
+ *   totalTokens: 150
+ * });
+ * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }
+ * ```
+ */
+export declare function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(input: BaseUsageInput): TokenUsage<TProviderDetails>;

package/dist/esm/utilities/usage.js

@@ -0,0 +1,11 @@
+function buildBaseUsage(input) {
+  return {
+    promptTokens: input.promptTokens,
+    completionTokens: input.completionTokens,
+    totalTokens: input.totalTokens
+  };
+}
+export {
+  buildBaseUsage
+};
+//# sourceMappingURL=usage.js.map

package/dist/esm/utilities/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sources":["../../../src/utilities/usage.ts"],"sourcesContent":["import type { ProviderUsageDetails, TokenUsage } from '../types'\n\n/**\n * Input parameters for building base TokenUsage.\n * Provider functions should extract these from their SDK's response.\n */\nexport interface BaseUsageInput {\n  /** Total input/prompt tokens */\n  promptTokens: number\n  /** Total output/completion tokens */\n  completionTokens: number\n  /** Total tokens (prompt + completion) */\n  totalTokens: number\n}\n\n/**\n * Builds the base TokenUsage object with core fields.\n * Provider-specific functions should use this and then add their own details.\n *\n * @param input - The base token counts\n * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens\n *\n * @example\n * ```typescript\n * const base = buildBaseUsage({\n *   promptTokens: 100,\n *   completionTokens: 50,\n *   totalTokens: 150\n * });\n * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }\n * ```\n */\nexport function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(\n  input: BaseUsageInput,\n): TokenUsage<TProviderDetails> {\n  return {\n    promptTokens: input.promptTokens,\n    completionTokens: input.completionTokens,\n    totalTokens: input.totalTokens,\n  }\n}\n"],"names":[],"mappings":"AAgCO,SAAS,eACd,OAC8B;AAC9B,SAAO;AAAA,IACL,cAAc,MAAM;AAAA,IACpB,kBAAkB,MAAM;AAAA,IACxB,aAAa,MAAM;AAAA,EAAA;AAEvB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.4.3"
+    "@tanstack/ai-event-client": "0.5.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -2,9 +2,11 @@
 name: ai-core/adapter-configuration
 description: >
   Provider adapter selection and configuration: openaiText, anthropicText,
-  geminiText, ollamaText, grokText, groqText, openRouterText. Per-model
+  geminiText, ollamaText, grokText, groqText, openRouterText, openaiCompatible. Per-model
   type safety with modelOptions, reasoning/thinking configuration,
   runtime adapter switching, extendAdapter() for custom models, createModel().
+  Generic OpenAI-compatible providers (DeepSeek, Together, Fireworks, etc.) via
+  openaiCompatible({ baseURL, apiKey, models }) from @tanstack/ai-openai/compatible.
   API key env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY,
   XAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST.
 type: sub-skill
@@ -60,15 +62,16 @@ into the factory, not into `chat()`.
 Each provider has a dedicated package with tree-shakeable adapter factories.
 The text adapter is the primary one for chat/completions:
 
-| Provider   | Package                   | Factory          | Env Var                                           |
-| ---------- | ------------------------- | ---------------- | ------------------------------------------------- |
-| OpenAI     | `@tanstack/ai-openai`     | `openaiText`     | `OPENAI_API_KEY`                                  |
-| Anthropic  | `@tanstack/ai-anthropic`  | `anthropicText`  | `ANTHROPIC_API_KEY`                               |
-| Gemini     | `@tanstack/ai-gemini`     | `geminiText`     | `GOOGLE_API_KEY` or `GEMINI_API_KEY`              |
-| Grok (xAI) | `@tanstack/ai-grok`       | `grokText`       | `XAI_API_KEY`                                     |
-| Groq       | `@tanstack/ai-groq`       | `groqText`       | `GROQ_API_KEY`                                    |
-| OpenRouter | `@tanstack/ai-openrouter` | `openRouterText` | `OPENROUTER_API_KEY`                              |
-| Ollama     | `@tanstack/ai-ollama`     | `ollamaText`     | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+| Provider          | Package                          | Factory                                     | Env Var                                           |
+| ----------------- | -------------------------------- | ------------------------------------------- | ------------------------------------------------- |
+| OpenAI            | `@tanstack/ai-openai`            | `openaiText`                                | `OPENAI_API_KEY`                                  |
+| Anthropic         | `@tanstack/ai-anthropic`         | `anthropicText`                             | `ANTHROPIC_API_KEY`                               |
+| Gemini            | `@tanstack/ai-gemini`            | `geminiText`                                | `GOOGLE_API_KEY` or `GEMINI_API_KEY`              |
+| Grok (xAI)        | `@tanstack/ai-grok`              | `grokText`                                  | `XAI_API_KEY`                                     |
+| Groq              | `@tanstack/ai-groq`              | `groqText`                                  | `GROQ_API_KEY`                                    |
+| OpenRouter        | `@tanstack/ai-openrouter`        | `openRouterText`                            | `OPENROUTER_API_KEY`                              |
+| Ollama            | `@tanstack/ai-ollama`            | `ollamaText`                                | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+| OpenAI-compatible | `@tanstack/ai-openai/compatible` | `openaiCompatible` / `openaiCompatibleText` | provider-specific (passed via `apiKey`)           |
 
 ```typescript
 // Each factory takes model as first arg, optional config as second
@@ -252,6 +255,63 @@ Subclasses can override to narrow the capability. When extending an
 adapter for a custom model that doesn't support the combination, return
 `false` explicitly.
 
+### 6. OpenAI-Compatible Providers
+
+Any provider that implements the OpenAI **Chat Completions** API (DeepSeek,
+Moonshot/Kimi, Together, Fireworks, Cerebras, Qwen/DashScope, Perplexity,
+NVIDIA NIM, LM Studio, etc.) can be used through the generic
+`openaiCompatible` factory from `@tanstack/ai-openai/compatible` — no
+dedicated package required.
+
+```typescript
+import { openaiCompatible } from '@tanstack/ai-openai/compatible'
+import { createModel } from '@tanstack/ai'
+
+// Provider-factory: configure baseURL + apiKey + models ONCE,
+// then select a model per call (the model arg is a type-safe union).
+const deepseek = openaiCompatible({
+  name: 'deepseek', // optional label for devtools/errors (default 'openai-compatible')
+  baseURL: 'https://api.deepseek.com/v1',
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+  models: [
+    'deepseek-chat', // bare string → optimistic defaults: text/image in, streaming, tools, structured output
+    createModel('deepseek-reasoner', {
+      // rich def → precise per-model capabilities
+      input: ['text'],
+      features: ['reasoning', 'structured_outputs'],
+    }),
+  ],
+})
+
+chat({ adapter: deepseek('deepseek-chat'), messages })
+chat({ adapter: deepseek('deepseek-reasoner'), messages })
+```
+
+`config` also accepts any OpenAI SDK `ClientOptions` (notably `defaultHeaders`
+and `defaultQuery`) for providers that need extra auth headers or query params.
+
+For a single model, use the one-shot helper:
+
+```typescript
+import { openaiCompatibleText } from '@tanstack/ai-openai/compatible'
+
+chat({
+  adapter: openaiCompatibleText('deepseek-chat', {
+    baseURL: 'https://api.deepseek.com/v1',
+    apiKey: process.env.DEEPSEEK_API_KEY!,
+  }),
+  messages,
+})
+```
+
+Pass `api: 'responses'` to target the OpenAI **Responses** API instead of Chat
+Completions (only for the rare compatible provider that implements it, e.g.
+Azure OpenAI); the default is `'chat-completions'`, which is what nearly all
+compatible providers speak.
+
+> Verify the provider's current `baseURL` and model ids against its live docs —
+> they drift. See `docs/adapters/openai-compatible.md` for the full provider table.
+
 ## Common Mistakes
 
 ### a. HIGH: Confusing legacy monolithic with tree-shakeable adapter

package/src/activities/chat/adapter.ts

@@ -4,6 +4,7 @@ import type {
   Modality,
   StreamChunk,
   TextOptions,
+  TokenUsage,
 } from '../../types'
 
 /**
@@ -40,6 +41,8 @@ export interface StructuredOutputResult<T = unknown> {
   data: T
   /** The raw text response from the model before parsing */
   rawText: string
+  /** Token usage information (if provided by the adapter) */
+  usage?: TokenUsage
 }
 
 /**

package/src/activities/chat/middleware/types.ts

@@ -2,9 +2,9 @@ import type {
   JSONSchema,
   ModelMessage,
   StreamChunk,
+  TokenUsage,
   Tool,
   ToolCall,
-  UsageTotals,
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
 
@@ -266,11 +266,11 @@ export interface ToolPhaseCompleteInfo {
  * Token usage statistics passed to the onUsage hook.
  * Extracted from the RUN_FINISHED chunk when usage data is present.
  *
- * Includes optional provider-reported `cost`/`costDetails` (see {@link UsageTotals}).
- * Kept as an interface extending `UsageTotals` to preserve declaration merging for
+ * Includes optional provider-reported `cost`/`costDetails` (see {@link TokenUsage}).
+ * Kept as an interface extending `TokenUsage` to preserve declaration merging for
  * this publicly exported type.
  */
-export interface UsageInfo extends UsageTotals {}
+export interface UsageInfo extends TokenUsage {}
 
 // ===========================
 // Terminal Hook Info
@@ -287,7 +287,7 @@ export interface FinishInfo {
   /** Final accumulated text content */
   content: string
   /** Final usage totals, if available (optionally including provider-reported cost) */
-  usage?: UsageTotals | undefined
+  usage?: TokenUsage | undefined
 }
 
 /**

package/src/activities/generateAudio/index.ts

@@ -174,6 +174,16 @@ async function runGenerateAudio<
       timestamp: Date.now(),
     })
 
+    if (result.usage) {
+      aiEventClient.emit('audio:usage', {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+        timestamp: Date.now(),
+      })
+    }
+
     logger.output(`activity=generateAudio provider=${providerName}`, {
       contentType: result.audio.contentType,
       audioDuration: result.audio.duration,

package/src/activities/generateSpeech/index.ts

@@ -187,6 +187,16 @@ async function runGenerateSpeech<
       timestamp: Date.now(),
     })
 
+    if (result.usage) {
+      aiEventClient.emit('speech:usage', {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+        timestamp: Date.now(),
+      })
+    }
+
     logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {
       bytes: result.audio.length,
       contentType: result.contentType,

package/src/extend-adapter.ts

@@ -22,6 +22,8 @@ export interface ExtendedModelDef<
   TName extends string = string,
   TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
   TOptions = unknown,
+  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,
 > {
   /** The model name identifier */
   name: TName
@@ -29,6 +31,23 @@ export interface ExtendedModelDef<
   input: TInput
   /** Type brand for provider options - use `{} as YourOptionsType` */
   modelOptions: TOptions
+  /** Optional declared features (e.g. 'reasoning', 'structured_outputs') */
+  features?: TFeatures
+  /** Optional declared provider tools (e.g. 'web_search') */
+  tools?: TTools
+}
+
+/** Capability bag accepted by the object form of `createModel`. */
+export interface ModelCapabilities<
+  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
+  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TOptions = unknown,
+> {
+  input?: TInput
+  features?: TFeatures
+  tools?: TTools
+  modelOptions?: TOptions
 }
 
 /**
@@ -57,15 +76,57 @@ export interface ExtendedModelDef<
  *
  * const myOpenai = extendAdapter(openaiText, customModels)
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Capabilities object form - declare features and provider tools
+ * const reasoner = createModel('reasoner', {
+ *   input: ['text'],
+ *   features: ['reasoning', 'structured_outputs'],
+ *   tools: ['web_search'],
+ * })
+ * ```
  */
+// Overload 1 — legacy positional input array (unchanged behavior)
 export function createModel<
   const TName extends string,
   const TInput extends ReadonlyArray<Modality>,
->(name: TName, input: TInput): ExtendedModelDef<TName, TInput> {
+>(name: TName, input: TInput): ExtendedModelDef<TName, TInput>
+// Overload 2 — capabilities object
+export function createModel<
+  const TName extends string,
+  const TCaps extends ModelCapabilities,
+>(
+  name: TName,
+  capabilities: TCaps,
+): ExtendedModelDef<
+  TName,
+  TCaps['input'] extends ReadonlyArray<Modality>
+    ? TCaps['input']
+    : ReadonlyArray<Modality>,
+  TCaps['modelOptions'],
+  TCaps['features'] extends ReadonlyArray<string>
+    ? TCaps['features']
+    : ReadonlyArray<string>,
+  TCaps['tools'] extends ReadonlyArray<string>
+    ? TCaps['tools']
+    : ReadonlyArray<string>
+>
+// Implementation
+export function createModel(
+  name: string,
+  second: ReadonlyArray<Modality> | ModelCapabilities,
+): ExtendedModelDef {
+  if (Array.isArray(second)) {
+    return { name, input: second, modelOptions: {} }
+  }
+  const caps = second as ModelCapabilities
   return {
     name,
-    input,
-    modelOptions: {},
+    input: caps.input ?? (['text'] as ReadonlyArray<Modality>),
+    modelOptions: caps.modelOptions ?? {},
+    features: caps.features,
+    tools: caps.tools,
   }
 }
 

package/src/index.ts

@@ -111,6 +111,9 @@ export type {
 // All types
 export * from './types'
 
+// Usage utilities
+export { buildBaseUsage, type BaseUsageInput } from './utilities/usage'
+
 // System prompts (type + normaliser used by adapters)
 export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts'
 export { normalizeSystemPrompts } from './system-prompts'
@@ -197,7 +200,7 @@ export {
 
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
-export type { ExtendedModelDef } from './extend-adapter'
+export type { ExtendedModelDef, ModelCapabilities } from './extend-adapter'
 
 // Logger
 export type {

package/src/types.ts

@@ -4,6 +4,16 @@ import type {
 } from '@standard-schema/spec'
 import type { InternalLogger } from './logger/internal-logger'
 import type { SystemPrompt } from './system-prompts'
+// The canonical usage types live in the leaf `@tanstack/ai-event-client`
+// package (which `@tanstack/ai` already depends on) so there is a single source
+// of truth without a dependency cycle. They are re-exported below.
+import type {
+  CompletionTokensDetails,
+  PromptTokensDetails,
+  ProviderUsageDetails,
+  TokenUsage,
+  UsageCostBreakdown,
+} from '@tanstack/ai-event-client'
 import type {
   BaseEvent as AGUIBaseEvent,
   CustomEvent as AGUICustomEvent,
@@ -978,38 +988,22 @@ export interface RunStartedEvent extends AGUIRunStartedEvent {
   model?: string
 }
 
-/**
- * Provider-reported cost breakdown for a single request, normalized onto a
- * canonical shape so consumer code is portable across gateways. Each adapter's
- * extractor maps its provider-specific wire keys (e.g. OpenRouter's
- * `upstream_inference_prompt_cost`, `upstream_inference_input_cost`) onto these
- * fields at runtime.
- */
-export interface UsageCostBreakdown {
-  /** Total cost the gateway paid the upstream provider. */
-  upstreamCost?: number
-  /** Upstream cost for input (prompt) tokens. */
-  upstreamInputCost?: number
-  /** Upstream cost for output (completion) tokens. */
-  upstreamOutputCost?: number
+// Re-export the canonical usage types (defined in `@tanstack/ai-event-client`)
+// so `@tanstack/ai` consumers keep importing them from here unchanged.
+export type {
+  CompletionTokensDetails,
+  PromptTokensDetails,
+  ProviderUsageDetails,
+  TokenUsage,
+  UsageCostBreakdown,
 }
 
 /**
- * Token usage totals for a run, optionally including provider-reported cost.
- *
- * `cost` and `costDetails` are populated only by adapters whose provider returns
- * authoritative per-request cost (e.g. OpenRouter). They are absent for adapters
- * that do not report cost, so consumers must treat them as optional.
+ * @deprecated Renamed to {@link TokenUsage}. Kept as an alias for backward
+ * compatibility with `@tanstack/ai@0.23` and earlier; will be removed in a
+ * future release.
  */
-export interface UsageTotals {
-  promptTokens: number
-  completionTokens: number
-  totalTokens: number
-  /** Provider-reported cost for the request, when available. */
-  cost?: number
-  /** Provider-reported cost breakdown, when available. */
-  costDetails?: UsageCostBreakdown
-}
+export type UsageTotals = TokenUsage
 
 /**
  * Emitted when a run completes successfully.
@@ -1022,8 +1016,8 @@ export interface RunFinishedEvent extends AGUIRunFinishedEvent {
   model?: string
   /** Why the generation stopped */
   finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
-  /** Token usage statistics, optionally including provider-reported cost. */
-  usage?: UsageTotals
+  /** Token usage statistics with optional detailed breakdowns and provider-reported cost. */
+  usage?: TokenUsage
 }
 
 /**
@@ -1473,11 +1467,7 @@ export interface TextCompletionChunk {
   content: string
   role?: 'assistant'
   finishReason?: 'stop' | 'length' | 'content_filter' | null
-  usage?: {
-    promptTokens: number
-    completionTokens: number
-    totalTokens: number
-  }
+  usage?: TokenUsage
 }
 
 export interface SummarizationOptions<
@@ -1501,11 +1491,7 @@ export interface SummarizationResult {
   id: string
   model: string
   summary: string
-  usage: {
-    promptTokens: number
-    completionTokens: number
-    totalTokens: number
-  }
+  usage: TokenUsage
 }
 
 // ============================================================================
@@ -1574,11 +1560,7 @@ export interface ImageGenerationResult {
   /** Array of generated images */
   images: Array<GeneratedImage>
   /** Token usage information (if available) */
-  usage?: {
-    inputTokens?: number
-    outputTokens?: number
-    totalTokens?: number
-  }
+  usage?: TokenUsage
 }
 
 // ============================================================================
@@ -1629,11 +1611,7 @@ export interface AudioGenerationResult {
   /** The generated audio */
   audio: GeneratedAudio
   /** Token usage information (if available) */
-  usage?: {
-    inputTokens?: number
-    outputTokens?: number
-    totalTokens?: number
-  }
+  usage?: TokenUsage
 }
 
 // ============================================================================
@@ -1754,6 +1732,8 @@ export interface TTSResult {
   duration?: number
   /** Content type of the audio (e.g., 'audio/mp3') */
   contentType?: string
+  /** Token usage information (if provided by the adapter) */
+  usage?: TokenUsage
 }
 
 // ============================================================================
@@ -1835,6 +1815,8 @@ export interface TranscriptionResult {
   segments?: Array<TranscriptionSegment>
   /** Word-level timestamps, if available */
   words?: Array<TranscriptionWord>
+  /** Token usage information (if provided by the adapter) */
+  usage?: TokenUsage
 }
 
 /**

package/src/utilities/usage.ts

@@ -0,0 +1,41 @@
+import type { ProviderUsageDetails, TokenUsage } from '../types'
+
+/**
+ * Input parameters for building base TokenUsage.
+ * Provider functions should extract these from their SDK's response.
+ */
+export interface BaseUsageInput {
+  /** Total input/prompt tokens */
+  promptTokens: number
+  /** Total output/completion tokens */
+  completionTokens: number
+  /** Total tokens (prompt + completion) */
+  totalTokens: number
+}
+
+/**
+ * Builds the base TokenUsage object with core fields.
+ * Provider-specific functions should use this and then add their own details.
+ *
+ * @param input - The base token counts
+ * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens
+ *
+ * @example
+ * ```typescript
+ * const base = buildBaseUsage({
+ *   promptTokens: 100,
+ *   completionTokens: 50,
+ *   totalTokens: 150
+ * });
+ * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }
+ * ```
+ */
+export function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(
+  input: BaseUsageInput,
+): TokenUsage<TProviderDetails> {
+  return {
+    promptTokens: input.promptTokens,
+    completionTokens: input.completionTokens,
+    totalTokens: input.totalTokens,
+  }
+}