@tanstack/ai-react 0.18.1 → 0.19.1

package/src/use-generation.ts

@@ -8,6 +8,8 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
+  GenerationRestoredResult,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 
@@ -25,12 +27,51 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
   connection?: ConnectConnectionAdapter
   /** Direct async function for one-shot generation (no streaming protocol needed) */
   fetcher?: GenerationFetcher<TInput, TResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /**
+   * How this generation persists across reloads.
+   * - Omit / `false`: ephemeral, in-memory only.
+   * - `true`: server-driven — on mount the client hydrates the last generation
+   *   for its `threadId` from the server (needs a connection with a
+   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
+   */
+  persistence?: boolean
+  /**
+   * The **scope** this generation belongs to: a stable, app-chosen name for the
+   * slot successive runs fill — not a link to a chat conversation.
+   *
+   * The hook starts empty and produces many runs over its life; each gets its
+   * own `runId`, but all belong to one scope. Persistence keys on this, so
+   * derive it from your own domain and keep it identical across reloads (e.g.
+   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
+   * id on the wire, which the protocol requires.
+   *
+   * **Required whenever `persistence` is set** — an app that cannot name the
+   * scope has nothing to restore to. Optional for ephemeral generations, where
+   * it falls back to `id` purely to satisfy the wire.
+   */
+  threadId?: string
+  /**
+   * Server-driven hydration handler for `persistence: true` when the
+   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
+   * `rpcStream()` adapter built without handlers) — typically a one-line
+   * server-function call. The connection's own handler takes precedence.
+   */
+  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
+  /**
+   * Re-attach handler that replays a run still generating to completion on
+   * mount, when the connection doesn't carry one. Without it, a restored
+   * `running` snapshot surfaces as an (interrupted) error. The connection's
+   * own handler takes precedence.
+   */
+  joinRun?: ConnectConnectionAdapter['joinRun']
   /**
    * Callback when a result is received. Can optionally return a transformed value.
    *
@@ -45,16 +86,26 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
   onProgress?: (progress: number, message?: string) => void
   /** Callback for each stream chunk (connect-based adapter mode only) */
   onChunk?: (chunk: StreamChunk) => void
+  /**
+   * @internal Rebuild a typed result from a restored snapshot, injected by each
+   * specialized hook (image / speech / audio / transcription / summarize).
+   * Forwarded to the client so a server-hydrate restore repaints `result`.
+   */
+  reconstructResult?: (restored: GenerationRestoredResult) => TResult | null
 }
 
 /**
  * Return type for the useGeneration hook.
  *
  * @template TOutput - The output type (after optional transform)
+ * @template TInput - The input type accepted by `generate` (defaults to any object)
  */
-export interface UseGenerationReturn<TOutput> {
+export interface UseGenerationReturn<
+  TOutput,
+  TInput extends Record<string, any> = Record<string, any>,
+> {
   /** Trigger a generation request */
-  generate: (input: Record<string, any>) => Promise<void>
+  generate: (input: TInput) => Promise<void>
   /** The generation result, or null if not yet generated */
   result: TOutput | null
   /** Whether a generation is currently in progress */
@@ -67,6 +118,13 @@ export interface UseGenerationReturn<TOutput> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /**
+   * The id of the generation job currently running, or `null` when nothing is in
+   * flight. Each call to `generate` is one job with its own id. Pass it to your
+   * own endpoint to cancel or poll the provider job — `stop()` only aborts the
+   * local stream, it does not stop work already running on the provider.
+   */
+  runId: string | null
 }
 
 /**
@@ -99,21 +157,30 @@ export function useGeneration<
   TResult,
   TTransformed = void,
 >(
-  options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+  options: Omit<
+    UseGenerationOptions<TInput, TResult>,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: TResult) => TTransformed
-  },
-): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>> {
+  } & GenerationPersistenceOptions,
+): UseGenerationReturn<
+  InferGenerationOutputFromReturn<TResult, TTransformed>,
+  TInput
+> {
   type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
   const hookId = useId()
-  const clientId = options.id || hookId
+  // Single identity: prefer `threadId`; deprecated `id` only when no threadId.
+  const clientIdentity = options.threadId ?? options.id ?? hookId
 
   const [result, setResult] = useState<TOutput | null>(null)
   const [isLoading, setIsLoading] = useState(false)
   const [error, setError] = useState<Error | undefined>(undefined)
   const [status, setStatus] = useState<GenerationClientState>('idle')
+  const [runId, setRunId] = useState<string | null>(null)
 
   const optionsRef = useRef(options)
   optionsRef.current = options
+  const disposedRef = useRef(false)
 
   const client = useMemo(() => {
     const opts = optionsRef.current
@@ -122,9 +189,20 @@ export function useGeneration<
     // local source is `Record<string, any> | undefined`). Callbacks
     // wrap optional ones in non-returning bodies so `?.()`'s
     // implicit `undefined` doesn't pollute the function return type.
+    // Identity: pass `threadId` alone when set (never also pass deprecated `id`).
     const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
-      id: clientId,
       body: opts.body,
+      ...(opts.threadId !== undefined
+        ? { threadId: opts.threadId }
+        : { id: opts.id ?? hookId }),
+      ...(opts.persistence !== undefined && { persistence: opts.persistence }),
+      ...(opts.hydrateGeneration !== undefined && {
+        hydrateGeneration: opts.hydrateGeneration,
+      }),
+      ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),
+      ...(opts.reconstructResult
+        ? { reconstructResult: opts.reconstructResult }
+        : {}),
       devtoolsBridgeFactory: createGenerationDevtoolsBridge,
       devtools: {
         hookName: 'useGeneration',
@@ -138,18 +216,29 @@ export function useGeneration<
         result: TResult,
       ) => TOutput | null | void,
       onError: (e: Error) => {
-        optionsRef.current.onError?.(e)
+        if (!disposedRef.current) optionsRef.current.onError?.(e)
       },
       onProgress: (p: number, m?: string) => {
-        optionsRef.current.onProgress?.(p, m)
+        if (!disposedRef.current) optionsRef.current.onProgress?.(p, m)
       },
       onChunk: (c: StreamChunk) => {
-        optionsRef.current.onChunk?.(c)
+        if (!disposedRef.current) optionsRef.current.onChunk?.(c)
+      },
+      onResultChange: (r) => {
+        if (!disposedRef.current) setResult(r)
+      },
+      onLoadingChange: (l) => {
+        if (!disposedRef.current) setIsLoading(l)
+      },
+      onErrorChange: (e) => {
+        if (!disposedRef.current) setError(e)
+      },
+      onStatusChange: (s) => {
+        if (!disposedRef.current) setStatus(s)
+      },
+      onResumeStateChange: (rs) => {
+        if (!disposedRef.current) setRunId(rs?.runId ?? null)
       },
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus,
     }
 
     if (opts.connection) {
@@ -169,7 +258,7 @@ export function useGeneration<
     throw new Error(
       'useGeneration requires either a connection or fetcher option',
     )
-  }, [clientId])
+  }, [clientIdentity, hookId])
 
   // Sync body changes without recreating client
   useEffect(() => {
@@ -179,11 +268,15 @@ export function useGeneration<
     })
   }, [client, options.body])
 
-  // Cleanup on unmount
+  // Mount devtools and clean up on unmount. Generation runs are never
+  // auto-started on mount — persisted state is only displayed. Mounting
+  // revives the client after a StrictMode dispose → remount replay.
   useEffect(() => {
+    disposedRef.current = false
     client.mountDevtools()
 
     return () => {
+      disposedRef.current = true
       client.dispose()
     }
   }, [client])
@@ -204,12 +297,13 @@ export function useGeneration<
   }, [client])
 
   return {
-    generate: generate as (input: Record<string, any>) => Promise<void>,
+    generate,
     result,
     isLoading,
     error,
     status,
     stop,
     reset,
+    runId,
   }
 }

package/src/use-summarize.ts

@@ -1,10 +1,12 @@
 import { useGeneration } from './use-generation'
+import { reconstructSummarizeResult } from '@tanstack/ai-client'
 import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
   SummarizeGenerateInput,
 } from '@tanstack/ai-client'
@@ -19,12 +21,51 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
   connection?: ConnectConnectionAdapter
   /** Direct async function for summarization */
   fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /**
+   * How this generation persists across reloads.
+   * - Omit / `false`: ephemeral, in-memory only.
+   * - `true`: server-driven — on mount the client hydrates the last generation
+   *   for its `threadId` from the server (needs a connection with a
+   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
+   */
+  persistence?: boolean
+  /**
+   * The **scope** this generation belongs to: a stable, app-chosen name for the
+   * slot successive runs fill — not a link to a chat conversation.
+   *
+   * The hook starts empty and produces many runs over its life; each gets its
+   * own `runId`, but all belong to one scope. Persistence keys on this, so
+   * derive it from your own domain and keep it identical across reloads (e.g.
+   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
+   * id on the wire, which the protocol requires.
+   *
+   * **Required whenever `persistence` is set** — an app that cannot name the
+   * scope has nothing to restore to. Optional for ephemeral generations, where
+   * it falls back to `id` purely to satisfy the wire.
+   */
+  threadId?: string
+  /**
+   * Server-driven hydration handler for `persistence: true` when the
+   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
+   * `rpcStream()` adapter built without handlers) — typically a one-line
+   * server-function call. The connection's own handler takes precedence.
+   */
+  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
+  /**
+   * Re-attach handler that replays a run still generating to completion on
+   * mount, when the connection doesn't carry one. Without it, a restored
+   * `running` snapshot surfaces as an (interrupted) error. The connection's
+   * own handler takes precedence.
+   */
+  joinRun?: ConnectConnectionAdapter['joinRun']
   /**
    * Callback when summarization is complete. Can optionally return a transformed value.
    *
@@ -61,6 +102,13 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /**
+   * The id of the generation job currently running, or `null` when nothing is in
+   * flight. Each call to `generate` is one job with its own id. Pass it to your
+   * own endpoint to cancel or poll the provider job — `stop()` only aborts the
+   * local stream, it does not stop work already running on the provider.
+   */
+  runId: string | null
 }
 
 /**
@@ -93,9 +141,12 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
  * ```
  */
 export function useSummarize<TTransformed = void>(
-  options: Omit<UseSummarizeOptions, 'onResult'> & {
+  options: Omit<
+    UseSummarizeOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: SummarizationResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseSummarizeReturn<
   InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
 > {
@@ -105,19 +156,15 @@ export function useSummarize<TTransformed = void>(
     hookName: 'useSummarize',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+    reconstructResult: reconstructSummarizeResult,
+  })
 
-  return {
-    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
-  }
+  return generation
 }

package/src/use-transcription.ts

@@ -1,10 +1,12 @@
 import { useGeneration } from './use-generation'
+import { reconstructTranscriptionResult } from '@tanstack/ai-client'
 import type { StreamChunk, TranscriptionResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
   TranscriptionGenerateInput,
 } from '@tanstack/ai-client'
@@ -19,12 +21,51 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
   connection?: ConnectConnectionAdapter
   /** Direct async function for transcription */
   fetcher?: GenerationFetcher<TranscriptionGenerateInput, TranscriptionResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /**
+   * How this generation persists across reloads.
+   * - Omit / `false`: ephemeral, in-memory only.
+   * - `true`: server-driven — on mount the client hydrates the last generation
+   *   for its `threadId` from the server (needs a connection with a
+   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
+   */
+  persistence?: boolean
+  /**
+   * The **scope** this generation belongs to: a stable, app-chosen name for the
+   * slot successive runs fill — not a link to a chat conversation.
+   *
+   * The hook starts empty and produces many runs over its life; each gets its
+   * own `runId`, but all belong to one scope. Persistence keys on this, so
+   * derive it from your own domain and keep it identical across reloads (e.g.
+   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
+   * id on the wire, which the protocol requires.
+   *
+   * **Required whenever `persistence` is set** — an app that cannot name the
+   * scope has nothing to restore to. Optional for ephemeral generations, where
+   * it falls back to `id` purely to satisfy the wire.
+   */
+  threadId?: string
+  /**
+   * Server-driven hydration handler for `persistence: true` when the
+   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
+   * `rpcStream()` adapter built without handlers) — typically a one-line
+   * server-function call. The connection's own handler takes precedence.
+   */
+  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
+  /**
+   * Re-attach handler that replays a run still generating to completion on
+   * mount, when the connection doesn't carry one. Without it, a restored
+   * `running` snapshot surfaces as an (interrupted) error. The connection's
+   * own handler takes precedence.
+   */
+  joinRun?: ConnectConnectionAdapter['joinRun']
   /**
    * Callback when transcription is complete. Can optionally return a transformed value.
    *
@@ -61,6 +102,13 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /**
+   * The id of the generation job currently running, or `null` when nothing is in
+   * flight. Each call to `generate` is one job with its own id. Pass it to your
+   * own endpoint to cancel or poll the provider job — `stop()` only aborts the
+   * local stream, it does not stop work already running on the provider.
+   */
+  runId: string | null
 }
 
 /**
@@ -98,9 +146,12 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
  * ```
  */
 export function useTranscription<TTransformed = void>(
-  options: Omit<UseTranscriptionOptions, 'onResult'> & {
+  options: Omit<
+    UseTranscriptionOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: TranscriptionResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseTranscriptionReturn<
   InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>
 > {
@@ -110,20 +161,11 @@ export function useTranscription<TTransformed = void>(
     hookName: 'useTranscription',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<
-      TranscriptionGenerateInput,
-      TranscriptionResult,
-      TTransformed
-    >({ ...options, devtools })
+  const generation = useGeneration<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TTransformed
+  >({ ...options, devtools, reconstructResult: reconstructTranscriptionResult })
 
-  return {
-    generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
-  }
+  return generation
 }

package/dist/esm/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/esm/mcp-apps.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp-apps.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}