@tanstack/ai 0.42.0 → 0.43.1

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

@@ -1,109 +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 = "transcription";
+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/generateTranscription/index.ts
+/**
+* Transcription Activity
+*
+* Transcribes audio to text using speech-to-text models.
+* This is a self-contained module with implementation, types, and JSDoc.
+*/
+/** The adapter kind this activity handles */
+var kind = "transcription";
 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)}`;
 }
+/**
+* Transcription activity - converts audio to text.
+*
+* Uses AI speech-to-text models to transcribe audio content.
+*
+* @example Transcribe an audio file
+* ```ts
+* import { generateTranscription } from '@tanstack/ai'
+* import { openaiTranscription } from '@tanstack/ai-openai'
+*
+* const result = await generateTranscription({
+*   adapter: openaiTranscription('whisper-1'),
+*   audio: audioFile, // File, Blob, or base64 string
+*   language: 'en'
+* })
+*
+* console.log(result.text)
+* ```
+*
+* @example With verbose output for timestamps
+* ```ts
+* const result = await generateTranscription({
+*   adapter: openaiTranscription('whisper-1'),
+*   audio: audioFile,
+*   responseFormat: 'verbose_json'
+* })
+*
+* result.segments?.forEach(segment => {
+*   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)
+* })
+* ```
+*
+* @example Streaming transcription result
+* ```ts
+* for await (const chunk of generateTranscription({
+*   adapter: openaiTranscription('whisper-1'),
+*   audio: audioFile,
+*   stream: true
+* })) {
+*   console.log(chunk)
+* }
+* ```
+*/
 function generateTranscription(options) {
-  if (options.stream) {
-    return streamGenerationResult(
-      () => runGenerateTranscription(options)
-    );
-  }
-  return runGenerateTranscription(
-    options
-  );
+	if (options.stream) return streamGenerationResult((resolved) => runGenerateTranscription({
+		...options,
+		runId: resolved.runId
+	}), options);
+	return runGenerateTranscription(options);
 }
+/**
+* Run non-streaming transcription
+*/
 async function runGenerateTranscription(options) {
-  const {
-    adapter,
-    stream: _stream,
-    debug: _debug,
-    middleware,
-    ...rest
-  } = options;
-  const model = adapter.model;
-  const requestId = createId("transcription");
-  const startTime = Date.now();
-  const logger = resolveDebugOption(options.debug);
-  const providerName = adapter.provider ?? adapter.name ?? "unknown";
-  const mwCtx = createGenerationContext({
-    requestId,
-    activity: "transcription",
-    provider: adapter.name,
-    model,
-    modelOptions: rest.modelOptions,
-    createId
-  });
-  await runGenerationStart(middleware, mwCtx);
-  aiEventClient.emit("transcription:request:started", {
-    requestId,
-    provider: adapter.name,
-    model,
-    language: rest.language,
-    prompt: rest.prompt,
-    responseFormat: rest.responseFormat,
-    modelOptions: rest.modelOptions,
-    timestamp: startTime
-  });
-  logger.request(`activity=generateTranscription provider=${providerName}`, {
-    provider: providerName,
-    model
-  });
-  try {
-    const result = await adapter.transcribe({ ...rest, model, logger });
-    const duration = Date.now() - startTime;
-    aiEventClient.emit("transcription:request:completed", {
-      requestId,
-      provider: adapter.name,
-      model,
-      text: result.text,
-      language: result.language,
-      duration,
-      modelOptions: rest.modelOptions,
-      timestamp: Date.now()
-    });
-    logger.output(
-      `activity=generateTranscription length=${result.text.length}`,
-      { hasText: !!result.text }
-    );
-    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("transcription: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("generateTranscription activity failed", {
-      error,
-      source: "generateTranscription"
-    });
-    throw error;
-  }
+	const { adapter, stream: _stream, debug: _debug, middleware, threadId, runId, ...rest } = options;
+	const model = adapter.model;
+	const requestId = createId("transcription");
+	const startTime = Date.now();
+	const logger = resolveDebugOption(options.debug);
+	const providerName = adapter.provider ?? adapter.name ?? "unknown";
+	const mwCtx = createGenerationContext({
+		requestId,
+		activity: "transcription",
+		provider: adapter.name,
+		model,
+		modelOptions: rest.modelOptions,
+		artifactInputs: {
+			audio: rest.audio,
+			language: rest.language,
+			prompt: rest.prompt,
+			responseFormat: rest.responseFormat
+		},
+		threadId,
+		runId,
+		createId
+	});
+	await runGenerationStart(middleware, mwCtx);
+	aiEventClient.emit("transcription:request:started", {
+		requestId,
+		provider: adapter.name,
+		model,
+		language: rest.language,
+		prompt: rest.prompt,
+		responseFormat: rest.responseFormat,
+		modelOptions: rest.modelOptions,
+		timestamp: startTime
+	});
+	logger.request(`activity=generateTranscription provider=${providerName}`, {
+		provider: providerName,
+		model
+	});
+	try {
+		const result = await applyGenerationResultTransforms(mwCtx, await adapter.transcribe({
+			...rest,
+			model,
+			logger
+		}));
+		const duration = Date.now() - startTime;
+		aiEventClient.emit("transcription:request:completed", {
+			requestId,
+			provider: adapter.name,
+			model,
+			text: result.text,
+			language: result.language,
+			duration,
+			modelOptions: rest.modelOptions,
+			timestamp: Date.now()
+		});
+		logger.output(`activity=generateTranscription length=${result.text.length}`, { hasText: !!result.text });
+		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("transcription: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("generateTranscription activity failed", {
+			error,
+			source: "generateTranscription"
+		});
+		throw error;
+	}
 }
+/**
+* Create typed options for the generateTranscription() function without executing.
+*/
 function createTranscriptionOptions(options) {
-  return options;
+	return options;
 }
-export {
-  createTranscriptionOptions,
-  generateTranscription,
-  kind
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+export { createTranscriptionOptions, generateTranscription, kind };
+
+//# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateTranscription/index.ts"],"sourcesContent":["/**\n * Transcription Activity\n *\n * Transcribes audio to text using speech-to-text 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 { TranscriptionAdapter } from './adapter'\nimport type {\n  StreamChunk,\n  TranscriptionResponseFormat,\n  TranscriptionResult,\n} from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'transcription' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TranscriptionAdapter via ~types.\n */\nexport type TranscriptionProviderOptions<TAdapter> =\n  TAdapter extends TranscriptionAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the transcription activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The transcription adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TranscriptionActivityOptions<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n> {\n  /** The transcription adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: TranscriptionResponseFormat\n  /** Provider-specific options for transcription */\n  modelOptions?: TranscriptionProviderOptions<TAdapter>\n  /**\n   * Whether to stream the transcription result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TranscriptionResult>.\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 transcription activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TranscriptionResult>\n */\nexport type TranscriptionActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<TranscriptionResult>\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 * Transcription activity - converts audio to text.\n *\n * Uses AI speech-to-text models to transcribe audio content.\n *\n * @example Transcribe an audio file\n * ```ts\n * import { generateTranscription } from '@tanstack/ai'\n * import { openaiTranscription } from '@tanstack/ai-openai'\n *\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile, // File, Blob, or base64 string\n *   language: 'en'\n * })\n *\n * console.log(result.text)\n * ```\n *\n * @example With verbose output for timestamps\n * ```ts\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   responseFormat: 'verbose_json'\n * })\n *\n * result.segments?.forEach(segment => {\n *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)\n * })\n * ```\n *\n * @example Streaming transcription result\n * ```ts\n * for await (const chunk of generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   stream: true\n * })) {\n *   console.log(chunk)\n * }\n * ```\n */\nexport function generateTranscription<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateTranscription(options),\n    ) as TranscriptionActivityResult<TStream>\n  }\n\n  return runGenerateTranscription(\n    options,\n  ) as TranscriptionActivityResult<TStream>\n}\n\n/**\n * Run non-streaming transcription\n */\nasync function runGenerateTranscription<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n>(\n  options: TranscriptionActivityOptions<TAdapter, boolean>,\n): Promise<TranscriptionResult> {\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('transcription')\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: 'transcription',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('transcription:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    language: rest.language,\n    prompt: rest.prompt,\n    responseFormat: rest.responseFormat,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateTranscription provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.transcribe({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('transcription:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      text: result.text,\n      language: result.language,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    logger.output(\n      `activity=generateTranscription length=${result.text.length}`,\n      { hasText: !!result.text },\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('transcription: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('generateTranscription activity failed', {\n      error,\n      source: 'generateTranscription',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateTranscription() function without executing.\n */\nexport function createTranscriptionOptions<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  TranscriptionAdapter,\n  TranscriptionAdapterConfig,\n  AnyTranscriptionAdapter,\n} from './adapter'\nexport { BaseTranscriptionAdapter } from './adapter'\n"],"names":[],"mappings":";;;;AAgCO,MAAM,OAAO;AAgFpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAiDO,SAAS,sBAOd,SACsC;AACtC,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,yBAAyB,OAAO;AAAA,IAAA;AAAA,EAEpC;AAEA,SAAO;AAAA,IACL;AAAA,EAAA;AAEJ;AAKA,eAAe,yBAMb,SAC8B;AAC9B,QAAM;AAAA,IACJ;AAAA,IACA,QAAQ;AAAA,IACR,OAAO;AAAA,IACP;AAAA,IACA,GAAG;AAAA,EAAA,IACD;AACJ,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,eAAe;AAC1C,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,QAAM,QAAQ,wBAAwB;AAAA,IACpC;AAAA,IACA,UAAU;AAAA,IACV,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,cAAc,KAAK;AAAA,IACnB;AAAA,EAAA,CACD;AAED,QAAM,mBAAmB,YAAY,KAAK;AAE1C,gBAAc,KAAK,iCAAiC;AAAA,IAClD;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,UAAU,KAAK;AAAA,IACf,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,2CAA2C,YAAY,IAAI;AAAA,IACxE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,WAAW,EAAE,GAAG,MAAM,OAAO,QAAQ;AAClE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,mCAAmC;AAAA,MACpD;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,MAAM,OAAO;AAAA,MACb,UAAU,OAAO;AAAA,MACjB;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO;AAAA,MACL,yCAAyC,OAAO,KAAK,MAAM;AAAA,MAC3D,EAAE,SAAS,CAAC,CAAC,OAAO,KAAA;AAAA,IAAK;AAG3B,QAAI,OAAO,MAAO,OAAM,mBAAmB,YAAY,OAAO,OAAO,KAAK;AAC1E,UAAM,oBAAoB,YAAY,OAAO;AAAA,MAC3C;AAAA,MACA,OAAO,OAAO;AAAA,IAAA,CACf;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,WAAW,KAAK,IAAA,IAAQ;AAC9B,UAAM,MAAM;AACZ,kBAAc,KAAK,+BAA+B;AAAA,MAChD;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,UAAM,mBAAmB,YAAY,OAAO;AAAA,MAC1C;AAAA,MACA;AAAA,IAAA,CACD;AACD,WAAO,OAAO,yCAAyC;AAAA,MACrD;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,2BAOd,SACiD;AACjD,SAAO;AACT;"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/activities/generateTranscription/index.ts"],"sourcesContent":["/**\n * Transcription Activity\n *\n * Transcribes audio to text using speech-to-text 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 { TranscriptionAdapter } from './adapter'\nimport type {\n  StreamChunk,\n  TranscriptionResponseFormat,\n  TranscriptionResult,\n} from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'transcription' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TranscriptionAdapter via ~types.\n */\nexport type TranscriptionProviderOptions<TAdapter> =\n  TAdapter extends TranscriptionAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the transcription activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The transcription adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TranscriptionActivityOptions<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n> {\n  /** The transcription adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: TranscriptionResponseFormat\n  /** Provider-specific options for transcription */\n  modelOptions?: TranscriptionProviderOptions<TAdapter>\n  /**\n   * Whether to stream the transcription result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TranscriptionResult>.\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 transcription activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TranscriptionResult>\n */\nexport type TranscriptionActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<TranscriptionResult>\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 * Transcription activity - converts audio to text.\n *\n * Uses AI speech-to-text models to transcribe audio content.\n *\n * @example Transcribe an audio file\n * ```ts\n * import { generateTranscription } from '@tanstack/ai'\n * import { openaiTranscription } from '@tanstack/ai-openai'\n *\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile, // File, Blob, or base64 string\n *   language: 'en'\n * })\n *\n * console.log(result.text)\n * ```\n *\n * @example With verbose output for timestamps\n * ```ts\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   responseFormat: 'verbose_json'\n * })\n *\n * result.segments?.forEach(segment => {\n *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)\n * })\n * ```\n *\n * @example Streaming transcription result\n * ```ts\n * for await (const chunk of generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   stream: true\n * })) {\n *   console.log(chunk)\n * }\n * ```\n */\nexport function generateTranscription<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityResult<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) =>\n        runGenerateTranscription({ ...options, runId: resolved.runId }),\n      options,\n    ) as TranscriptionActivityResult<TStream>\n  }\n\n  return runGenerateTranscription(\n    options,\n  ) as TranscriptionActivityResult<TStream>\n}\n\n/**\n * Run non-streaming transcription\n */\nasync function runGenerateTranscription<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n>(\n  options: TranscriptionActivityOptions<TAdapter, boolean>,\n): Promise<TranscriptionResult> {\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('transcription')\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: 'transcription',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    artifactInputs: {\n      audio: rest.audio,\n      language: rest.language,\n      prompt: rest.prompt,\n      responseFormat: rest.responseFormat,\n    },\n    threadId,\n    runId,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('transcription:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    language: rest.language,\n    prompt: rest.prompt,\n    responseFormat: rest.responseFormat,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateTranscription provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const rawResult = await adapter.transcribe({ ...rest, model, logger })\n    const result = await applyGenerationResultTransforms(mwCtx, rawResult)\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('transcription:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      text: result.text,\n      language: result.language,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    logger.output(\n      `activity=generateTranscription length=${result.text.length}`,\n      { hasText: !!result.text },\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('transcription: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('generateTranscription activity failed', {\n      error,\n      source: 'generateTranscription',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateTranscription() function without executing.\n */\nexport function createTranscriptionOptions<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  TranscriptionAdapter,\n  TranscriptionAdapterConfig,\n  AnyTranscriptionAdapter,\n} from './adapter'\nexport { BaseTranscriptionAdapter } from './adapter'\n"],"mappings":";;;;;;;;;;;;;AAiCA,IAAa,OAAO;AAoFpB,SAAS,SAAS,QAAwB;CACxC,OAAO,GAAG,OAAO,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC;AACzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,SAAgB,sBAOd,SACsC;CACtC,IAAI,QAAQ,QACV,OAAO,wBAMJ,aACC,yBAAyB;EAAE,GAAG;EAAS,OAAO,SAAS;CAAM,CAAC,GAChE,OACF;CAGF,OAAO,yBACL,OACF;AACF;;;;AAKA,eAAe,yBAMb,SAC8B;CAC9B,MAAM,EACJ,SACA,QAAQ,SACR,OAAO,QACP,YACA,UACA,OACA,GAAG,SACD;CACJ,MAAM,QAAQ,QAAQ;CACtB,MAAM,YAAY,SAAS,eAAe;CAC1C,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,OAAO,KAAK;GACZ,UAAU,KAAK;GACf,QAAQ,KAAK;GACb,gBAAgB,KAAK;EACvB;EACA;EACA;EACA;CACF,CAAC;CAED,MAAM,mBAAmB,YAAY,KAAK;CAE1C,cAAc,KAAK,iCAAiC;EAClD;EACA,UAAU,QAAQ;EAClB;EACA,UAAU,KAAK;EACf,QAAQ,KAAK;EACb,gBAAgB,KAAK;EACrB,cAAc,KAAK;EACnB,WAAW;CACb,CAAC;CAED,OAAO,QAAQ,2CAA2C,gBAAgB;EACxE,UAAU;EACV;CACF,CAAC;CAED,IAAI;EAEF,MAAM,SAAS,MAAM,gCAAgC,OAAO,MADpC,QAAQ,WAAW;GAAE,GAAG;GAAM;GAAO;EAAO,CAAC,CACA;EACrE,MAAM,WAAW,KAAK,IAAI,IAAI;EAE9B,cAAc,KAAK,mCAAmC;GACpD;GACA,UAAU,QAAQ;GAClB;GACA,MAAM,OAAO;GACb,UAAU,OAAO;GACjB;GACA,cAAc,KAAK;GACnB,WAAW,KAAK,IAAI;EACtB,CAAC;EAED,OAAO,OACL,yCAAyC,OAAO,KAAK,UACrD,EAAE,SAAS,CAAC,CAAC,OAAO,KAAK,CAC3B;EAEA,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,+BAA+B;GAChD;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,yCAAyC;GACrD;GACA,QAAQ;EACV,CAAC;EACD,MAAM;CACR;AACF;;;;AASA,SAAgB,2BAOd,SACiD;CACjD,OAAO;AACT"}

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

@@ -1,30 +1,37 @@
-class BaseVideoAdapter {
-  kind = "video";
-  model;
-  config;
-  constructor(config = {}, model) {
-    this.config = config;
-    this.model = model;
-  }
-  /**
-   * Default implementation returns `{ kind: 'none' }`. Adapters that have
-   * declared their per-model duration map should override this.
-   */
-  availableDurations() {
-    return { kind: "none" };
-  }
-  /**
-   * Default implementation returns `undefined`. Adapters that have declared
-   * their per-model duration map should override.
-   */
-  snapDuration(_seconds) {
-    return void 0;
-  }
-  generateId() {
-    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-  }
-}
-export {
-  BaseVideoAdapter
+//#region src/activities/generateVideo/adapter.ts
+/**
+* Abstract base class for video generation adapters.
+* Extend this class to implement a video adapter for a specific provider.
+*
+* @experimental Video generation is an experimental feature and may change.
+*
+* Generic parameters match VideoAdapter - all pre-resolved by the provider function.
+*/
+var BaseVideoAdapter = class {
+	kind = "video";
+	model;
+	config;
+	constructor(config = {}, model) {
+		this.config = config;
+		this.model = model;
+	}
+	/**
+	* Default implementation returns `{ kind: 'none' }`. Adapters that have
+	* declared their per-model duration map should override this.
+	*/
+	availableDurations() {
+		return { kind: "none" };
+	}
+	/**
+	* Default implementation returns `undefined`. Adapters that have declared
+	* their per-model duration map should override.
+	*/
+	snapDuration(_seconds) {}
+	generateId() {
+		return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+	}
 };
-//# sourceMappingURL=adapter.js.map
+//#endregion
+export { BaseVideoAdapter };
+
+//# sourceMappingURL=adapter.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sources":["../../../../src/activities/generateVideo/adapter.ts"],"sourcesContent":["import type {\n  ModelInputModalitiesByName,\n  VideoGenerationOptions,\n  VideoJobResult,\n  VideoStatusResult,\n  VideoUrlResult,\n} from '../../types'\n\n/**\n * Structured description of the durations a video model accepts.\n *\n * Tagged union so the same shape can express discrete enums (OpenAI Sora,\n * Veo), continuous ranges, mixed shapes, and models with no duration field.\n * Consumed by `VideoAdapter.availableDurations()`.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type DurationOptions<T extends string | number | undefined> =\n  | { kind: 'discrete'; values: ReadonlyArray<NonNullable<T>> }\n  | { kind: 'range'; min: number; max: number; step?: number; unit: 'seconds' }\n  | {\n      kind: 'mixed'\n      values: ReadonlyArray<NonNullable<T>>\n      range?: { min: number; max: number; step?: number }\n    }\n  | { kind: 'none' }\n\n/**\n * Configuration for video adapter instances\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport interface VideoAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Video 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 * @experimental Video generation is an experimental feature and may change.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'sora-2')\n * - TProviderOptions: Provider-specific options (already resolved)\n * - TModelProviderOptionsByName: Map from model name to its specific provider options\n * - TModelSizeByName: Map from model name to its supported sizes\n * - TModelInputModalitiesByName: Map from model name to the non-text prompt\n *   modalities it accepts (constrains the `prompt` part types at compile time)\n * - TModelDurationByName: Map from model name to its supported duration\n *   union. Defaults to `Record<string, number>` so adapters that haven't\n *   declared a map keep today's `duration?: number` typing.\n */\nexport interface VideoAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n  TModelInputModalitiesByName extends ModelInputModalitiesByName =\n    ModelInputModalitiesByName,\n  TModelDurationByName extends Record<string, string | number | undefined> =\n    Record<string, number>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'video'\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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n    modelInputModalitiesByName: TModelInputModalitiesByName\n    modelDurationByName: TModelDurationByName\n  }\n\n  /**\n   * Create a new video generation job.\n   * Returns a job ID that can be used to poll for status and retrieve the video.\n   */\n  createVideoJob: (\n    options: VideoGenerationOptions<\n      TProviderOptions,\n      TModelSizeByName[TModel],\n      TModelDurationByName[TModel]\n    >,\n  ) => Promise<VideoJobResult>\n\n  /**\n   * Get the current status of a video generation job.\n   */\n  getVideoStatus: (jobId: string) => Promise<VideoStatusResult>\n\n  /**\n   * Get the URL to download/view the generated video.\n   * Should only be called after status is 'completed'.\n   */\n  getVideoUrl: (jobId: string) => Promise<VideoUrlResult>\n\n  /**\n   * Describe the durations this adapter's model accepts. Returns a tagged\n   * union so consumers can render UI / coerce input without provider-specific\n   * knowledge.\n   */\n  availableDurations: () => DurationOptions<TModelDurationByName[TModel]>\n\n  /**\n   * Coerce a raw seconds value to the closest valid duration for this model.\n   * Returns `undefined` for models with no duration field.\n   */\n  snapDuration: (seconds: number) => TModelDurationByName[TModel] | undefined\n}\n\n/**\n * A VideoAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyVideoAdapter = VideoAdapter<any, any, any, any, any, any>\n\n/**\n * Abstract base class for video generation adapters.\n * Extend this class to implement a video adapter for a specific provider.\n *\n * @experimental Video generation is an experimental feature and may change.\n *\n * Generic parameters match VideoAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseVideoAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n  TModelInputModalitiesByName extends ModelInputModalitiesByName =\n    ModelInputModalitiesByName,\n  TModelDurationByName extends Record<string, string | number | undefined> =\n    Record<string, number>,\n> implements VideoAdapter<\n  TModel,\n  TProviderOptions,\n  TModelProviderOptionsByName,\n  TModelSizeByName,\n  TModelInputModalitiesByName,\n  TModelDurationByName\n> {\n  readonly kind = 'video' 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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n    modelInputModalitiesByName: TModelInputModalitiesByName\n    modelDurationByName: TModelDurationByName\n  }\n\n  protected config: VideoAdapterConfig\n\n  constructor(config: VideoAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract createVideoJob(\n    options: VideoGenerationOptions<\n      TProviderOptions,\n      TModelSizeByName[TModel],\n      TModelDurationByName[TModel]\n    >,\n  ): Promise<VideoJobResult>\n\n  abstract getVideoStatus(jobId: string): Promise<VideoStatusResult>\n\n  abstract getVideoUrl(jobId: string): Promise<VideoUrlResult>\n\n  /**\n   * Default implementation returns `{ kind: 'none' }`. Adapters that have\n   * declared their per-model duration map should override this.\n   */\n  availableDurations(): DurationOptions<TModelDurationByName[TModel]> {\n    return { kind: 'none' }\n  }\n\n  /**\n   * Default implementation returns `undefined`. Adapters that have declared\n   * their per-model duration map should override.\n   */\n  snapDuration(_seconds: number): TModelDurationByName[TModel] | undefined {\n    return undefined\n  }\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AA6IO,MAAe,iBAmBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAWC;AAAA,EAEV,YAAY,SAA6B,CAAA,GAAI,OAAe;AAC1D,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,qBAAoE;AAClE,WAAO,EAAE,MAAM,OAAA;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,aAAa,UAA4D;AACvE,WAAO;AAAA,EACT;AAAA,EAEU,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/generateVideo/adapter.ts"],"sourcesContent":["import type {\n  ModelInputModalitiesByName,\n  VideoGenerationOptions,\n  VideoJobResult,\n  VideoStatusResult,\n  VideoUrlResult,\n} from '../../types'\n\n/**\n * Structured description of the durations a video model accepts.\n *\n * Tagged union so the same shape can express discrete enums (OpenAI Sora,\n * Veo), continuous ranges, mixed shapes, and models with no duration field.\n * Consumed by `VideoAdapter.availableDurations()`.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type DurationOptions<T extends string | number | undefined> =\n  | { kind: 'discrete'; values: ReadonlyArray<NonNullable<T>> }\n  | { kind: 'range'; min: number; max: number; step?: number; unit: 'seconds' }\n  | {\n      kind: 'mixed'\n      values: ReadonlyArray<NonNullable<T>>\n      range?: { min: number; max: number; step?: number }\n    }\n  | { kind: 'none' }\n\n/**\n * Configuration for video adapter instances\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport interface VideoAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Video 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 * @experimental Video generation is an experimental feature and may change.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'sora-2')\n * - TProviderOptions: Provider-specific options (already resolved)\n * - TModelProviderOptionsByName: Map from model name to its specific provider options\n * - TModelSizeByName: Map from model name to its supported sizes\n * - TModelInputModalitiesByName: Map from model name to the non-text prompt\n *   modalities it accepts (constrains the `prompt` part types at compile time)\n * - TModelDurationByName: Map from model name to its supported duration\n *   union. Defaults to `Record<string, number>` so adapters that haven't\n *   declared a map keep today's `duration?: number` typing.\n */\nexport interface VideoAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n  TModelInputModalitiesByName extends ModelInputModalitiesByName =\n    ModelInputModalitiesByName,\n  TModelDurationByName extends Record<string, string | number | undefined> =\n    Record<string, number>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'video'\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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n    modelInputModalitiesByName: TModelInputModalitiesByName\n    modelDurationByName: TModelDurationByName\n  }\n\n  /**\n   * Create a new video generation job.\n   * Returns a job ID that can be used to poll for status and retrieve the video.\n   */\n  createVideoJob: (\n    options: VideoGenerationOptions<\n      TProviderOptions,\n      TModelSizeByName[TModel],\n      TModelDurationByName[TModel]\n    >,\n  ) => Promise<VideoJobResult>\n\n  /**\n   * Get the current status of a video generation job.\n   */\n  getVideoStatus: (jobId: string) => Promise<VideoStatusResult>\n\n  /**\n   * Get the URL to download/view the generated video.\n   * Should only be called after status is 'completed'.\n   */\n  getVideoUrl: (jobId: string) => Promise<VideoUrlResult>\n\n  /**\n   * Describe the durations this adapter's model accepts. Returns a tagged\n   * union so consumers can render UI / coerce input without provider-specific\n   * knowledge.\n   */\n  availableDurations: () => DurationOptions<TModelDurationByName[TModel]>\n\n  /**\n   * Coerce a raw seconds value to the closest valid duration for this model.\n   * Returns `undefined` for models with no duration field.\n   */\n  snapDuration: (seconds: number) => TModelDurationByName[TModel] | undefined\n}\n\n/**\n * A VideoAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyVideoAdapter = VideoAdapter<any, any, any, any, any, any>\n\n/**\n * Abstract base class for video generation adapters.\n * Extend this class to implement a video adapter for a specific provider.\n *\n * @experimental Video generation is an experimental feature and may change.\n *\n * Generic parameters match VideoAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseVideoAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n  TModelInputModalitiesByName extends ModelInputModalitiesByName =\n    ModelInputModalitiesByName,\n  TModelDurationByName extends Record<string, string | number | undefined> =\n    Record<string, number>,\n> implements VideoAdapter<\n  TModel,\n  TProviderOptions,\n  TModelProviderOptionsByName,\n  TModelSizeByName,\n  TModelInputModalitiesByName,\n  TModelDurationByName\n> {\n  readonly kind = 'video' 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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n    modelInputModalitiesByName: TModelInputModalitiesByName\n    modelDurationByName: TModelDurationByName\n  }\n\n  protected config: VideoAdapterConfig\n\n  constructor(config: VideoAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract createVideoJob(\n    options: VideoGenerationOptions<\n      TProviderOptions,\n      TModelSizeByName[TModel],\n      TModelDurationByName[TModel]\n    >,\n  ): Promise<VideoJobResult>\n\n  abstract getVideoStatus(jobId: string): Promise<VideoStatusResult>\n\n  abstract getVideoUrl(jobId: string): Promise<VideoUrlResult>\n\n  /**\n   * Default implementation returns `{ kind: 'none' }`. Adapters that have\n   * declared their per-model duration map should override this.\n   */\n  availableDurations(): DurationOptions<TModelDurationByName[TModel]> {\n    return { kind: 'none' }\n  }\n\n  /**\n   * Default implementation returns `undefined`. Adapters that have declared\n   * their per-model duration map should override.\n   */\n  snapDuration(_seconds: number): TModelDurationByName[TModel] | undefined {\n    return undefined\n  }\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;;;AA6IA,IAAsB,mBAAtB,MAmBE;CACA,OAAgB;CAEhB;CAWA;CAEA,YAAY,SAA6B,CAAC,GAAG,OAAe;EAC1D,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;;;;;CAkBA,qBAAoE;EAClE,OAAO,EAAE,MAAM,OAAO;CACxB;;;;;CAMA,aAAa,UAA4D,CAEzE;CAEA,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/generateVideo/index.d.ts

@@ -1,7 +1,7 @@
 import { DebugOption } from '../../logger/types.js';
 import { GenerationMiddleware } from '../middleware/types.js';
 import { VideoAdapter } from './adapter.js';
-import { MediaPrompt, MediaPromptFor, StreamChunk, TokenUsage, VideoJobResult, VideoStatusResult, VideoUrlResult } from '../../types.js';
+import { MediaPrompt, MediaPromptFor, PersistedArtifactRef, StreamChunk, TokenUsage, VideoJobResult, VideoStatusResult, VideoUrlResult } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "video";
 /**
@@ -79,8 +79,28 @@ export type VideoCreateOptions<TAdapter extends VideoAdapter<string, any, any, a
     pollingInterval?: number;
     /** Maximum time to wait before timing out in milliseconds (stream mode only). @default 600000 */
     maxDuration?: number;
-    /** Custom run ID (stream mode only) */
+    /**
+     * Custom run id (stream mode only) — the id stamped on the emitted
+     * `RUN_STARTED` / `RUN_FINISHED` chunks.
+     *
+     * IGNORED by a non-streaming submit. That run spans two calls, and its id is
+     * derived from the provider's job instead, so {@link getVideoJobStatus} can
+     * recompute it from the `jobId` you already have to poll with. Honoring a
+     * custom id here would reintroduce the failure this avoids: a caller who set
+     * it on the submit and forgot it on the poll would silently open a second
+     * record while the first sat unfinished forever.
+     */
     runId?: string;
+    /**
+     * Stable conversation/thread id for correlating this run when persisted.
+     *
+     * Also the `threadId` stamped on the emitted `RUN_STARTED` / `RUN_FINISHED`
+     * chunks; when omitted a throwaway id is minted for those chunks only, and
+     * the persisted run record carries NO thread link rather than a fabricated
+     * one. Pass it whenever persistence is on — it is the slot a reloading client
+     * hydrates by, so a run stored without it can only be fetched by run id.
+     */
+    threadId?: string;
     /**
      * Enable debug logging. Pass `true` to enable all categories, `false` to
      * silence everything including errors, or a `DebugConfig` object for granular
@@ -89,10 +109,29 @@ export type VideoCreateOptions<TAdapter extends VideoAdapter<string, any, any, a
     debug?: DebugOption;
     /**
      * Observe-only middleware notified on start, usage, success, and error. Pass
-     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
-     * `GenerationMiddleware` contract for a custom backend. In streaming mode the
-     * span covers the full create→poll→complete lifecycle; in non-streaming mode
-     * it covers job submission. An abandoned stream fires `onAbort`.
+     * `otelMiddleware()` to emit OpenTelemetry spans, `withGenerationPersistence()`
+     * to persist the run, or implement the `GenerationMiddleware` contract for a
+     * custom backend.
+     *
+     * In streaming mode one run covers the full create→poll→complete lifecycle:
+     * `onStart` at submission, a terminal `onFinish`/`onError` when the job
+     * settles, and `onAbort` if the consumer abandons the stream.
+     *
+     * In NON-streaming mode the call only SUBMITS the job, so it only opens the
+     * run: no terminal hook fires here, because the video does not exist yet.
+     * Pass the same `middleware` and `threadId` to {@link getVideoJobStatus}; the
+     * poll that observes a terminal job state finishes the run and is where the
+     * result and its artifacts are recorded. Nothing else has to be threaded
+     * through — both calls derive the run id from the provider's `jobId`, the one
+     * id a poller cannot be missing.
+     *
+     * Because the job id only exists once the provider accepts the job, `onStart`
+     * fires AFTER the submit request rather than before it — an observer's span
+     * therefore covers the run from acceptance onward, not the submit round-trip.
+     * A submission that FAILS has no job to key on, so it opens and immediately
+     * fails a run under this call's `requestId`: the thread's latest run reports
+     * the failure (a client hydrating the slot sees it) even though there is no
+     * job to resume.
      */
     middleware?: Array<GenerationMiddleware>;
 } & ({} extends VideoProviderOptions<TAdapter> ? {
@@ -150,7 +189,7 @@ export type VideoActivityResult<TRequest extends 'create' | 'status' | 'url' = '
  *
  * @example Create a video generation job
  * ```ts
- * import { generateVideo } from '@tanstack/ai'
+ * import { generateVideo, getVideoJobStatus } from '@tanstack/ai'
  * import { openaiVideo } from '@tanstack/ai-openai'
  *
  * // Start a video generation job
@@ -160,6 +199,14 @@ export type VideoActivityResult<TRequest extends 'create' | 'status' | 'url' = '
  * })
  *
  * console.log('Job started:', jobId)
+ *
+ * // The submission only OPENS the run; the poll that sees a terminal state is
+ * // what completes it. The `jobId` is the whole correlation — pass the same
+ * // `middleware` and `threadId` when you use them.
+ * const status = await getVideoJobStatus({
+ *   adapter: openaiVideo('sora-2'),
+ *   jobId,
+ * })
  * ```
  *
  * @example Stream the full video generation lifecycle
@@ -178,12 +225,71 @@ export type VideoActivityResult<TRequest extends 'create' | 'status' | 'url' = '
  * ```
  */
 export declare function generateVideo<TAdapter extends VideoAdapter<string, any, any, any, any, any>, TStream extends boolean = false>(options: VideoCreateOptions<TAdapter, TStream>): VideoActivityResult<'create', TStream>;
+/**
+ * Options for {@link getVideoJobStatus}.
+ *
+ * The run this poll finishes is identified by `adapter` + `jobId` alone — the
+ * same pair the submitting `generateVideo()` call derived it from — so there is
+ * no run id to thread through. Pass the submission's `threadId` and the same
+ * `middleware`.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoJobStatusOptions<TAdapter extends VideoAdapter<string, any, any, any, any, any>> {
+    /** The video adapter to use (must be created with a model) */
+    adapter: TAdapter & {
+        kind: typeof kind;
+    };
+    /** The job ID to check status for */
+    jobId: string;
+    /**
+     * The scope the run is filed under. Must match the submission's `threadId` —
+     * generation persistence REFUSES a run without a scope (a run filed under
+     * none can never be hydrated by one), so omitting it throws rather than
+     * quietly filing the finished video somewhere unreachable.
+     */
+    threadId?: string;
+    /**
+     * Observe-only middleware. Hooks fire ONLY on the poll that observes a
+     * terminal job state: `onStart` (resuming the submission's run), then the
+     * result transforms — which is where persistence copies the video into a blob
+     * store and rewrites `url` to a durable one, so the returned result carries
+     * the same urls as the stored record — then `onFinish`, or `onError` when the
+     * job failed. Intermediate polls invoke nothing, so a middleware is not
+     * charged for the wait.
+     */
+    middleware?: Array<GenerationMiddleware>;
+}
+/**
+ * The status of a video job, plus the video itself once the job completed.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoJobStatusResult {
+    /** Job identifier */
+    jobId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    progress?: number;
+    url?: string;
+    /** When the provider url expires, if it reported one. */
+    expiresAt?: Date;
+    error?: string;
+    usage?: TokenUsage;
+    /** Durable artifact references, when generation persistence is wired. */
+    artifacts?: Array<PersistedArtifactRef>;
+}
 /**
  * Get video job status - returns the current status, progress, and URL if available.
  *
  * This function combines status checking and URL retrieval. If the job is completed,
  * it will automatically fetch and include the video URL.
  *
+ * It is also where a non-streaming `generateVideo()` run ENDS: pass the same
+ * `middleware` and `threadId`, and the poll that first sees a terminal job state
+ * finishes the run (recording the result and its artifacts) or fails it. The run
+ * is identified by `adapter` + `jobId`, exactly what the submission derived it
+ * from, so there is nothing else to carry between the two calls.
+ *
  * @experimental Video generation is an experimental feature and may change.
  *
  * @example Check job status
@@ -202,19 +308,37 @@ export declare function generateVideo<TAdapter extends VideoAdapter<string, any,
  *   console.log('Video URL:', result.url)
  * }
  * ```
+ *
+ * @example Submit and poll one persisted run
+ * ```ts
+ * import { generateVideo, getVideoJobStatus } from '@tanstack/ai'
+ * import { withGenerationPersistence } from '@tanstack/ai-persistence'
+ * import { openaiVideo } from '@tanstack/ai-openai'
+ *
+ * const adapter = openaiVideo('sora-2')
+ * const middleware = [withGenerationPersistence(persistence)]
+ *
+ * // Opens the run (status `running`, jobId recorded). Its run id is derived
+ * // from the provider job, so nothing has to be stored to resume it.
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: 'A cat chasing a dog in a sunny park',
+ *   threadId,
+ *   middleware,
+ * })
+ *
+ * // Completes the SAME run once the job settles — this is what writes the
+ * // video, its artifacts, and the terminal status. Works from a different
+ * // request or process: the jobId is the only correlation.
+ * const status = await getVideoJobStatus({
+ *   adapter,
+ *   jobId,
+ *   threadId,
+ *   middleware,
+ * })
+ * ```
  */
-export declare function getVideoJobStatus<TAdapter extends VideoAdapter<string, any, any, any, any, any>>(options: {
-    adapter: TAdapter & {
-        kind: typeof kind;
-    };
-    jobId: string;
-}): Promise<{
-    status: 'pending' | 'processing' | 'completed' | 'failed';
-    progress?: number;
-    url?: string;
-    error?: string;
-    usage?: TokenUsage;
-}>;
+export declare function getVideoJobStatus<TAdapter extends VideoAdapter<string, any, any, any, any, any>>(options: VideoJobStatusOptions<TAdapter>): Promise<VideoJobStatusResult>;
 /**
  * Create typed options for the generateVideo() function without executing.
  */