@tanstack/ai 0.21.3 → 0.22.1

package/dist/esm/activities/generateSpeech/index.d.ts

@@ -58,10 +58,10 @@ export type TTSActivityResult<TStream extends boolean = false> = TStream extends
  * @example Generate speech from text
  * ```ts
  * import { generateSpeech } from '@tanstack/ai'
- * import { openaiTTS } from '@tanstack/ai-openai'
+ * import { openaiSpeech } from '@tanstack/ai-openai'
  *
  * const result = await generateSpeech({
- *   adapter: openaiTTS('tts-1-hd'),
+ *   adapter: openaiSpeech('tts-1-hd'),
  *   text: 'Hello, welcome to TanStack AI!',
  *   voice: 'nova'
  * })
@@ -72,7 +72,7 @@ export type TTSActivityResult<TStream extends boolean = false> = TStream extends
  * @example With format and speed options
  * ```ts
  * const result = await generateSpeech({
- *   adapter: openaiTTS('tts-1'),
+ *   adapter: openaiSpeech('tts-1'),
  *   text: 'This is slower speech.',
  *   voice: 'alloy',
  *   format: 'wav',

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 { openaiTTS } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiTTS('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: openaiTTS('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    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;"}

package/dist/esm/types.d.ts

@@ -650,10 +650,26 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
     request?: Request | RequestInit;
     /**
      * Schema for structured output.
-     * When provided, the adapter should use the provider's native structured output API
-     * to ensure the response conforms to this schema.
-     * The schema will be converted to JSON Schema format before being sent to the provider.
-     * Supports any Standard JSON Schema compliant library (Zod, ArkType, Valibot, etc.).
+     *
+     * **Two distinct use sites:**
+     *
+     * 1. **User-facing (activity layer):** accepts any
+     *    {@link SchemaInput} — Zod, ArkType, Valibot, or a raw JSON Schema.
+     *    The activity layer converts to JSON Schema before handing off.
+     *
+     * 2. **Adapter-facing (`chatStream` call):** the engine populates this with
+     *    a pre-converted JSON Schema **only** when the adapter declared
+     *    `supportsCombinedToolsAndSchema(modelOptions) === true`. The adapter
+     *    should then wire the schema into the upstream request (e.g.
+     *    `response_format: { type: 'json_schema', ... }`, `text.format`,
+     *    `output_format`) alongside any `tools`. The model's natural final
+     *    turn carries the schema-constrained JSON text and the engine
+     *    harvests it from the agent loop without a separate finalization
+     *    round-trip.
+     *
+     *    Adapters that did NOT declare the capability never see this field
+     *    populated — the engine instead invokes `structuredOutput` /
+     *    `structuredOutputStream` after the agent loop.
      */
     outputSchema?: SchemaInput;
     /**

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.21.3",
+  "version": "0.22.1",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TanStack/ai.git",
-    "directory": "packages/typescript/ai"
+    "directory": "packages/ai"
   },
   "type": "module",
   "module": "./dist/esm/index.js",
@@ -64,7 +64,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.3.10"
+    "@tanstack/ai-event-client": "0.4.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

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

@@ -26,7 +26,7 @@ sources:
 
 > **Before implementing:** Ask the user which provider and model they want.
 > Then fetch the latest available models from the provider's source code
-> (check the adapter's model metadata file, e.g. `packages/typescript/ai-openai/src/model-meta.ts`)
+> (check the adapter's model metadata file, e.g. `packages/ai-openai/src/model-meta.ts`)
 > or from the provider's API/docs to recommend the most current model.
 > The model lists in this skill and its reference files may be outdated.
 > Always verify against the source before recommending a specific model.
@@ -221,6 +221,37 @@ const custom = myOpenai('ft:gpt-5.2:my-org:custom-model:abc123')
 At runtime, `extendAdapter` simply passes through to the original factory.
 The `_customModels` parameter is only used for type inference.
 
+### 5. Capability Flag: `supportsCombinedToolsAndSchema`
+
+Adapters can declare an optional capability method:
+
+```ts
+supportsCombinedToolsAndSchema?(modelOptions?: TProviderOptions): boolean
+```
+
+When `true`, the engine wires `outputSchema` into the regular
+`chatStream` call alongside `tools` and harvests the schema-constrained
+JSON from the agent loop's final-turn text — skipping the separate
+`structuredOutput` / `structuredOutputStream` finalization round-trip.
+When `false` (or the method is omitted), the legacy finalization path
+runs.
+
+Current per-adapter status (#605):
+
+| Adapter                                      | Returns                                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `openaiText` / `openaiChatCompletions`       | `true` (all supported models)                                                                     |
+| `anthropicText`                              | `true` for Claude 4.5+ (gated by `ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise |
+| `geminiText`                                 | `true` for Gemini 3.x (gated by `GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise     |
+| `grokText`                                   | `true` for Grok 4 family (gated by `GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise    |
+| `groqText`                                   | `false` (Groq API rejects schema + tools + stream)                                                |
+| `openRouterText` / `openRouterResponsesText` | `false` (per-call resolution is a follow-up)                                                      |
+| `ollamaText`                                 | `false` (constrained-decoding vs tool-call grammar conflict)                                      |
+
+Subclasses can override to narrow the capability. When extending an
+adapter for a custom model that doesn't support the combination, return
+`false` explicitly.
+
 ## Common Mistakes
 
 ### a. HIGH: Confusing legacy monolithic with tree-shakeable adapter

package/skills/ai-core/debug-logging/SKILL.md

@@ -253,7 +253,7 @@ const safe: Logger = {
 }
 ```
 
-Source: packages/typescript/ai/src/logger/internal-logger.ts
+Source: packages/ai/src/logger/internal-logger.ts
 
 ## Cross-References
 

package/skills/ai-core/structured-outputs/SKILL.md

@@ -181,15 +181,27 @@ The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-out
 
 **Adapter coverage for streaming:**
 
-| Adapter                                           | `outputSchema` + `stream: true`                                                               |
-| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `@tanstack/ai-openai`                             | Native single-request stream (Responses API)                                                  |
-| `@tanstack/ai-openrouter`                         | Native single-request stream                                                                  |
-| `@tanstack/ai-grok`                               | Native single-request stream (Chat Completions)                                               |
-| `@tanstack/ai-groq`                               | Native single-request stream (Chat Completions)                                               |
-| All other adapters (anthropic, gemini, ollama, …) | Fallback: runs non-streaming `structuredOutput`, emits one `structured-output.complete` event |
-
-Consumer code is identical across providers — always read the final object off `structured-output.complete`. You only see incremental `TEXT_MESSAGE_CONTENT` deltas when the adapter implements `structuredOutputStream` natively.
+| Adapter                                                         | `outputSchema` + `stream: true`                                                                                                                       |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tanstack/ai-openai` (Responses + Chat Completions)            | **Native combined mode (#605)** — schema wired into the regular `chatStream` call alongside `tools`; engine harvests JSON, no finalization round-trip |
+| `@tanstack/ai-anthropic` (Claude 4.5+ only)                     | **Native combined mode (#605)** — `output_config.format` + `tools` in one beta Messages call. Older Claude models fall back                           |
+| `@tanstack/ai-gemini` (Gemini 3.x only)                         | **Native combined mode (#605)** — `responseSchema` + `tools` in one `generateContentStream`. Gemini 2.x falls back                                    |
+| `@tanstack/ai-grok` (Grok 4 family only)                        | **Native combined mode (#605)** — `response_format: json_schema` + `tools`. Grok 2 / 3 fall back                                                      |
+| `@tanstack/ai-openrouter`                                       | Native single-request stream (legacy `structuredOutputStream` path; per-call combined-mode lookup is a follow-up)                                     |
+| `@tanstack/ai-groq`                                             | Legacy `structuredOutputStream` only (no tools — Groq's API rejects schema + tools + stream)                                                          |
+| All other adapters (ollama, older Claude, Gemini 2.x, Grok 2/3) | Fallback: runs non-streaming `structuredOutput`, emits one `structured-output.complete` event                                                         |
+
+**Native combined mode vs fallback** is signaled by the adapter's
+optional `supportsCombinedToolsAndSchema(modelOptions)` method. When
+it returns `true`, the engine wires the JSON Schema into the regular
+`chatStream` call and harvests the final-turn text — middleware sees
+the run through `beforeModel` / `modelStream` as usual, and the
+`'structuredOutput'` middleware phase does **not** fire. When it
+returns `false` (or is omitted), the engine takes the legacy
+finalization path: agent loop, then a separate `structuredOutput` /
+`structuredOutputStream` call with `'structuredOutput'` phase tagging.
+
+Consumer code is identical across providers — always read the final object off `structured-output.complete`.
 
 ### Pattern 4: useChat with outputSchema (progressive UI)
 

package/src/activities/chat/adapter.ts

@@ -123,6 +123,29 @@ export interface TextAdapter<
   structuredOutputStream?: (
     options: StructuredOutputOptions<TProviderOptions>,
   ) => AsyncIterable<StreamChunk>
+
+  /**
+   * Declares whether the adapter supports combining `tools` and a
+   * schema-constrained final answer in a single streaming request.
+   *
+   * When `true`, the engine wires `outputSchema` into the regular
+   * `chatStream()` call and skips the separate `runStructuredFinalization`
+   * round-trip. The model's natural final turn carries the
+   * schema-constrained JSON text and the engine harvests it from the agent
+   * loop's accumulated content.
+   *
+   * When `false`, `undefined`, or the method is omitted, the engine runs
+   * the agent loop without `outputSchema` and then issues a separate
+   * `structuredOutput` / `structuredOutputStream` call against the JSON
+   * schema for finalization (the legacy path).
+   *
+   * The method receives the per-call `modelOptions` so providers whose
+   * support depends on the resolved upstream model (e.g. OpenRouter) can
+   * answer per-request. Most adapters can return a constant.
+   */
+  supportsCombinedToolsAndSchema?: (
+    modelOptions?: TProviderOptions | undefined,
+  ) => boolean
 }
 
 /**