@tanstack/ai 0.41.0 → 0.43.0

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

@@ -1,119 +1,168 @@
-import { aiEventClient } from "@tanstack/ai-event-client";
-import { streamGenerationResult } from "../stream-generation-result.js";
 import { resolveDebugOption } from "../../logger/resolve.js";
-import { createGenerationContext, runGenerationStart, runGenerationUsage, runGenerationFinish, runGenerationError } from "../middleware/run.js";
-const kind = "tts";
+import { streamGenerationResult } from "../stream-generation-result.js";
+import { applyGenerationResultTransforms, createGenerationContext, runGenerationError, runGenerationFinish, runGenerationStart, runGenerationUsage } from "../middleware/run.js";
+import "./adapter.js";
+import { aiEventClient } from "@tanstack/ai-event-client";
+//#region src/activities/generateSpeech/index.ts
+/**
+* TTS Activity
+*
+* Generates speech audio from text using text-to-speech models.
+* This is a self-contained module with implementation, types, and JSDoc.
+*/
+/** The adapter kind this activity handles */
+var kind = "tts";
 function createId(prefix) {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
+/**
+* TTS activity - generates speech from text.
+*
+* Uses AI text-to-speech models to create audio from natural language text.
+*
+* @example Generate speech from text
+* ```ts
+* import { generateSpeech } from '@tanstack/ai'
+* import { openaiSpeech } from '@tanstack/ai-openai'
+*
+* const result = await generateSpeech({
+*   adapter: openaiSpeech('tts-1-hd'),
+*   text: 'Hello, welcome to TanStack AI!',
+*   voice: 'nova'
+* })
+*
+* console.log(result.audio) // base64-encoded audio
+* ```
+*
+* @example With format and speed options
+* ```ts
+* const result = await generateSpeech({
+*   adapter: openaiSpeech('tts-1'),
+*   text: 'This is slower speech.',
+*   voice: 'alloy',
+*   format: 'wav',
+*   speed: 0.8
+* })
+* ```
+*/
 function generateSpeech(options) {
-  if (options.stream) {
-    return streamGenerationResult(
-      () => runGenerateSpeech(options)
-    );
-  }
-  return runGenerateSpeech(options);
+	if (options.stream) return streamGenerationResult((resolved) => runGenerateSpeech({
+		...options,
+		runId: resolved.runId
+	}), options);
+	return runGenerateSpeech(options);
 }
+/**
+* Run the core TTS generation logic (non-streaming).
+*/
 async function runGenerateSpeech(options) {
-  const {
-    adapter,
-    stream: _stream,
-    debug: _debug,
-    middleware,
-    ...rest
-  } = options;
-  const model = adapter.model;
-  const requestId = createId("speech");
-  const startTime = Date.now();
-  const logger = resolveDebugOption(options.debug);
-  const providerName = adapter.provider ?? adapter.name ?? "unknown";
-  const mwCtx = createGenerationContext({
-    requestId,
-    activity: "tts",
-    provider: adapter.name,
-    model,
-    modelOptions: rest.modelOptions,
-    createId
-  });
-  await runGenerationStart(middleware, mwCtx);
-  aiEventClient.emit("speech:request:started", {
-    requestId,
-    provider: adapter.name,
-    model,
-    text: rest.text,
-    voice: rest.voice,
-    format: rest.format,
-    speed: rest.speed,
-    modelOptions: rest.modelOptions,
-    timestamp: startTime
-  });
-  logger.request(`activity=generateSpeech provider=${providerName}`, {
-    provider: providerName,
-    model
-  });
-  try {
-    const result = await adapter.generateSpeech({ ...rest, model, logger });
-    const duration = Date.now() - startTime;
-    aiEventClient.emit("speech:request:completed", {
-      requestId,
-      provider: adapter.name,
-      model,
-      audio: result.audio,
-      format: result.format,
-      audioDuration: result.duration,
-      contentType: result.contentType,
-      duration,
-      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
-    });
-    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage);
-    await runGenerationFinish(middleware, mwCtx, {
-      duration,
-      usage: result.usage
-    });
-    return result;
-  } catch (error) {
-    const duration = Date.now() - startTime;
-    const err = error;
-    aiEventClient.emit("speech:request:error", {
-      requestId,
-      provider: adapter.name,
-      model,
-      error: { message: err.message, name: err.name },
-      duration,
-      modelOptions: rest.modelOptions,
-      timestamp: Date.now()
-    });
-    await runGenerationError(middleware, mwCtx, {
-      error,
-      duration
-    });
-    logger.errors("generateSpeech activity failed", {
-      error,
-      source: "generateSpeech"
-    });
-    throw error;
-  }
+	const { adapter, stream: _stream, debug: _debug, middleware, threadId, runId, ...rest } = options;
+	const model = adapter.model;
+	const requestId = createId("speech");
+	const startTime = Date.now();
+	const logger = resolveDebugOption(options.debug);
+	const providerName = adapter.provider ?? adapter.name ?? "unknown";
+	const mwCtx = createGenerationContext({
+		requestId,
+		activity: "tts",
+		provider: adapter.name,
+		model,
+		modelOptions: rest.modelOptions,
+		artifactInputs: {
+			text: rest.text,
+			voice: rest.voice,
+			format: rest.format,
+			speed: rest.speed
+		},
+		threadId,
+		runId,
+		createId
+	});
+	await runGenerationStart(middleware, mwCtx);
+	aiEventClient.emit("speech:request:started", {
+		requestId,
+		provider: adapter.name,
+		model,
+		text: rest.text,
+		voice: rest.voice,
+		format: rest.format,
+		speed: rest.speed,
+		modelOptions: rest.modelOptions,
+		timestamp: startTime
+	});
+	logger.request(`activity=generateSpeech provider=${providerName}`, {
+		provider: providerName,
+		model
+	});
+	try {
+		const result = await applyGenerationResultTransforms(mwCtx, await adapter.generateSpeech({
+			...rest,
+			model,
+			logger
+		}));
+		const duration = Date.now() - startTime;
+		aiEventClient.emit("speech:request:completed", {
+			requestId,
+			provider: adapter.name,
+			model,
+			audio: result.audio,
+			format: result.format,
+			audioDuration: result.duration,
+			contentType: result.contentType,
+			duration,
+			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
+		});
+		if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage);
+		await runGenerationFinish(middleware, mwCtx, {
+			duration,
+			usage: result.usage
+		});
+		return result;
+	} catch (error) {
+		const duration = Date.now() - startTime;
+		const err = error;
+		aiEventClient.emit("speech:request:error", {
+			requestId,
+			provider: adapter.name,
+			model,
+			error: {
+				message: err.message,
+				name: err.name
+			},
+			duration,
+			modelOptions: rest.modelOptions,
+			timestamp: Date.now()
+		});
+		await runGenerationError(middleware, mwCtx, {
+			error,
+			duration
+		});
+		logger.errors("generateSpeech activity failed", {
+			error,
+			source: "generateSpeech"
+		});
+		throw error;
+	}
 }
+/**
+* Create typed options for the generateSpeech() function without executing.
+*/
 function createSpeechOptions(options) {
-  return options;
+	return options;
 }
-export {
-  createSpeechOptions,
-  generateSpeech,
-  kind
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+export { createSpeechOptions, generateSpeech, kind };
+
+//# sourceMappingURL=index.js.map

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 {\n  createGenerationContext,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware/run'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware/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   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\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 {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    ...rest\n  } = 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  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'tts',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\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    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\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    await runGenerationError(middleware, mwCtx, {\n      error,\n      duration,\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":"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"}
+{"version":3,"file":"index.js","names":[],"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 {\n  applyGenerationResultTransforms,\n  createGenerationContext,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware/run'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware/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   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n  /** Stable conversation/thread id for correlating this run when persisted. */\n  threadId?: string\n  /** Stable run id for correlating this run when persisted. */\n  runId?: string\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      // Only `runId` is taken from the resolved wire identity. `threadId` stays\n      // the CALLER's: `streamGenerationResult` mints one for the RUN_* chunks\n      // when none was passed, and spreading that over the options would hand\n      // middleware a thread id known to nobody, which persistence would then\n      // file the run under. Matches `generateVideo`.\n      (resolved) => runGenerateSpeech({ ...options, runId: resolved.runId }),\n      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 {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    threadId,\n    runId,\n    ...rest\n  } = 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  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'tts',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    artifactInputs: {\n      text: rest.text,\n      voice: rest.voice,\n      format: rest.format,\n      speed: rest.speed,\n    },\n    threadId,\n    runId,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\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 rawResult = await adapter.generateSpeech({ ...rest, model, logger })\n    const result = await applyGenerationResultTransforms(mwCtx, rawResult)\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    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\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    await runGenerationError(middleware, mwCtx, {\n      error,\n      duration,\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"],"mappings":";;;;;;;;;;;;;AA6BA,IAAa,OAAO;AA+EpB,SAAS,SAAS,QAAwB;CACxC,OAAO,GAAG,OAAO,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC;AACzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,eAGd,SAA4E;CAC5E,IAAI,QAAQ,QACV,OAAO,wBAMJ,aAAa,kBAAkB;EAAE,GAAG;EAAS,OAAO,SAAS;CAAM,CAAC,GACrE,OACF;CAEF,OAAO,kBAAkB,OAAO;AAClC;;;;AAKA,eAAe,kBAEb,SAAoE;CACpE,MAAM,EACJ,SACA,QAAQ,SACR,OAAO,QACP,YACA,UACA,OACA,GAAG,SACD;CACJ,MAAM,QAAQ,QAAQ;CACtB,MAAM,YAAY,SAAS,QAAQ;CACnC,MAAM,YAAY,KAAK,IAAI;CAC3B,MAAM,SAAyB,mBAAmB,QAAQ,KAAK;CAC/D,MAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;CAEF,MAAM,QAAQ,wBAAwB;EACpC;EACA,UAAU;EACV,UAAU,QAAQ;EAClB;EACA,cAAc,KAAK;EACnB,gBAAgB;GACd,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,QAAQ,KAAK;GACb,OAAO,KAAK;EACd;EACA;EACA;EACA;CACF,CAAC;CAED,MAAM,mBAAmB,YAAY,KAAK;CAE1C,cAAc,KAAK,0BAA0B;EAC3C;EACA,UAAU,QAAQ;EAClB;EACA,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,QAAQ,KAAK;EACb,OAAO,KAAK;EACZ,cAAc,KAAK;EACnB,WAAW;CACb,CAAC;CAED,OAAO,QAAQ,oCAAoC,gBAAgB;EACjE,UAAU;EACV;CACF,CAAC;CAED,IAAI;EAEF,MAAM,SAAS,MAAM,gCAAgC,OAAO,MADpC,QAAQ,eAAe;GAAE,GAAG;GAAM;GAAO;EAAO,CAAC,CACJ;EACrE,MAAM,WAAW,KAAK,IAAI,IAAI;EAE9B,cAAc,KAAK,4BAA4B;GAC7C;GACA,UAAU,QAAQ;GAClB;GACA,OAAO,OAAO;GACd,QAAQ,OAAO;GACf,eAAe,OAAO;GACtB,aAAa,OAAO;GACpB;GACA,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EAED,IAAI,OAAO,OACT,cAAc,KAAK,gBAAgB;GACjC;GACA;GACA,OAAO,OAAO;GACd,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EAGH,OAAO,OAAO,iCAAiC,OAAO,MAAM,UAAU;GACpE,OAAO,OAAO,MAAM;GACpB,aAAa,OAAO;EACtB,CAAC;EAED,IAAI,OAAO,OAAO,MAAM,mBAAmB,YAAY,OAAO,OAAO,KAAK;EAC1E,MAAM,oBAAoB,YAAY,OAAO;GAC3C;GACA,OAAO,OAAO;EAChB,CAAC;EAED,OAAO;CACT,SAAS,OAAO;EACd,MAAM,WAAW,KAAK,IAAI,IAAI;EAC9B,MAAM,MAAM;EACZ,cAAc,KAAK,wBAAwB;GACzC;GACA,UAAU,QAAQ;GAClB;GACA,OAAO;IAAE,SAAS,IAAI;IAAS,MAAM,IAAI;GAAK;GAC9C;GACA,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EACD,MAAM,mBAAmB,YAAY,OAAO;GAC1C;GACA;EACF,CAAC;EACD,OAAO,OAAO,kCAAkC;GAC9C;GACA,QAAQ;EACV,CAAC;EACD,MAAM;CACR;AACF;;;;AASA,SAAgB,oBAId,SACuC;CACvC,OAAO;AACT"}

package/dist/esm/activities/generateTranscription/adapter.js

@@ -1,16 +1,23 @@
-class BaseTranscriptionAdapter {
-  kind = "transcription";
-  model;
-  config;
-  constructor(model, config = {}) {
-    this.config = config;
-    this.model = model;
-  }
-  generateId() {
-    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-  }
-}
-export {
-  BaseTranscriptionAdapter
+//#region src/activities/generateTranscription/adapter.ts
+/**
+* Abstract base class for audio transcription adapters.
+* Extend this class to implement a transcription adapter for a specific provider.
+*
+* Generic parameters match TranscriptionAdapter - all pre-resolved by the provider function.
+*/
+var BaseTranscriptionAdapter = class {
+	kind = "transcription";
+	model;
+	config;
+	constructor(model, config = {}) {
+		this.config = config;
+		this.model = model;
+	}
+	generateId() {
+		return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+	}
 };
-//# sourceMappingURL=adapter.js.map
+//#endregion
+export { BaseTranscriptionAdapter };
+
+//# sourceMappingURL=adapter.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sources":["../../../../src/activities/generateTranscription/adapter.ts"],"sourcesContent":["import type { TranscriptionOptions, TranscriptionResult } from '../../types'\n\n/**\n * Configuration for transcription adapter instances\n */\nexport interface TranscriptionAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Transcription 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., 'whisper-1')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface TranscriptionAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'transcription'\n  /** Adapter name identifier */\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  }\n\n  /**\n   * Transcribe audio to text\n   */\n  transcribe: (\n    options: TranscriptionOptions<TProviderOptions>,\n  ) => Promise<TranscriptionResult>\n}\n\n/**\n * A TranscriptionAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTranscriptionAdapter = TranscriptionAdapter<any, any>\n\n/**\n * Abstract base class for audio transcription adapters.\n * Extend this class to implement a transcription adapter for a specific provider.\n *\n * Generic parameters match TranscriptionAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTranscriptionAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements TranscriptionAdapter<TModel, TProviderOptions> {\n  readonly kind = 'transcription' 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  }\n\n  protected config: TranscriptionAdapterConfig\n\n  constructor(model: TModel, config: TranscriptionAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract transcribe(\n    options: TranscriptionOptions<TProviderOptions>,\n  ): Promise<TranscriptionResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AA6DO,MAAe,yBAGsC;AAAA,EACjD,OAAO;AAAA,EAEP;AAAA,EAOC;AAAA,EAEV,YAAY,OAAe,SAAqC,IAAI;AAClE,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAMU,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","names":[],"sources":["../../../../src/activities/generateTranscription/adapter.ts"],"sourcesContent":["import type { TranscriptionOptions, TranscriptionResult } from '../../types'\n\n/**\n * Configuration for transcription adapter instances\n */\nexport interface TranscriptionAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Transcription 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., 'whisper-1')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface TranscriptionAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'transcription'\n  /** Adapter name identifier */\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  }\n\n  /**\n   * Transcribe audio to text\n   */\n  transcribe: (\n    options: TranscriptionOptions<TProviderOptions>,\n  ) => Promise<TranscriptionResult>\n}\n\n/**\n * A TranscriptionAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTranscriptionAdapter = TranscriptionAdapter<any, any>\n\n/**\n * Abstract base class for audio transcription adapters.\n * Extend this class to implement a transcription adapter for a specific provider.\n *\n * Generic parameters match TranscriptionAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTranscriptionAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements TranscriptionAdapter<TModel, TProviderOptions> {\n  readonly kind = 'transcription' 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  }\n\n  protected config: TranscriptionAdapterConfig\n\n  constructor(model: TModel, config: TranscriptionAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract transcribe(\n    options: TranscriptionOptions<TProviderOptions>,\n  ): Promise<TranscriptionResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA6DA,IAAsB,2BAAtB,MAG4D;CAC1D,OAAgB;CAEhB;CAOA;CAEA,YAAY,OAAe,SAAqC,CAAC,GAAG;EAClE,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAMA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}

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

@@ -50,6 +50,10 @@ export interface TranscriptionActivityOptions<TAdapter extends TranscriptionAdap
      * `GenerationMiddleware` contract for a custom backend.
      */
     middleware?: Array<GenerationMiddleware>;
+    /** Stable conversation/thread id for correlating this run when persisted. */
+    threadId?: string;
+    /** Stable run id for correlating this run when persisted. */
+    runId?: string;
 }
 /**
  * Result type for the transcription activity.