@tanstack/ai 0.32.0 → 0.33.0

package/src/activities/generateAudio/index.ts

@@ -8,8 +8,16 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import {
+  createGenerationContext,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware'
 import type { AudioAdapter } from './adapter'
 import type { AudioGenerationResult, StreamChunk } from '../../types'
 
@@ -70,6 +78,12 @@ export interface AudioActivityOptions<
    * control and/or a custom `Logger`.
    */
   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.
+   */
+  middleware?: Array<GenerationMiddleware>
 }
 
 // ===========================
@@ -135,7 +149,13 @@ async function runGenerateAudio<
 >(
   options: AudioActivityOptions<TAdapter, boolean>,
 ): Promise<AudioGenerationResult> {
-  const { adapter, stream: _stream, debug: _debug, ...rest } = options
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options
   const model = adapter.model
   const requestId = createId('audio')
   const startTime = Date.now()
@@ -145,6 +165,17 @@ async function runGenerateAudio<
     (adapter as { name?: string }).name ??
     'unknown'
 
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'audio',
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
   aiEventClient.emit('audio:request:started', {
     requestId,
     provider: adapter.name,
@@ -189,6 +220,12 @@ async function runGenerateAudio<
       audioDuration: result.audio.duration,
     })
 
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)
+    await runGenerationFinish(middleware, mwCtx, {
+      duration: elapsedMs,
+      usage: result.usage,
+    })
+
     return result
   } catch (error) {
     const elapsedMs = Date.now() - startTime
@@ -202,6 +239,10 @@ async function runGenerateAudio<
       modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
       timestamp: Date.now(),
     })
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: elapsedMs,
+    })
     logger.errors('generateAudio activity failed', {
       error,
       source: 'generateAudio',

package/src/activities/generateImage/index.ts

@@ -8,9 +8,17 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import {
+  createGenerationContext,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware'
 import { resolveMediaPrompt } from '../../utilities/media-prompt'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware'
 import type { ImageAdapter } from './adapter'
 import type {
   ImageGenerationResult,
@@ -123,6 +131,12 @@ export type ImageActivityOptions<
    * control and/or a custom `Logger`.
    */
   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.
+   */
+  middleware?: Array<GenerationMiddleware>
 } & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
   ? {
       /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<
@@ -228,12 +242,29 @@ async function runGenerateImage<
 >(
   options: ImageActivityOptions<TAdapter, boolean>,
 ): Promise<ImageGenerationResult> {
-  const { adapter, stream: _stream, debug: _debug, ...rest } = options
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options
   const model = adapter.model
   const requestId = createId('image')
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
 
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'image',
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
   // Devtools events carry the flattened prompt text plus media-part counts —
   // the wire payload stays `prompt: string` regardless of the prompt shape.
   const resolved = resolveMediaPrompt(rest.prompt)
@@ -299,8 +330,18 @@ async function runGenerateImage<
       count: result.images.length,
     })
 
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)
+    await runGenerationFinish(middleware, mwCtx, {
+      duration,
+      usage: result.usage,
+    })
+
     return result
   } catch (error) {
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: Date.now() - startTime,
+    })
     logger.errors('generateImage activity failed', {
       error,
       source: 'generateImage',

package/src/activities/generateSpeech/index.ts

@@ -8,8 +8,16 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import {
+  createGenerationContext,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware'
 import type { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 
@@ -73,6 +81,12 @@ export interface TTSActivityOptions<
    * control and/or a custom `Logger`.
    */
   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.
+   */
+  middleware?: Array<GenerationMiddleware>
 }
 
 // ===========================
@@ -143,7 +157,13 @@ export function generateSpeech<
 async function runGenerateSpeech<
   TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
 >(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {
-  const { adapter, stream: _stream, debug: _debug, ...rest } = options
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options
   const model = adapter.model
   const requestId = createId('speech')
   const startTime = Date.now()
@@ -153,6 +173,17 @@ async function runGenerateSpeech<
     (adapter as { name?: string }).name ??
     'unknown'
 
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'tts',
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
   aiEventClient.emit('speech:request:started', {
     requestId,
     provider: adapter.name,
@@ -202,6 +233,12 @@ async function runGenerateSpeech<
       contentType: result.contentType,
     })
 
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)
+    await runGenerationFinish(middleware, mwCtx, {
+      duration,
+      usage: result.usage,
+    })
+
     return result
   } catch (error) {
     const duration = Date.now() - startTime
@@ -215,6 +252,10 @@ async function runGenerateSpeech<
       modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
       timestamp: Date.now(),
     })
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration,
+    })
     logger.errors('generateSpeech activity failed', {
       error,
       source: 'generateSpeech',

package/src/activities/generateTranscription/index.ts

@@ -8,8 +8,16 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import {
+  createGenerationContext,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware'
 import type { TranscriptionAdapter } from './adapter'
 import type { StreamChunk, TranscriptionResult } from '../../types'
 
@@ -76,6 +84,12 @@ export interface TranscriptionActivityOptions<
    * control and/or a custom `Logger`.
    */
   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.
+   */
+  middleware?: Array<GenerationMiddleware>
 }
 
 // ===========================
@@ -174,7 +188,13 @@ async function runGenerateTranscription<
 >(
   options: TranscriptionActivityOptions<TAdapter, boolean>,
 ): Promise<TranscriptionResult> {
-  const { adapter, stream: _stream, debug: _debug, ...rest } = options
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options
   const model = adapter.model
   const requestId = createId('transcription')
   const startTime = Date.now()
@@ -184,6 +204,17 @@ async function runGenerateTranscription<
     (adapter as { name?: string }).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,
@@ -220,6 +251,12 @@ async function runGenerateTranscription<
       { 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
@@ -233,6 +270,10 @@ async function runGenerateTranscription<
       modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
       timestamp: Date.now(),
     })
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration,
+    })
     logger.errors('generateTranscription activity failed', {
       error,
       source: 'generateTranscription',

package/src/activities/generateVideo/index.ts

@@ -10,8 +10,17 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { toRunErrorPayload } from '../error-payload'
 import { resolveDebugOption } from '../../logger/resolve'
+import {
+  createGenerationContext,
+  runGenerationAbort,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware'
 import type { VideoAdapter } from './adapter'
 import type {
   MediaPrompt,
@@ -160,6 +169,14 @@ export type VideoCreateOptions<
    * control and/or a custom `Logger`.
    */
   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`.
+   */
+  middleware?: Array<GenerationMiddleware>
 } & ({} extends VideoProviderOptions<TAdapter>
     ? {
         /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>
@@ -299,14 +316,27 @@ export function generateVideo<
 async function runCreateVideoJob<
   TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
-  const { adapter, prompt, size, duration, modelOptions } = options
+  const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
+  const requestId = createId('video')
+  const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
   const providerName =
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
     'unknown'
 
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'video',
+    provider: adapter.name,
+    model,
+    modelOptions,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
   logger.request(`activity=generateVideo provider=${providerName}`, {
     provider: providerName,
     model,
@@ -325,8 +355,17 @@ async function runCreateVideoJob<
       jobId: result.jobId,
       model: result.model,
     })
+    // Non-streaming create only submits the job; usage isn't known until the
+    // job completes via polling, so the span covers submission only.
+    await runGenerationFinish(middleware, mwCtx, {
+      duration: Date.now() - startTime,
+    })
     return result
   } catch (error) {
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: Date.now() - startTime,
+    })
     logger.errors('generateVideo activity failed', {
       error,
       source: 'generateVideo',
@@ -346,9 +385,11 @@ function sleep(ms: number): Promise<void> {
 async function* runStreamingVideoGeneration<
   TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, true>): AsyncIterable<StreamChunk> {
-  const { adapter, prompt, size, duration, modelOptions } = options
+  const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
   const runId = options.runId ?? createId('run')
+  const requestId = createId('video')
+  const obsStartTime = Date.now()
   const pollingInterval = options.pollingInterval ?? 2000
   const maxDuration = options.maxDuration ?? 600_000
   const logger: InternalLogger = resolveDebugOption(options.debug)
@@ -366,6 +407,17 @@ async function* runStreamingVideoGeneration<
     timestamp: Date.now(),
   } as StreamChunk
 
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'video',
+    provider: adapter.name,
+    model,
+    modelOptions,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
   logger.request(
     `activity=generateVideo provider=${providerName} stream=true`,
     {
@@ -374,6 +426,9 @@ async function* runStreamingVideoGeneration<
     },
   )
 
+  // Tracks whether a terminal observer event (finish/error) has already fired,
+  // so the `finally` below can fire one on abandonment without double-firing.
+  let settled = false
   try {
     // Create the video generation job
     const jobResult = await adapter.createVideoJob({
@@ -422,6 +477,18 @@ async function* runStreamingVideoGeneration<
           },
         )
 
+        // Fire finish before yielding the terminal chunks: the generation has
+        // succeeded, so a consumer that stops reading after `generation:result`
+        // (without pulling `RUN_FINISHED`) must not trip the abandonment path in
+        // `finally`, which would otherwise report a spurious cancellation.
+        if (urlResult.usage)
+          await runGenerationUsage(middleware, mwCtx, urlResult.usage)
+        await runGenerationFinish(middleware, mwCtx, {
+          duration: Date.now() - obsStartTime,
+          usage: urlResult.usage,
+        })
+        settled = true
+
         yield {
           type: 'CUSTOM',
           name: 'generation:result',
@@ -453,6 +520,14 @@ async function* runStreamingVideoGeneration<
     throw new Error('Video generation timed out')
   } catch (error: unknown) {
     const payload = toRunErrorPayload(error, 'Video generation failed')
+    // Mark settled before firing onError: if a user error-hook throws, the
+    // `finally` below must still not double-fire onAbort over the same op
+    // (which would mask the original error and end the span twice).
+    settled = true
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: Date.now() - obsStartTime,
+    })
     logger.errors('generateVideo activity failed', {
       message: payload.message,
       code: payload.code,
@@ -467,6 +542,17 @@ async function* runStreamingVideoGeneration<
       error: payload,
       timestamp: Date.now(),
     } as StreamChunk
+  } finally {
+    if (!settled) {
+      // The consumer abandoned the stream (broke the `for await` loop or
+      // disconnected) before completion, so the generator is being unwound at
+      // a `yield` without reaching finish/error. Fire `onAbort` — a cancel, not
+      // an error — so otelMiddleware ends its span instead of leaking it.
+      await runGenerationAbort(middleware, mwCtx, {
+        reason: 'Video generation stream abandoned before completion',
+        duration: Date.now() - obsStartTime,
+      })
+    }
   }
 }
 

package/src/activities/middleware/index.ts

@@ -0,0 +1,20 @@
+// Base, activity-agnostic middleware shared by chat and the media activities.
+// The `ChatMiddleware` superset lives at `../chat/middleware`.
+export type {
+  GenerationActivity,
+  GenerationMiddleware,
+  GenerationMiddlewareContext,
+  GenerationUsageInfo,
+  GenerationFinishInfo,
+  GenerationAbortInfo,
+  GenerationErrorInfo,
+  AnyGenerationMiddleware,
+} from './types'
+export {
+  createGenerationContext,
+  runGenerationStart,
+  runGenerationUsage,
+  runGenerationFinish,
+  runGenerationAbort,
+  runGenerationError,
+} from './run'

package/src/activities/middleware/run.ts

@@ -0,0 +1,88 @@
+import type {
+  GenerationAbortInfo,
+  GenerationErrorInfo,
+  GenerationFinishInfo,
+  GenerationMiddleware,
+  GenerationMiddlewareContext,
+  GenerationUsageInfo,
+} from './types'
+
+/**
+ * Build the stable context for a single media-activity call.
+ *
+ * Media activities are always server-side and carry no user runtime context,
+ * so `source` is fixed to `'server'` and `context` to `undefined`.
+ */
+export function createGenerationContext(args: {
+  requestId: string
+  activity: GenerationMiddlewareContext['activity']
+  provider: string
+  model: string
+  modelOptions?: unknown
+  createId: (prefix: string) => string
+}): GenerationMiddlewareContext {
+  return {
+    requestId: args.requestId,
+    activity: args.activity,
+    provider: args.provider,
+    model: args.model,
+    modelOptions: args.modelOptions,
+    source: 'server',
+    createId: args.createId,
+    context: undefined,
+  }
+}
+
+/**
+ * Run a single lifecycle hook across each middleware in registration order,
+ * awaiting each. Exceptions PROPAGATE (matching `chat()` middleware) — a
+ * broken middleware fails the activity rather than being silently swallowed.
+ */
+async function run(
+  middleware: ReadonlyArray<GenerationMiddleware> | undefined,
+  invoke: (mw: GenerationMiddleware) => void | Promise<void>,
+): Promise<void> {
+  if (!middleware || middleware.length === 0) return
+  for (const mw of middleware) {
+    await invoke(mw)
+  }
+}
+
+export function runGenerationStart(
+  middleware: ReadonlyArray<GenerationMiddleware> | undefined,
+  ctx: GenerationMiddlewareContext,
+): Promise<void> {
+  return run(middleware, (mw) => mw.onStart?.(ctx))
+}
+
+export function runGenerationUsage(
+  middleware: ReadonlyArray<GenerationMiddleware> | undefined,
+  ctx: GenerationMiddlewareContext,
+  usage: GenerationUsageInfo,
+): Promise<void> {
+  return run(middleware, (mw) => mw.onUsage?.(ctx, usage))
+}
+
+export function runGenerationFinish(
+  middleware: ReadonlyArray<GenerationMiddleware> | undefined,
+  ctx: GenerationMiddlewareContext,
+  info: GenerationFinishInfo,
+): Promise<void> {
+  return run(middleware, (mw) => mw.onFinish?.(ctx, info))
+}
+
+export function runGenerationAbort(
+  middleware: ReadonlyArray<GenerationMiddleware> | undefined,
+  ctx: GenerationMiddlewareContext,
+  info: GenerationAbortInfo,
+): Promise<void> {
+  return run(middleware, (mw) => mw.onAbort?.(ctx, info))
+}
+
+export function runGenerationError(
+  middleware: ReadonlyArray<GenerationMiddleware> | undefined,
+  ctx: GenerationMiddlewareContext,
+  info: GenerationErrorInfo,
+): Promise<void> {
+  return run(middleware, (mw) => mw.onError?.(ctx, info))
+}