@tanstack/ai 0.6.2 → 0.6.3

package/src/activities/generateVideo/index.ts

@@ -10,6 +10,7 @@
 import { aiEventClient } from '../../event-client.js'
 import type { VideoAdapter } from './adapter'
 import type {
+  StreamChunk,
   VideoJobResult,
   VideoStatusResult,
   VideoUrlResult,
@@ -67,10 +68,14 @@ interface VideoActivityBaseOptions<
  * Options for creating a new video generation job.
  * The model is extracted from the adapter's model property.
  *
+ * @template TAdapter - The video adapter type
+ * @template TStream - Whether to stream the output
+ *
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoCreateOptions<
   TAdapter extends VideoAdapter<string, any, any, any>,
+  TStream extends boolean = false,
 > = VideoActivityBaseOptions<TAdapter> & {
   /** Request type - create a new job (default if not specified) */
   request?: 'create'
@@ -80,6 +85,21 @@ export type VideoCreateOptions<
   size?: VideoSizeForAdapter<TAdapter>
   /** Video duration in seconds */
   duration?: number
+  /**
+   * Whether to stream the video generation lifecycle.
+   * When true, returns an AsyncIterable<StreamChunk> that handles the full
+   * job lifecycle: create job, poll for status, yield updates, and yield final result.
+   * When false or not provided, returns a Promise<VideoJobResult>.
+   *
+   * @default false
+   */
+  stream?: TStream
+  /** Polling interval in milliseconds (stream mode only). @default 2000 */
+  pollingInterval?: number
+  /** Maximum time to wait before timing out in milliseconds (stream mode only). @default 600000 */
+  maxDuration?: number
+  /** Custom run ID (stream mode only) */
+  runId?: string
 } & ({} extends VideoProviderOptions<TAdapter>
     ? {
         /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>
@@ -125,28 +145,34 @@ export interface VideoUrlOptions<
 export type VideoActivityOptions<
   TAdapter extends VideoAdapter<string, any, any, any>,
   TRequest extends 'create' | 'status' | 'url' = 'create',
+  TStream extends boolean = false,
 > = TRequest extends 'status'
   ? VideoStatusOptions<TAdapter>
   : TRequest extends 'url'
     ? VideoUrlOptions<TAdapter>
-    : VideoCreateOptions<TAdapter>
+    : VideoCreateOptions<TAdapter, TStream>
 
 // ===========================
 // Activity Result Types
 // ===========================
 
 /**
- * Result type for the video activity, based on request type.
+ * Result type for the video activity, based on request type and streaming.
+ * - If stream is true (create request): AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<VideoJobResult | VideoStatusResult | VideoUrlResult>
  *
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoActivityResult<
   TRequest extends 'create' | 'status' | 'url' = 'create',
+  TStream extends boolean = false,
 > = TRequest extends 'status'
   ? Promise<VideoStatusResult>
   : TRequest extends 'url'
     ? Promise<VideoUrlResult>
-    : Promise<VideoJobResult>
+    : TStream extends true
+      ? AsyncIterable<StreamChunk>
+      : Promise<VideoJobResult>
 
 // ===========================
 // Activity Implementation
@@ -158,6 +184,9 @@ export type VideoActivityResult<
  * Uses AI video generation models to create videos based on natural language descriptions.
  * Unlike image generation, video generation is asynchronous and requires polling for completion.
  *
+ * When `stream: true` is passed, handles the full job lifecycle automatically:
+ * create job → poll for status → stream updates → yield final result.
+ *
  * @experimental Video generation is an experimental feature and may change.
  *
  * @example Create a video generation job
@@ -173,10 +202,43 @@ export type VideoActivityResult<
  *
  * console.log('Job started:', jobId)
  * ```
+ *
+ * @example Stream the full video generation lifecycle
+ * ```ts
+ * import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
+ * import { openaiVideo } from '@tanstack/ai-openai'
+ *
+ * const stream = generateVideo({
+ *   adapter: openaiVideo('sora-2'),
+ *   prompt: 'A cat chasing a dog in a sunny park',
+ *   stream: true,
+ *   pollingInterval: 3000,
+ * })
+ *
+ * return toServerSentEventsResponse(stream)
+ * ```
+ */
+export function generateVideo<
+  TAdapter extends VideoAdapter<string, any, any, any>,
+  TStream extends boolean = false,
+>(
+  options: VideoCreateOptions<TAdapter, TStream>,
+): VideoActivityResult<'create', TStream> {
+  if (options.stream) {
+    return runStreamingVideoGeneration(
+      options as VideoCreateOptions<TAdapter, true>,
+    ) as VideoActivityResult<'create', TStream>
+  }
+
+  return runCreateVideoJob(options) as VideoActivityResult<'create', TStream>
+}
+
+/**
+ * Internal implementation of non-streaming video job creation.
  */
-export async function generateVideo<
+async function runCreateVideoJob<
   TAdapter extends VideoAdapter<string, any, any, any>,
->(options: VideoCreateOptions<TAdapter>): Promise<VideoJobResult> {
+>(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
   const { adapter, prompt, size, duration, modelOptions } = options
   const model = adapter.model
 
@@ -189,6 +251,108 @@ export async function generateVideo<
   })
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Internal streaming implementation for video generation.
+ * Handles the full job lifecycle: create job → poll for status → stream updates → yield final result.
+ */
+async function* runStreamingVideoGeneration<
+  TAdapter extends VideoAdapter<string, any, any, any>,
+>(options: VideoCreateOptions<TAdapter, true>): AsyncIterable<StreamChunk> {
+  const { adapter, prompt, size, duration, modelOptions } = options
+  const model = adapter.model
+  const runId = options.runId ?? createId('run')
+  const pollingInterval = options.pollingInterval ?? 2000
+  const maxDuration = options.maxDuration ?? 600_000
+
+  yield {
+    type: 'RUN_STARTED',
+    runId,
+    timestamp: Date.now(),
+  }
+
+  try {
+    // Create the video generation job
+    const jobResult = await adapter.createVideoJob({
+      model,
+      prompt,
+      size,
+      duration,
+      modelOptions,
+    })
+
+    yield {
+      type: 'CUSTOM',
+      name: 'video:job:created',
+      value: { jobId: jobResult.jobId },
+      timestamp: Date.now(),
+    }
+
+    // Poll for completion
+    const startTime = Date.now()
+    while (Date.now() - startTime < maxDuration) {
+      await sleep(pollingInterval)
+
+      const statusResult = await adapter.getVideoStatus(jobResult.jobId)
+
+      yield {
+        type: 'CUSTOM',
+        name: 'video:status',
+        value: {
+          jobId: jobResult.jobId,
+          status: statusResult.status,
+          progress: statusResult.progress,
+          error: statusResult.error,
+        },
+        timestamp: Date.now(),
+      }
+
+      if (statusResult.status === 'completed') {
+        const urlResult = await adapter.getVideoUrl(jobResult.jobId)
+
+        yield {
+          type: 'CUSTOM',
+          name: 'generation:result',
+          value: {
+            jobId: jobResult.jobId,
+            status: 'completed',
+            url: urlResult.url,
+            expiresAt: urlResult.expiresAt,
+          },
+          timestamp: Date.now(),
+        }
+
+        yield {
+          type: 'RUN_FINISHED',
+          runId,
+          finishReason: 'stop',
+          timestamp: Date.now(),
+        }
+        return
+      }
+
+      if (statusResult.status === 'failed') {
+        throw new Error(statusResult.error || 'Video generation failed')
+      }
+    }
+
+    throw new Error('Video generation timed out')
+  } catch (error: any) {
+    yield {
+      type: 'RUN_ERROR',
+      runId,
+      error: {
+        message: error.message || 'Video generation failed',
+        code: error.code,
+      },
+      timestamp: Date.now(),
+    }
+  }
+}
+
 /**
  * Get video job status - returns the current status, progress, and URL if available.
  *
@@ -316,7 +480,10 @@ export async function getVideoJobStatus<
  */
 export function createVideoOptions<
   TAdapter extends VideoAdapter<string, any, any, any>,
->(options: VideoCreateOptions<TAdapter>): VideoCreateOptions<TAdapter> {
+  TStream extends boolean = false,
+>(
+  options: VideoCreateOptions<TAdapter, TStream>,
+): VideoCreateOptions<TAdapter, TStream> {
   return options
 }
 

package/src/activities/stream-generation-result.ts

@@ -0,0 +1,62 @@
+/**
+ * Internal helper for wrapping one-shot generation results as StreamChunk
+ * async iterables. NOT exported from the package — used only by activity
+ * implementations to support `stream: true`.
+ */
+
+import type { StreamChunk } from '../types'
+
+function createId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+/**
+ * Wrap a one-shot generation result as a StreamChunk async iterable.
+ *
+ * This allows non-streaming activities (image, speech, transcription, summarize)
+ * to be sent over the same streaming transport as chat.
+ *
+ * @param generator - An async function that performs the generation and returns the result
+ * @param options - Optional configuration (runId)
+ * @returns An AsyncIterable of StreamChunks with RUN_STARTED, CUSTOM(generation:result), and RUN_FINISHED events
+ */
+export async function* streamGenerationResult<TResult>(
+  generator: () => Promise<TResult>,
+  options?: { runId?: string },
+): AsyncIterable<StreamChunk> {
+  const runId = options?.runId ?? createId('run')
+
+  yield {
+    type: 'RUN_STARTED',
+    runId,
+    timestamp: Date.now(),
+  }
+
+  try {
+    const result = await generator()
+
+    yield {
+      type: 'CUSTOM',
+      name: 'generation:result',
+      value: result as unknown,
+      timestamp: Date.now(),
+    }
+
+    yield {
+      type: 'RUN_FINISHED',
+      runId,
+      finishReason: 'stop',
+      timestamp: Date.now(),
+    }
+  } catch (error: any) {
+    yield {
+      type: 'RUN_ERROR',
+      runId,
+      error: {
+        message: error.message || 'Generation failed',
+        code: error.code,
+      },
+      timestamp: Date.now(),
+    }
+  }
+}

package/src/activities/summarize/index.ts

@@ -6,6 +6,7 @@
  */
 
 import { aiEventClient } from '../../event-client.js'
+import { streamGenerationResult } from '../stream-generation-result.js'
 import type { SummarizeAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -239,28 +240,8 @@ async function* runStreamingSummarize(
     return
   }
 
-  // Fall back to non-streaming and yield as a single chunk
-  const result = await adapter.summarize(summarizeOptions)
-
-  // Yield TEXT_MESSAGE_CONTENT event with the summary
-  yield {
-    type: 'TEXT_MESSAGE_CONTENT',
-    messageId: result.id,
-    model: result.model,
-    timestamp: Date.now(),
-    delta: result.summary,
-    content: result.summary,
-  }
-
-  // Yield RUN_FINISHED event
-  yield {
-    type: 'RUN_FINISHED',
-    runId: result.id,
-    model: result.model,
-    timestamp: Date.now(),
-    finishReason: 'stop',
-    usage: result.usage,
-  }
+  // Fall back to non-streaming — wrap result with streamGenerationResult
+  yield* streamGenerationResult(() => adapter.summarize(summarizeOptions))
 }
 
 // ===========================