@tanstack/ai 0.41.0 → 0.43.0

package/src/activities/middleware/types.ts

@@ -25,11 +25,14 @@ import type { TokenUsage } from '../../types'
 /**
  * The activity an observability event describes.
  *
- * Mirrors the public surface a caller reaches for: `'chat'` for `chat()`, and
- * the media kinds for the `generate*` activities. `'tts'` matches the speech
- * adapter's kind (the public discriminator avoids inventing a parallel
- * `'speech'`/`'text'` vocabulary). `otelMiddleware` maps each to its
- * `gen_ai.operation.name`.
+ * Mirrors the public surface a caller reaches for: `'chat'` for `chat()`,
+ * `'summarize'` for `summarize()`, and the media kinds for the `generate*`
+ * activities. `'tts'` matches the speech adapter's kind (the public
+ * discriminator avoids inventing a parallel `'speech'`/`'text'` vocabulary).
+ * `otelMiddleware` maps each to its `gen_ai.operation.name`.
+ *
+ * `'summarize'` produces text, not media, so it has no artifacts — a
+ * persistence middleware stores its run record and result and nothing else.
  */
 export type GenerationActivity =
   | 'chat'
@@ -38,6 +41,7 @@ export type GenerationActivity =
   | 'audio'
   | 'tts'
   | 'transcription'
+  | 'summarize'
 
 /**
  * Stable context passed to every {@link GenerationMiddleware} hook. Created
@@ -60,6 +64,10 @@ export interface GenerationMiddlewareContext<TContext = unknown> {
   provider: string
   /** Model id. Emitted as `gen_ai.request.model`. */
   model: string
+  /** Stable conversation/thread id, when supplied by the caller. */
+  threadId?: string
+  /** Stable run id, when supplied by the caller. */
+  runId?: string
   /**
    * Provider-specific options passed to the activity, if any. Typed `unknown`
    * because each activity's options are strongly typed per model; a supertype
@@ -72,8 +80,44 @@ export interface GenerationMiddlewareContext<TContext = unknown> {
   createId: (prefix: string) => string
   /** Runtime context provided by the activity options, if any. */
   context: TContext
+  /**
+   * Result transforms registered by middleware during this activity call.
+   * Transforms run after the raw adapter result exists and before the final
+   * result is returned or streamed. Push multiple transforms to run them in
+   * registration order.
+   *
+   * REQUIRED (always an array, empty when nothing registered): middleware
+   * registers by pushing onto it, so an optional array would let a host that
+   * builds its own context omit it and silently no-op every registration —
+   * generation persistence would then mark a run completed with neither its
+   * result nor its artifacts written, with nothing to observe but the missing
+   * data. Every context the library builds comes from
+   * `createGenerationContext`, which always sets `[]`.
+   */
+  resultTransforms: Array<GenerationResultTransform<any, TContext>>
+  /**
+   * Activity inputs captured for middleware that needs to transform or persist
+   * the result together with reconstructable request metadata.
+   */
+  artifactInputs?: unknown
 }
 
+/** Stable context handed to each {@link GenerationResultTransform}. */
+export interface GenerationResultTransformContext<TContext = unknown> {
+  /** The activity call being transformed. */
+  middleware: GenerationMiddlewareContext<TContext>
+}
+
+/**
+ * A transform middleware registers on `ctx.resultTransforms` to rewrite the raw
+ * adapter result before it is returned or streamed. Return a new result to
+ * replace it, or `undefined` to leave it unchanged.
+ */
+export type GenerationResultTransform<TResult = unknown, TContext = unknown> = (
+  result: TResult,
+  ctx: GenerationResultTransformContext<TContext>,
+) => TResult | undefined | Promise<TResult | undefined>
+
 // ===========================
 // Hook payloads
 // ===========================

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

@@ -12,6 +12,19 @@ function createId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
 }
 
+/**
+ * Persisted artifact refs a middleware may have attached to the result. Read
+ * defensively: the result shape is activity-specific and `artifacts` is only
+ * present when generation persistence is wired with an artifact + blob store.
+ */
+function artifactsFromResult(result: unknown): Array<unknown> | undefined {
+  if (typeof result !== 'object' || result === null) return undefined
+  const artifacts = (result as { artifacts?: unknown }).artifacts
+  return Array.isArray(artifacts) && artifacts.length > 0
+    ? artifacts
+    : undefined
+}
+
 /**
  * Wrap a one-shot generation result as a StreamChunk async iterable.
  *
@@ -23,7 +36,10 @@ function createId(prefix: string): string {
  * @returns An AsyncIterable of StreamChunks with RUN_STARTED, CUSTOM(generation:result), and RUN_FINISHED events on success, or RUN_STARTED and RUN_ERROR on failure
  */
 export async function* streamGenerationResult<TResult>(
-  generator: () => Promise<TResult>,
+  generator: (resolved: {
+    runId: string
+    threadId: string
+  }) => Promise<TResult>,
   options?: { runId?: string; threadId?: string },
 ): AsyncIterable<StreamChunk> {
   const runId = options?.runId ?? createId('run')
@@ -37,7 +53,19 @@ export async function* streamGenerationResult<TResult>(
   }
 
   try {
-    const result = await generator()
+    const result = await generator({ runId, threadId })
+
+    // Emit persisted artifact refs (if a middleware attached any) before the
+    // result, so the client records them as the run streams.
+    const artifacts = artifactsFromResult(result)
+    if (artifacts) {
+      yield {
+        type: EventType.CUSTOM,
+        name: 'generation:artifacts',
+        value: artifacts,
+        timestamp: Date.now(),
+      }
+    }
 
     yield {
       type: EventType.CUSTOM,

package/src/activities/summarize/chat-stream-summarize.ts

@@ -362,6 +362,11 @@ export class ChatStreamSummarizeAdapter<
       systemPrompts: [systemPrompt],
       modelOptions,
       logger: options.logger,
+      // Forward the run identity so the wrapped chat stamps it onto RUN_STARTED
+      // (chat uses `runId` as its `runIdOverride`). Conditional spreads keep the
+      // fields absent when unset, under `exactOptionalPropertyTypes`.
+      ...(options.runId !== undefined ? { runId: options.runId } : {}),
+      ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
     }
   }
 

package/src/activities/summarize/index.ts

@@ -8,8 +8,18 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import {
+  applyGenerationResultTransforms,
+  createGenerationContext,
+  runGenerationAbort,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage,
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { SummarizeAdapter } from './adapter'
 import type { StreamChunk, SummarizationResult } from '../../types'
 
@@ -57,6 +67,32 @@ export interface SummarizeActivityOptions<
   focus?: Array<string>
   /** Provider-specific options */
   modelOptions?: SummarizeProviderOptions<TAdapter>
+  /**
+   * Optional run identity. When set on a streaming summarize, it is stamped
+   * onto the emitted `RUN_STARTED` so a delivery-durable route keys the run's
+   * log by the same id the client rejoins with — making a mid-run reload
+   * resumable. Filed under `threadId` when persistence is wired.
+   */
+  runId?: string
+  /**
+   * Stable conversation/thread id for correlating this run when persisted — the
+   * slot a reloading client hydrates the last summary by. Pass it whenever
+   * persistence is on; `withGenerationPersistence` refuses a run without one.
+   */
+  threadId?: string
+  /**
+   * Observe-only middleware notified on start, usage, success, and error. Pass
+   * `otelMiddleware()` for OpenTelemetry, `withGenerationPersistence()` to
+   * record the run (summaries are text, so the run record holds the result and
+   * there are no artifacts to store), or implement the `GenerationMiddleware`
+   * contract for a custom backend.
+   *
+   * Streaming and non-streaming behave the same way: one `onStart`, then a
+   * terminal `onFinish` / `onError`, with the result transforms applied to the
+   * `SummarizationResult` in between. A streaming consumer that disconnects
+   * mid-summary fires `onAbort`.
+   */
+  middleware?: Array<GenerationMiddleware>
   /**
    * Whether to stream the summarization result.
    * When true, returns an AsyncIterable<StreamChunk> for streaming output.
@@ -180,13 +216,27 @@ export function summarize<
 async function runSummarize(
   options: SummarizeActivityOptions<SummarizeAdapter<string, object>, false>,
 ): Promise<SummarizationResult> {
-  const { adapter, text, maxLength, style, focus, modelOptions } = options
+  const { adapter, text, maxLength, style, focus, modelOptions, middleware } =
+    options
   const model = adapter.model
   const requestId = createId('summarize')
   const inputLength = text.length
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
 
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: 'summarize',
+    provider: adapter.name,
+    model,
+    modelOptions,
+    threadId: options.threadId,
+    runId: options.runId,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
   aiEventClient.emit('summarize:request:started', {
     requestId,
     provider: adapter.name,
@@ -212,7 +262,11 @@ async function runSummarize(
   }
 
   try {
-    const result = await adapter.summarize(summarizeOptions)
+    const rawResult = await adapter.summarize(summarizeOptions)
+    // Transforms run before anything observes the result — the same order every
+    // media activity uses — so the run record and the returned value are the
+    // same object.
+    const result = await applyGenerationResultTransforms(mwCtx, rawResult)
 
     const duration = Date.now() - startTime
     const outputLength = result.summary.length
@@ -232,8 +286,18 @@ async function runSummarize(
       outputLength,
     })
 
+    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('summarize activity failed', {
       error,
       source: 'summarize',
@@ -242,6 +306,15 @@ async function runSummarize(
   }
 }
 
+/** Read a `usage` off a transformed result without asserting its shape. */
+function usageOf(result: unknown): SummarizationResult['usage'] | undefined {
+  if (typeof result !== 'object' || result === null) return undefined
+  const usage = (result as { usage?: unknown }).usage
+  return typeof usage === 'object' && usage !== null
+    ? (usage as SummarizationResult['usage'])
+    : undefined
+}
+
 /**
  * Run streaming summarization
  * Uses the adapter's native streaming if available, otherwise falls back
@@ -250,7 +323,16 @@ async function runSummarize(
 async function* runStreamingSummarize(
   options: SummarizeActivityOptions<SummarizeAdapter<string, object>, true>,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, text, maxLength, style, focus, modelOptions } = options
+  const {
+    adapter,
+    text,
+    maxLength,
+    style,
+    focus,
+    modelOptions,
+    runId,
+    threadId,
+  } = options
   const model = adapter.model
   const logger: InternalLogger = resolveDebugOption(options.debug)
 
@@ -260,6 +342,10 @@ async function* runStreamingSummarize(
     stream: true,
   })
 
+  // Thread the caller's run identity through so the emitted `RUN_STARTED`
+  // carries it — keeps a delivery-durable route's log keyed by the id the
+  // client rejoins with (mid-run reload resumability). Conditional spreads keep
+  // the fields off the object entirely under `exactOptionalPropertyTypes`.
   const summarizeOptions = {
     model,
     text,
@@ -268,23 +354,127 @@ async function* runStreamingSummarize(
     focus,
     modelOptions,
     logger,
+    ...(runId !== undefined ? { runId } : {}),
+    ...(threadId !== undefined ? { threadId } : {}),
+  }
+
+  // Use real streaming if the adapter supports it
+  if (adapter.summarizeStream) {
+    yield* runNativeSummarizeStream(
+      options,
+      adapter.summarizeStream(summarizeOptions),
+      logger,
+    )
+    return
   }
 
   try {
-    // Use real streaming if the adapter supports it
-    if (adapter.summarizeStream) {
-      yield* adapter.summarizeStream(summarizeOptions)
-      return
-    }
+    // Fall back to non-streaming — wrap the result with streamGenerationResult,
+    // forwarding the run identity so its RUN_STARTED matches too. The generation
+    // itself goes through `runSummarize`, so middleware (and its result
+    // transforms) run exactly as they do for a non-streaming call. Only `runId`
+    // is taken from the resolved wire identity — `threadId` stays the CALLER's,
+    // since a minted one would file the run in a slot no client can hydrate.
+    yield* streamGenerationResult(
+      (resolved) =>
+        runSummarize({ ...options, stream: false, runId: resolved.runId }),
+      {
+        ...(runId !== undefined ? { runId } : {}),
+        ...(threadId !== undefined ? { threadId } : {}),
+      },
+    )
+  } catch (error) {
+    logger.errors('summarize activity failed', {
+      error,
+      source: 'summarize',
+    })
+    throw error
+  }
+}
 
-    // Fall back to non-streaming — wrap result with streamGenerationResult
-    yield* streamGenerationResult(() => adapter.summarize(summarizeOptions))
+/**
+ * Drive an adapter's native `summarizeStream`, wiring the generation middleware
+ * around it.
+ *
+ * The adapter emits a terminal `generation:result` CUSTOM chunk carrying the
+ * assembled {@link SummarizationResult}; that is the one point where a result
+ * exists, so the transforms run there and the REWRITTEN result is what gets
+ * yielded — the client and the persisted run record then hold the same object.
+ * An adapter whose stream never emits one still finishes the run, just with no
+ * result recorded.
+ */
+async function* runNativeSummarizeStream(
+  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, true>,
+  stream: AsyncIterable<StreamChunk>,
+  logger: InternalLogger,
+): AsyncIterable<StreamChunk> {
+  const { adapter, middleware, modelOptions } = options
+  const mwCtx = createGenerationContext({
+    requestId: createId('summarize'),
+    activity: 'summarize',
+    provider: adapter.name,
+    model: adapter.model,
+    modelOptions,
+    threadId: options.threadId,
+    runId: options.runId,
+    createId,
+  })
+
+  await runGenerationStart(middleware, mwCtx)
+
+  const startTime = Date.now()
+  // Tracks whether a terminal hook already fired, so the `finally` can report an
+  // abandoned stream without double-firing. Mirrors the streaming video path.
+  let settled = false
+  try {
+    for await (const chunk of stream) {
+      if (chunk.type === 'CUSTOM' && chunk.name === 'generation:result') {
+        const result = await applyGenerationResultTransforms<unknown>(
+          mwCtx,
+          chunk.value,
+        )
+        const usage = usageOf(result)
+        // Finish before yielding the terminal chunks: a consumer that stops
+        // reading once it has the result must not trip the abandonment path.
+        if (usage) await runGenerationUsage(middleware, mwCtx, usage)
+        await runGenerationFinish(middleware, mwCtx, {
+          duration: Date.now() - startTime,
+          usage,
+        })
+        settled = true
+        yield { ...chunk, value: result }
+        continue
+      }
+      yield chunk
+    }
+    if (!settled) {
+      await runGenerationFinish(middleware, mwCtx, {
+        duration: Date.now() - startTime,
+      })
+      settled = true
+    }
   } catch (error) {
+    settled = true
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: Date.now() - startTime,
+    })
     logger.errors('summarize activity failed', {
       error,
       source: 'summarize',
     })
     throw error
+  } finally {
+    if (!settled) {
+      // The consumer abandoned the stream mid-summary, so the generator is being
+      // unwound at a `yield`. Report a cancel, not an error, so an observer ends
+      // its span (and persistence marks the run interrupted) instead of leaving
+      // the run open forever.
+      await runGenerationAbort(middleware, mwCtx, {
+        reason: 'Summarize stream abandoned before completion',
+        duration: Date.now() - startTime,
+      })
+    }
   }
 }
 

package/src/adapter-internals.ts

@@ -15,4 +15,13 @@ export {
   provideSandboxRuntime,
   SandboxRuntimeCapability,
 } from './activities/chat/middleware/sandbox-runtime'
-export type { SandboxRuntime } from './activities/chat/middleware/sandbox-runtime'
+export {
+  getRunDisconnect,
+  provideRunDisconnect,
+  RunDisconnectCapability,
+} from './activities/chat/middleware/run-disconnect'
+export {
+  getPendingTurn,
+  PendingTurnCapability,
+  providePendingTurn,
+} from './activities/chat/middleware/pending-turn'