@tanstack/ai 0.6.1 → 0.6.3

package/src/activities/chat/tools/tool-calls.ts

@@ -324,6 +324,13 @@ export async function* executeToolCalls(
     toolMap.set(tool.name, tool)
   }
 
+  // Batch gating: when any tool in the batch still needs an approval decision,
+  // defer all execution so side effects don't happen before the user decides.
+  const hasPendingApprovals = toolCalls.some((tc) => {
+    const t = toolMap.get(tc.function.name)
+    return t?.needsApproval && !approvals.has(`approval_${tc.id}`)
+  })
+
   for (const toolCall of toolCalls) {
     const tool = toolMap.get(toolCall.function.name)
     const toolName = toolCall.function.name
@@ -339,6 +346,13 @@ export async function* executeToolCalls(
       continue
     }
 
+    // Skip non-pending tools while approvals are outstanding
+    if (hasPendingApprovals) {
+      if (!tool.needsApproval || approvals.has(`approval_${toolCall.id}`)) {
+        continue
+      }
+    }
+
     // Parse arguments, throwing error if invalid JSON
     let input: unknown = {}
     const argsStr = toolCall.function.arguments.trim() || '{}'

package/src/activities/generateImage/index.ts

@@ -6,8 +6,9 @@
  */
 
 import { aiEventClient } from '../../event-client.js'
+import { streamGenerationResult } from '../stream-generation-result.js'
 import type { ImageAdapter } from './adapter'
-import type { ImageGenerationResult } from '../../types'
+import type { ImageGenerationResult, StreamChunk } from '../../types'
 
 // ===========================
 // Activity Kind
@@ -60,9 +61,11 @@ export type ImageSizeForModel<TAdapter, TModel extends string> =
  * The model is extracted from the adapter's model property.
  *
  * @template TAdapter - The image adapter type
+ * @template TStream - Whether to stream the output
  */
 export type ImageActivityOptions<
   TAdapter extends ImageAdapter<string, any, any, any>,
+  TStream extends boolean = false,
 > = {
   /** The image adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
@@ -72,6 +75,14 @@ export type ImageActivityOptions<
   numberOfImages?: number
   /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
   size?: ImageSizeForModel<TAdapter, TAdapter['model']>
+  /**
+   * Whether to stream the image generation result.
+   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+   * When false or not provided, returns a Promise<ImageGenerationResult>.
+   *
+   * @default false
+   */
+  stream?: TStream
 } & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
   ? {
       /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<
@@ -90,8 +101,15 @@ export type ImageActivityOptions<
 // Activity Result Type
 // ===========================
 
-/** Result type for the image activity */
-export type ImageActivityResult = Promise<ImageGenerationResult>
+/**
+ * Result type for the image activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<ImageGenerationResult>
+ */
+export type ImageActivityResult<TStream extends boolean = false> =
+  TStream extends true
+    ? AsyncIterable<StreamChunk>
+    : Promise<ImageGenerationResult>
 
 function createId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
@@ -146,10 +164,31 @@ function createId(prefix: string): string {
  * })
  * ```
  */
-export async function generateImage<
+export function generateImage<
+  TAdapter extends ImageAdapter<string, any, any, any>,
+  TStream extends boolean = false,
+>(
+  options: ImageActivityOptions<TAdapter, TStream>,
+): ImageActivityResult<TStream> {
+  if (options.stream) {
+    return streamGenerationResult(() =>
+      runGenerateImage(options),
+    ) as ImageActivityResult<TStream>
+  }
+
+  return runGenerateImage(options) as ImageActivityResult<TStream>
+}
+
+/**
+ * Internal implementation of image generation (always non-streaming).
+ * Contains all devtools event emission logic.
+ */
+async function runGenerateImage<
   TAdapter extends ImageAdapter<string, any, any, any>,
->(options: ImageActivityOptions<TAdapter>): ImageActivityResult {
-  const { adapter, ...rest } = options
+>(
+  options: ImageActivityOptions<TAdapter, boolean>,
+): Promise<ImageGenerationResult> {
+  const { adapter, stream: _stream, ...rest } = options
   const model = adapter.model
   const requestId = createId('image')
   const startTime = Date.now()
@@ -204,7 +243,10 @@ export async function generateImage<
  */
 export function createImageOptions<
   TAdapter extends ImageAdapter<string, any, any, any>,
->(options: ImageActivityOptions<TAdapter>): ImageActivityOptions<TAdapter> {
+  TStream extends boolean = false,
+>(
+  options: ImageActivityOptions<TAdapter, TStream>,
+): ImageActivityOptions<TAdapter, TStream> {
   return options
 }
 

package/src/activities/generateSpeech/index.ts

@@ -6,8 +6,9 @@
  */
 
 import { aiEventClient } from '../../event-client.js'
+import { streamGenerationResult } from '../stream-generation-result.js'
 import type { TTSAdapter } from './adapter'
-import type { TTSResult } from '../../types'
+import type { StreamChunk, TTSResult } from '../../types'
 
 // ===========================
 // Activity Kind
@@ -37,9 +38,11 @@ export type TTSProviderOptions<TAdapter> =
  * The model is extracted from the adapter's model property.
  *
  * @template TAdapter - The TTS adapter type
+ * @template TStream - Whether to stream the output
  */
 export interface TTSActivityOptions<
   TAdapter extends TTSAdapter<string, object>,
+  TStream extends boolean = false,
 > {
   /** The TTS adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
@@ -53,14 +56,27 @@ export interface TTSActivityOptions<
   speed?: number
   /** Provider-specific options for TTS generation */
   modelOptions?: TTSProviderOptions<TAdapter>
+  /**
+   * Whether to stream the generation result.
+   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+   * When false or not provided, returns a Promise<TTSResult>.
+   *
+   * @default false
+   */
+  stream?: TStream
 }
 
 // ===========================
 // Activity Result Type
 // ===========================
 
-/** Result type for the TTS activity */
-export type TTSActivityResult = Promise<TTSResult>
+/**
+ * Result type for the TTS activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<TTSResult>
+ */
+export type TTSActivityResult<TStream extends boolean = false> =
+  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>
 
 function createId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
@@ -100,10 +116,25 @@ function createId(prefix: string): string {
  * })
  * ```
  */
-export async function generateSpeech<
+export function generateSpeech<
   TAdapter extends TTSAdapter<string, object>,
->(options: TTSActivityOptions<TAdapter>): TTSActivityResult {
-  const { adapter, ...rest } = options
+  TStream extends boolean = false,
+>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {
+  if (options.stream) {
+    return streamGenerationResult(() =>
+      runGenerateSpeech(options),
+    ) as TTSActivityResult<TStream>
+  }
+  return runGenerateSpeech(options) as TTSActivityResult<TStream>
+}
+
+/**
+ * Run the core TTS generation logic (non-streaming).
+ */
+async function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(
+  options: TTSActivityOptions<TAdapter, boolean>,
+): Promise<TTSResult> {
+  const { adapter, stream: _stream, ...rest } = options
   const model = adapter.model
   const requestId = createId('speech')
   const startTime = Date.now()
@@ -149,7 +180,10 @@ export async function generateSpeech<
  */
 export function createSpeechOptions<
   TAdapter extends TTSAdapter<string, object>,
->(options: TTSActivityOptions<TAdapter>): TTSActivityOptions<TAdapter> {
+  TStream extends boolean = false,
+>(
+  options: TTSActivityOptions<TAdapter, TStream>,
+): TTSActivityOptions<TAdapter, TStream> {
   return options
 }
 

package/src/activities/generateTranscription/index.ts

@@ -6,8 +6,9 @@
  */
 
 import { aiEventClient } from '../../event-client.js'
+import { streamGenerationResult } from '../stream-generation-result.js'
 import type { TranscriptionAdapter } from './adapter'
-import type { TranscriptionResult } from '../../types'
+import type { StreamChunk, TranscriptionResult } from '../../types'
 
 // ===========================
 // Activity Kind
@@ -37,9 +38,11 @@ export type TranscriptionProviderOptions<TAdapter> =
  * The model is extracted from the adapter's model property.
  *
  * @template TAdapter - The transcription adapter type
+ * @template TStream - Whether to stream the output
  */
 export interface TranscriptionActivityOptions<
   TAdapter extends TranscriptionAdapter<string, object>,
+  TStream extends boolean = false,
 > {
   /** The transcription adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
@@ -53,14 +56,29 @@ export interface TranscriptionActivityOptions<
   responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
   /** Provider-specific options for transcription */
   modelOptions?: TranscriptionProviderOptions<TAdapter>
+  /**
+   * Whether to stream the transcription result.
+   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+   * When false or not provided, returns a Promise<TranscriptionResult>.
+   *
+   * @default false
+   */
+  stream?: TStream
 }
 
 // ===========================
 // Activity Result Type
 // ===========================
 
-/** Result type for the transcription activity */
-export type TranscriptionActivityResult = Promise<TranscriptionResult>
+/**
+ * Result type for the transcription activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<TranscriptionResult>
+ */
+export type TranscriptionActivityResult<TStream extends boolean = false> =
+  TStream extends true
+    ? AsyncIterable<StreamChunk>
+    : Promise<TranscriptionResult>
 
 function createId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
@@ -101,13 +119,44 @@ function createId(prefix: string): string {
  *   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)
+ * }
+ * ```
+ */
+export function generateTranscription<
+  TAdapter extends TranscriptionAdapter<string, object>,
+  TStream extends boolean = false,
+>(
+  options: TranscriptionActivityOptions<TAdapter, TStream>,
+): TranscriptionActivityResult<TStream> {
+  if (options.stream) {
+    return streamGenerationResult(() =>
+      runGenerateTranscription(options),
+    ) as TranscriptionActivityResult<TStream>
+  }
+
+  return runGenerateTranscription(
+    options,
+  ) as TranscriptionActivityResult<TStream>
+}
+
+/**
+ * Run non-streaming transcription
  */
-export async function generateTranscription<
+async function runGenerateTranscription<
   TAdapter extends TranscriptionAdapter<string, object>,
 >(
-  options: TranscriptionActivityOptions<TAdapter>,
-): TranscriptionActivityResult {
-  const { adapter, ...rest } = options
+  options: TranscriptionActivityOptions<TAdapter, boolean>,
+): Promise<TranscriptionResult> {
+  const { adapter, stream: _stream, ...rest } = options
   const model = adapter.model
   const requestId = createId('transcription')
   const startTime = Date.now()
@@ -149,9 +198,10 @@ export async function generateTranscription<
  */
 export function createTranscriptionOptions<
   TAdapter extends TranscriptionAdapter<string, object>,
+  TStream extends boolean = false,
 >(
-  options: TranscriptionActivityOptions<TAdapter>,
-): TranscriptionActivityOptions<TAdapter> {
+  options: TranscriptionActivityOptions<TAdapter, TStream>,
+): TranscriptionActivityOptions<TAdapter, TStream> {
   return options
 }
 

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))
 }
 
 // ===========================