@tanstack/ai 0.42.0 → 0.43.1

package/src/activities/generateVideo/index.ts

@@ -11,6 +11,7 @@ import { aiEventClient } from '@tanstack/ai-event-client'
 import { toRunErrorPayload } from '../error-payload'
 import { resolveDebugOption } from '../../logger/resolve'
 import {
+  applyGenerationResultTransforms,
   createGenerationContext,
   runGenerationAbort,
   runGenerationError,
@@ -20,11 +21,15 @@ import {
 } from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware/types'
+import type {
+  GenerationMiddleware,
+  GenerationMiddlewareContext,
+} from '../middleware/types'
 import type { VideoAdapter } from './adapter'
 import type {
   MediaPrompt,
   MediaPromptFor,
+  PersistedArtifactRef,
   StreamChunk,
   TokenUsage,
   VideoJobResult,
@@ -175,8 +180,28 @@ export type VideoCreateOptions<
   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
@@ -185,10 +210,29 @@ export type VideoCreateOptions<
   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>
@@ -282,7 +326,7 @@ export type VideoActivityResult<
  *
  * @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
@@ -292,6 +336,14 @@ export type VideoActivityResult<
  * })
  *
  * 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
@@ -324,8 +376,39 @@ export function generateVideo<
   return runCreateVideoJob(options) as VideoActivityResult<'create', TStream>
 }
 
+/**
+ * The run id a non-streaming video job is filed under, derived from the
+ * provider job itself.
+ *
+ * A submit-and-poll run spans two calls in two different requests, so the two
+ * halves need to agree on an id. Deriving it from the `jobId` — the one id a
+ * poller structurally cannot be missing, because it cannot poll without it —
+ * means no correlation state has to survive the boundary and there is no
+ * "forgot to pass the run id" failure to document. The provider is part of the
+ * key so two providers' job-id spaces cannot collide, and both halves are
+ * percent-encoded so the joined string stays unambiguous (and url-safe, since
+ * run ids end up in storage keys and query strings).
+ */
+function videoRunIdForJob(provider: string, jobId: string): string {
+  return `video:${encodeURIComponent(provider)}:${encodeURIComponent(jobId)}`
+}
+
 /**
  * Internal implementation of non-streaming video job creation.
+ *
+ * Submitting a job OPENS a run, it does not complete one: the video does not
+ * exist yet, and the bytes only appear on a later poll. So this fires `onStart`
+ * and runs the result transforms over the submission result — the jobId lands
+ * on the run record, which is what lets a later request resume polling — but
+ * fires NO terminal hook. {@link getVideoJobStatus} finishes the run when the
+ * job settles, keyed on the same derived id.
+ *
+ * `onStart` therefore runs AFTER the submit request: the run's id comes from
+ * the job, which does not exist until the provider accepts it. A submission
+ * that fails has no job, so it opens and immediately fails a run under this
+ * call's `requestId` — terminal and unresumable by construction, but it puts
+ * the failure where a client hydrating the thread will see it instead of
+ * showing nothing.
  */
 async function runCreateVideoJob<
   TAdapter extends VideoAdapter<string, any, any, any, any, any>,
@@ -340,24 +423,35 @@ async function runCreateVideoJob<
     (adapter as { name?: string }).name ??
     'unknown'
 
-  const mwCtx = createGenerationContext({
-    requestId,
-    activity: 'video',
-    provider: adapter.name,
-    model,
-    modelOptions,
-    createId,
-  })
-
-  await runGenerationStart(middleware, mwCtx)
+  // `runId` is resolved per outcome (from the job, or absent on failure), so the
+  // context is built once the outcome is known. `options.runId` is deliberately
+  // not consulted: in non-streaming mode the run id is always the derived one,
+  // the single rule that keeps the two calls in agreement.
+  const contextFor = (runId?: string): GenerationMiddlewareContext =>
+    createGenerationContext({
+      requestId,
+      activity: 'video',
+      provider: adapter.name,
+      model,
+      modelOptions,
+      // Deliberately the CALLER's `threadId` — no minted fallback. A thread id
+      // nobody else knows would file the run in a slot no client could hydrate,
+      // which is worse than no link because it looks like one. Mirrors the
+      // streaming path.
+      threadId: options.threadId,
+      runId,
+      artifactInputs: { prompt },
+      createId,
+    })
 
   logger.request(`activity=generateVideo provider=${providerName}`, {
     provider: providerName,
     model,
   })
 
+  let jobResult: VideoJobResult
   try {
-    const result = await adapter.createVideoJob({
+    jobResult = await adapter.createVideoJob({
       model,
       prompt,
       size,
@@ -365,18 +459,13 @@ async function runCreateVideoJob<
       modelOptions,
       logger,
     })
-    logger.output(`activity=generateVideo jobId=${result.jobId}`, {
-      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, {
+    // No jobId exists, so this run can only be keyed on the request. Start it
+    // just to fail it: `generationRuns.update` on an unknown run id is a no-op
+    // by contract, so without the `onStart` the failure would persist nowhere.
+    const failedCtx = contextFor()
+    await runGenerationStart(middleware, failedCtx)
+    await runGenerationError(middleware, failedCtx, {
       error,
       duration: Date.now() - startTime,
     })
@@ -386,6 +475,18 @@ async function runCreateVideoJob<
     })
     throw error
   }
+
+  logger.output(`activity=generateVideo jobId=${jobResult.jobId}`, {
+    jobId: jobResult.jobId,
+    model: jobResult.model,
+  })
+
+  const mwCtx = contextFor(videoRunIdForJob(adapter.name, jobResult.jobId))
+  await runGenerationStart(middleware, mwCtx)
+  // Transforms see the submission result (no url yet, so nothing to copy into a
+  // blob store) purely so the run record captures the jobId and any prompt
+  // inputs. No finish hook: the run is still running.
+  return await applyGenerationResultTransforms(mwCtx, jobResult)
 }
 
 function sleep(ms: number): Promise<void> {
@@ -412,12 +513,15 @@ async function* runStreamingVideoGeneration<
     (adapter as { name?: string }).name ??
     'unknown'
 
-  const threadId = createId('thread')
+  // The wire needs a thread id on every RUN_* chunk, so one is minted when the
+  // caller passes none — matching `streamGenerationResult`, which the other
+  // activities stream through.
+  const wireThreadId = options.threadId ?? createId('thread')
 
   yield {
     type: 'RUN_STARTED',
     runId,
-    threadId,
+    threadId: wireThreadId,
     timestamp: Date.now(),
   } as StreamChunk
 
@@ -427,6 +531,17 @@ async function* runStreamingVideoGeneration<
     provider: adapter.name,
     model,
     modelOptions,
+    // Identity has to reach the middleware, not just the chunks: persistence
+    // keys the run record on these, and without them it falls back to the
+    // internal `requestId` and records no thread link at all.
+    //
+    // Deliberately the CALLER's `threadId`, never `wireThreadId`: a minted id is
+    // known to nobody, so persisting it would file the run in a slot no client
+    // could ever hydrate — worse than recording no link, because it looks like
+    // one. This mirrors `generateImage`.
+    threadId: options.threadId,
+    runId,
+    artifactInputs: { prompt },
     createId,
   })
 
@@ -459,7 +574,7 @@ async function* runStreamingVideoGeneration<
       name: 'video:job:created',
       value: { jobId: jobResult.jobId },
       timestamp: Date.now(),
-    } as StreamChunk
+    }
 
     // Poll for completion
     const startTime = Date.now()
@@ -478,7 +593,7 @@ async function* runStreamingVideoGeneration<
           error: statusResult.error,
         },
         timestamp: Date.now(),
-      } as StreamChunk
+      }
 
       if (statusResult.status === 'completed') {
         const urlResult = await adapter.getVideoUrl(jobResult.jobId)
@@ -491,6 +606,21 @@ async function* runStreamingVideoGeneration<
           },
         )
 
+        // Run the result transforms before anything observes the result, the
+        // same as every other media activity. This is what lets persistence
+        // copy the video into a blob store, attach its artifact refs, and
+        // rewrite `url` to a durable app-origin one — so the chunk below and
+        // the stored run record carry the SAME urls. Skipping it leaves a
+        // result whose only url is the provider's expiring link.
+        const rawResult = {
+          jobId: jobResult.jobId,
+          status: 'completed' as const,
+          url: urlResult.url,
+          expiresAt: urlResult.expiresAt,
+          ...(urlResult.usage ? { usage: urlResult.usage } : {}),
+        }
+        const result = await applyGenerationResultTransforms(mwCtx, rawResult)
+
         // 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
@@ -506,20 +636,14 @@ async function* runStreamingVideoGeneration<
         yield {
           type: 'CUSTOM',
           name: 'generation:result',
-          value: {
-            jobId: jobResult.jobId,
-            status: 'completed',
-            url: urlResult.url,
-            expiresAt: urlResult.expiresAt,
-            ...(urlResult.usage ? { usage: urlResult.usage } : {}),
-          },
+          value: result,
           timestamp: Date.now(),
-        } as StreamChunk
+        }
 
         yield {
           type: 'RUN_FINISHED',
           runId,
-          threadId,
+          threadId: wireThreadId,
           finishReason: 'stop',
           timestamp: Date.now(),
         } as StreamChunk
@@ -550,7 +674,7 @@ async function* runStreamingVideoGeneration<
     yield {
       type: 'RUN_ERROR',
       runId,
-      threadId,
+      threadId: wireThreadId,
       message: payload.message,
       code: payload.code,
       error: payload,
@@ -570,12 +694,73 @@ async function* runStreamingVideoGeneration<
   }
 }
 
+/**
+ * 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
@@ -594,23 +779,63 @@ async function* runStreamingVideoGeneration<
  *   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 async 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
-}> {
-  const { adapter, jobId } = options
+>(options: VideoJobStatusOptions<TAdapter>): Promise<VideoJobStatusResult> {
+  const { adapter, jobId, middleware } = options
   const requestId = createId('video-status')
   const startTime = Date.now()
 
+  // Built per call but only USED on a terminal poll — `onStart` is what
+  // registers the result transforms, so it has to run in the same call that
+  // applies them.
+  const terminalContext = (): GenerationMiddlewareContext =>
+    createGenerationContext({
+      requestId,
+      activity: 'video',
+      provider: adapter.name,
+      model: adapter.model,
+      threadId: options.threadId,
+      // Recomputed, never passed in: the submitting call derived the same id
+      // from the same provider + job, so the two halves agree without the
+      // caller carrying anything but the jobId they must already have.
+      runId: videoRunIdForJob(adapter.name, jobId),
+      // Deliberately no `artifactInputs`: the submission already persisted any
+      // prompt inputs under this run, and passing them again would store a
+      // second copy of every input image.
+      createId,
+    })
+
   aiEventClient.emit('video:request:started', {
     requestId,
     provider: adapter.name,
@@ -625,34 +850,12 @@ export async function getVideoJobStatus<
 
   // If completed, also get the URL
   if (statusResult.status === 'completed') {
+    let urlResult: VideoUrlResult
+    // Scoped tightly to the provider call: a middleware hook that throws must
+    // surface as itself, not be relabelled "failed to get video URL" and then
+    // re-reported to the very middleware that threw.
     try {
-      const urlResult = await adapter.getVideoUrl(jobId)
-      aiEventClient.emit('video:request:completed', {
-        requestId,
-        provider: adapter.name,
-        model: adapter.model,
-        requestType: 'status',
-        jobId,
-        status: statusResult.status,
-        progress: statusResult.progress,
-        url: urlResult.url,
-        duration: Date.now() - startTime,
-        timestamp: Date.now(),
-      })
-      if (urlResult.usage) {
-        aiEventClient.emit('video:usage', {
-          requestId,
-          model: adapter.model,
-          usage: urlResult.usage,
-          timestamp: Date.now(),
-        })
-      }
-      return {
-        status: statusResult.status,
-        progress: statusResult.progress,
-        url: urlResult.url,
-        ...(urlResult.usage ? { usage: urlResult.usage } : {}),
-      }
+      urlResult = await adapter.getVideoUrl(jobId)
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : 'Failed to get video URL'
@@ -668,13 +871,63 @@ export async function getVideoJobStatus<
         duration: Date.now() - startTime,
         timestamp: Date.now(),
       })
-      // Provider reported completed but result fetch failed — treat as failed
+      // Provider reported completed but result fetch failed — treat as failed,
+      // and fail the run with it: the job is terminal, so nothing later will.
+      await runGenerationError(middleware, terminalContext(), {
+        error,
+        duration: Date.now() - startTime,
+      })
       return {
+        jobId,
         status: 'failed' as const,
         progress: statusResult.progress,
         error: errorMessage,
       }
     }
+
+    aiEventClient.emit('video:request:completed', {
+      requestId,
+      provider: adapter.name,
+      model: adapter.model,
+      requestType: 'status',
+      jobId,
+      status: statusResult.status,
+      progress: statusResult.progress,
+      url: urlResult.url,
+      duration: Date.now() - startTime,
+      timestamp: Date.now(),
+    })
+    if (urlResult.usage) {
+      aiEventClient.emit('video:usage', {
+        requestId,
+        model: adapter.model,
+        usage: urlResult.usage,
+        timestamp: Date.now(),
+      })
+    }
+
+    const mwCtx = terminalContext()
+    await runGenerationStart(middleware, mwCtx)
+    const result = await applyGenerationResultTransforms<VideoJobStatusResult>(
+      mwCtx,
+      {
+        jobId,
+        status: 'completed',
+        ...(statusResult.progress !== undefined
+          ? { progress: statusResult.progress }
+          : {}),
+        url: urlResult.url,
+        ...(urlResult.expiresAt ? { expiresAt: urlResult.expiresAt } : {}),
+        ...(urlResult.usage ? { usage: urlResult.usage } : {}),
+      },
+    )
+    if (urlResult.usage)
+      await runGenerationUsage(middleware, mwCtx, urlResult.usage)
+    await runGenerationFinish(middleware, mwCtx, {
+      duration: Date.now() - startTime,
+      usage: urlResult.usage,
+    })
+    return result
   }
 
   aiEventClient.emit('video:request:completed', {
@@ -690,8 +943,18 @@ export async function getVideoJobStatus<
     timestamp: Date.now(),
   })
 
+  // A failed job is terminal for the run too: without this the record would sit
+  // at `running` forever, indistinguishable from a job still being worked on.
+  if (statusResult.status === 'failed') {
+    await runGenerationError(middleware, terminalContext(), {
+      error: new Error(statusResult.error || 'Video generation failed'),
+      duration: Date.now() - startTime,
+    })
+  }
+
   // Return status for non-completed jobs
   return {
+    jobId,
     status: statusResult.status,
     progress: statusResult.progress,
     error: statusResult.error,

package/src/activities/middleware/index.ts

@@ -9,6 +9,8 @@ export type {
   GenerationAbortInfo,
   GenerationErrorInfo,
   AnyGenerationMiddleware,
+  GenerationResultTransform,
+  GenerationResultTransformContext,
 } from './types'
 export {
   createGenerationContext,

package/src/activities/middleware/run.ts

@@ -4,6 +4,7 @@ import type {
   GenerationFinishInfo,
   GenerationMiddleware,
   GenerationMiddlewareContext,
+  GenerationResultTransformContext,
   GenerationUsageInfo,
 } from './types'
 
@@ -19,6 +20,9 @@ export function createGenerationContext(args: {
   provider: string
   model: string
   modelOptions?: unknown
+  threadId?: string
+  runId?: string
+  artifactInputs?: unknown
   createId: (prefix: string) => string
 }): GenerationMiddlewareContext {
   return {
@@ -27,9 +31,13 @@ export function createGenerationContext(args: {
     provider: args.provider,
     model: args.model,
     modelOptions: args.modelOptions,
+    threadId: args.threadId,
+    runId: args.runId,
     source: 'server',
     createId: args.createId,
     context: undefined,
+    resultTransforms: [],
+    artifactInputs: args.artifactInputs,
   }
 }
 
@@ -86,3 +94,26 @@ export function runGenerationError(
 ): Promise<void> {
   return run(middleware, (mw) => mw.onError?.(ctx, info))
 }
+
+/**
+ * Apply the result transforms middleware registered on the context, in order,
+ * to the raw adapter result. Each transform may return a replacement result or
+ * `undefined` to leave it unchanged. Runs after the adapter result exists and
+ * before the final result is returned or streamed.
+ */
+export async function applyGenerationResultTransforms<TResult>(
+  ctx: GenerationMiddlewareContext,
+  result: TResult,
+): Promise<TResult> {
+  let current = result
+  const transformCtx: GenerationResultTransformContext = { middleware: ctx }
+
+  for (const transform of ctx.resultTransforms ?? []) {
+    const transformed = await transform(current, transformCtx)
+    if (transformed !== undefined) {
+      current = transformed as TResult
+    }
+  }
+
+  return current
+}