@tanstack/ai-client 0.23.2 → 0.24.0

package/src/generation-client.ts

@@ -26,9 +26,11 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   GenerationRestoredResult,
   GenerationResumeSnapshot,
   GenerationResumeState,
+  GenerationTransport,
 } from './generation-types'
 
 /**
@@ -108,10 +110,10 @@ export class GenerationClient<
   private readonly joinRunHandler:
     | ConnectConnectionAdapter['joinRun']
     | undefined
-  private readonly uniqueId: string
+  private uniqueId: string
   private readonly devtoolsMetadata: AIDevtoolsClientMetadata
   private readonly devtoolsBridge: GenerationDevtoolsBridge<TOutput>
-  private readonly threadId: string
+  private threadId: string
   private readonly persistenceScope: string | undefined
   // Server-driven mode (`persistence: true`): no local snapshot store; on mount
   // the client hydrates the last generation for `threadId` from the server.
@@ -133,26 +135,20 @@ export class GenerationClient<
   private serverHydrationStarted = false
 
   constructor(
-    options: GenerationClientOptions<TInput, TResult, TOutput> &
-      (
-        | { connection: ConnectConnectionAdapter; fetcher?: never }
-        | {
-            fetcher: GenerationFetcher<TInput, TResult>
-            connection?: never
-          }
-      ),
+    options: Omit<
+      GenerationClientOptions<TInput, TResult, TOutput>,
+      'persistence' | 'threadId'
+    > &
+      GenerationPersistenceOptions &
+      GenerationTransport<TInput, TResult>,
   ) {
-    // `threadId` is the single identity. Deprecated `id` is only a fallback
-    // when no threadId is given (ephemeral runs / legacy call sites).
-    this.uniqueId =
-      options.threadId ?? options.id ?? this.generateUniqueId('generation')
-    // AG-UI requires a thread id on every run, so fall back to uniqueId. The
-    // generated fallback is for the WIRE ONLY: it is not stable across reloads,
-    // so persistence must never key on it — see `persistenceScope` below.
-    this.threadId = options.threadId ?? this.uniqueId
-    // The persistence scope: the explicit `threadId` and nothing else. The
-    // types require it whenever `persistence` is set; this field keeps the
-    // fallback from silently becoming a storage key for JS callers.
+    // `threadId` is the only identity. Do not mint a random id during
+    // construct: hooks build this client during render.
+    this.threadId = options.threadId ?? ''
+    this.uniqueId = this.threadId
+    // The persistence scope is the explicit `threadId` and nothing else.
+    // The types require it whenever `persistence` is set. This field keeps a
+    // generated wire id from becoming a storage key for JS callers.
     this.persistenceScope = options.threadId
     this.connection = options.connection
     this.fetcher = options.fetcher
@@ -199,10 +195,17 @@ export class GenerationClient<
   }
 
   private buildDevtoolsBridgeOptions(): GenerationDevtoolsBridgeOptions<TOutput> {
+    const client = this
     return {
-      hookId: this.uniqueId,
-      clientId: this.uniqueId,
-      threadId: this.threadId,
+      get hookId() {
+        return client.uniqueId
+      },
+      get clientId() {
+        return client.uniqueId
+      },
+      get threadId() {
+        return client.threadId
+      },
       metadata: this.devtoolsMetadata,
       getCoreState: () => ({
         input: this.input,
@@ -216,6 +219,7 @@ export class GenerationClient<
   }
 
   mountDevtools(): void {
+    this.ensureThreadId()
     // Mounting revives a disposed client. Framework hooks call this from
     // their mount effect, so a dispose → remount cycle (e.g. React
     // StrictMode's mount → cleanup → mount replay against the same memoized
@@ -629,6 +633,14 @@ export class GenerationClient<
     }
   }
 
+  private ensureThreadId(): string {
+    if (!this.threadId) {
+      this.threadId = this.generateUniqueId('generation')
+    }
+    this.uniqueId = this.threadId
+    return this.threadId
+  }
+
   private generateUniqueId(prefix: string): string {
     return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
   }

package/src/generation-types.ts

@@ -201,27 +201,23 @@ export interface GenerationResumeSnapshot {
 }
 
 /**
- * The `persistence` / `threadId` / `id` identity shared by every generation hook.
+ * The `persistence` / `threadId` identity shared by every generation hook.
  *
  * Turning persistence on **requires** a `threadId`, the stable scope runs are
  * filed under. Without one the client would hydrate by a generated id that
  * changes every reload, so nothing would ever restore; making it a type error
  * means the compiler asks for the scope instead of the runtime inventing one.
  *
- * `threadId` is the single identity for the hook, the AG-UI wire thread, and
- * persistence. Legacy `id` is deprecated and typed `never` whenever
- * `threadId` is supplied — pass one scope, not two.
+ * `threadId` is the only identity for the hook, the AG-UI wire thread, and
+ * persistence. There is no separate instance `id`.
  *
- * Ephemeral generations (no `persistence`, or `persistence: false`) may still
- * pass a deprecated `id` when they have no `threadId`, as a wire/devtools
- * fallback. Prefer giving them a `threadId` instead.
- *
- * USAGE: intersect this onto a hook's parameter and subtract the three keys
- * from the options interface, leaving that interface a plain (non-union)
+ * USAGE: intersect this onto a hook's parameter and subtract `persistence`
+ * and `threadId` from the options interface (plus any other keys the hook
+ * redeclares, such as `onResult`), leaving that interface a plain (non-union)
  * object so `Pick` / `Omit` composition elsewhere keeps working:
  *
  * ```ts
- * options: Omit<UseGenerateImageOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
+ * options: Omit<UseGenerateImageOptions, 'onResult' | 'persistence' | 'threadId'> & {
  *   onResult?: (result: ImageGenerationResult) => TTransformed
  * } & GenerationPersistenceOptions
  * ```
@@ -233,31 +229,13 @@ export interface GenerationResumeSnapshot {
 export type GenerationPersistenceOptions =
   | {
       persistence: true
-      /** Required by `persistence` — the stable scope runs are filed under. */
-      threadId: string
-      /**
-       * @deprecated Prefer `threadId`. Not allowed when `threadId` is set —
-       * `threadId` is the single identity for the hook, the wire, and persistence.
-       */
-      id?: never
-    }
-  | {
-      persistence?: false | undefined
-      /** Stable scope for the generation slot (also the wire / devtools identity). */
+      /** Required by `persistence`. The stable scope runs are filed under. */
       threadId: string
-      /**
-       * @deprecated Prefer `threadId`. Not allowed when `threadId` is set.
-       */
-      id?: never
     }
   | {
       persistence?: false | undefined
-      threadId?: undefined
-      /**
-       * @deprecated Prefer `threadId` as the single identity. Only allowed when
-       * `threadId` is omitted — legacy wire/devtools fallback for ephemeral runs.
-       */
-      id?: string
+      /** Stable scope for the generation slot (also the wire / DevTools identity). */
+      threadId?: string
     }
 
 // ===========================
@@ -330,28 +308,19 @@ export type GenerationTransport<TInput, TResult> =
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention -- _TInput is unused in the interface body but part of the public positional generic API (callers supply it for inference)
 export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
-  /**
-   * @deprecated Prefer {@link GenerationClientOptions.threadId}. Legacy instance
-   * id used only as a wire/devtools fallback when `threadId` is omitted. When
-   * both are passed, `threadId` wins and `id` is ignored. Framework hooks type
-   * `id` as `never` whenever `threadId` is set — see
-   * {@link GenerationPersistenceOptions}.
-   */
-  id?: string
-
   /**
    * The **scope** this generation belongs to: a stable, app-chosen name for the
    * slot successive runs fill, not a link to a chat conversation. This is the
-   * single identity for the client — wire thread id, devtools hook id, and
+   * only identity for the client: wire thread id, DevTools hook id, and
    * persistence key.
    *
-   * A generation hook starts empty and produces many runs over its life — each
+   * A generation hook starts empty and produces many runs over its life. Each
    * run gets its own `runId`, but they all belong to one scope. Persistence
    * keys on this: server-driven hydrates the last run for it on mount. It is
    * also sent as the AG-UI thread id on the wire, since the protocol requires
    * one.
    *
-   * Derive it from your own domain — it must be meaningful before any media
+   * Derive it from your own domain. It must be meaningful before any media
    * exists and identical after a reload:
    *
    * ```ts
@@ -360,9 +329,8 @@ export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
    *
    * **Required whenever `persistence` is set.** An app that cannot name the
    * scope has nothing to restore *to*, and a generated fallback would key each
-   * reload differently — silently restoring nothing. Optional only for
-   * ephemeral runs, where it falls back to deprecated `id` (or a generated id)
-   * purely to satisfy the wire and nothing is written.
+   * reload differently, silently restoring nothing. Optional only for
+   * ephemeral runs. If omitted, the client mints a wire id after mount.
    */
   threadId?: string
 

package/src/index.ts

@@ -30,6 +30,7 @@ export type {
   ChatClientPersistence,
   ChatPersistedState,
   ChatPersistenceOption,
+  ChatPersistenceOptions,
   ChatStorageAdapter,
   ChatClientOptions,
   ChatPendingInterrupt,
@@ -143,6 +144,7 @@ export {
   xhrHttpStream,
   stream,
   rpcStream,
+  webSocket,
   StreamTruncatedError,
   DurableStreamIncompleteError,
   StreamReconnectLimitError,
@@ -155,6 +157,7 @@ export {
   type RunAgentInputContext,
   type StreamConnectionHandlers,
   type SubscribeConnectionAdapter,
+  type WebSocketConnectionOptions,
   type XhrConnectionOptions,
 } from './connection-adapters'
 

package/src/types.ts

@@ -628,6 +628,36 @@ export type ChatPersistenceOption<
   TTools extends ReadonlyArray<AnyClientTool> = any,
 > = boolean | ChatClientPersistence<TTools>
 
+/**
+ * The `persistence` / `threadId` pairing for `ChatClient` and the chat hooks.
+ *
+ * Persistence that is on (`true` or a storage adapter) requires a `threadId`.
+ * A minted id changes every reload, so nothing would restore. The compiler
+ * asks for the conversation id instead.
+ *
+ * Omit `persistence`, or set it to `false`, and `threadId` stays optional.
+ * The client then mints one after mount for the wire and DevTools.
+ *
+ * Intersect this onto `ChatClientOptions`. Do not apply a later plain `Omit`
+ * to that type: it collapses the union and the requirement disappears. Use
+ * {@link DistributedOmit}.
+ */
+export type ChatPersistenceOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> =
+  | {
+      persistence: true
+      threadId: string
+    }
+  | {
+      persistence: ChatClientPersistence<TTools>
+      threadId: string
+    }
+  | {
+      persistence?: false | undefined
+      threadId?: string
+    }
+
 type IsUnknown<T> = unknown extends T
   ? [T] extends [unknown]
     ? true
@@ -718,43 +748,6 @@ export interface ChatClientBaseOptions<
    */
   initialMessages?: Array<UIMessage<TTools>>
 
-  /**
-   * How this chat persists across reloads. See {@link ChatPersistenceOption}.
-   *
-   * - Omit or `false`: ephemeral, in-memory only.
-   * - `true`: server-authoritative. The client caches nothing and hydrates the
-   *   thread from the server by its `threadId` on mount (needs a connection with
-   *   a `hydrate` handler). Big transcripts never touch the browser, and the same
-   *   thread opens the same way on another device.
-   * - a {@link ChatClientPersistence} adapter: client-authoritative. The combined
-   *   {@link ChatPersistedState} record (transcript plus resume pointer) is cached
-   *   in the browser, restoring the transcript, pending interrupts, and an
-   *   in-flight run on reload.
-   *
-   * Use `initialResumeSnapshot` for a host-supplied in-memory rehydrate instead.
-   */
-  persistence?: ChatPersistenceOption<TTools>
-
-  /**
-   * Optional storage-key override for this chat instance, and the devtools
-   * instance id. Persistence keys on `threadId` by default; set `id` only when
-   * you need the persisted record keyed separately from the wire thread.
-   * Prefer a stable `threadId` for the common case.
-   *
-   * The framework hooks (`useChat` / `createChat`) do NOT expose `id`: a hook's
-   * identity is its `threadId`. This lower-level escape hatch exists only for
-   * direct `ChatClient` construction.
-   */
-  id?: string
-
-  /**
-   * The conversation id for this chat, stable across sends and reloads. It is
-   * the AG-UI thread key on the wire AND the key client persistence stores the
-   * conversation under, so set a stable `threadId` to have a reload restore the
-   * same conversation. If omitted, a unique thread id is generated per session.
-   */
-  threadId?: string
-
   /**
    * Initial resumable run state, useful when rehydrating a persisted client
    * after a full page reload. This restores the client-side interrupt
@@ -932,14 +925,16 @@ export interface ChatClientBaseOptions<
 
 /**
  * Options for `ChatClient`. Exactly one of `connection` or `fetcher` must be
- * provided — the type-level XOR is enforced via `ChatTransport`.
+ * provided — the type-level XOR is enforced via `ChatTransport`. Persistence
+ * that is on requires a `threadId` via {@link ChatPersistenceOptions}.
  */
 export type ChatClientOptions<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = InferredClientContext<TTools>,
 > = DistributedOmit<ChatClientBaseOptions<TTools, TContext>, 'context'> &
   ClientContextOptionFromTools<TTools, TContext> &
-  ChatTransport
+  ChatTransport &
+  ChatPersistenceOptions<TTools>
 
 export interface ChatRequestBody {
   messages: Array<ModelMessage>

package/src/video-generation-client.ts

@@ -25,8 +25,10 @@ import type {
 import type {
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   GenerationResumeSnapshot,
   GenerationResumeState,
+  GenerationTransport,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoGenerationClientOptions,
@@ -111,10 +113,10 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private readonly fetcher:
     | GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
     | undefined
-  private readonly uniqueId: string
+  private uniqueId: string
   private readonly devtoolsMetadata: AIDevtoolsClientMetadata
   private readonly devtoolsBridge: VideoDevtoolsBridge<TOutput>
-  private readonly threadId: string
+  private threadId: string
   // Server-driven mode (`persistence: true`): no local snapshot store; on mount
   // the client hydrates the last generation for `threadId` from the server.
   private readonly serverDriven: boolean = false
@@ -137,22 +139,17 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private serverHydrationStarted = false
 
   constructor(
-    options: VideoGenerationClientOptions<TOutput> &
-      (
-        | { connection: ConnectConnectionAdapter; fetcher?: never }
-        | {
-            fetcher: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
-            connection?: never
-          }
-      ),
+    options: Omit<
+      VideoGenerationClientOptions<TOutput>,
+      'persistence' | 'threadId'
+    > &
+      GenerationPersistenceOptions &
+      GenerationTransport<VideoGenerateInput, VideoGenerateResult>,
   ) {
-    // `threadId` is the single identity. Deprecated `id` is only a fallback
-    // when no threadId is given (ephemeral runs / legacy call sites).
-    this.uniqueId =
-      options.threadId ?? options.id ?? this.generateUniqueId('video')
-    // The wire/hydration thread key. Server-driven mode needs a stable key, so
-    // prefer an explicit `threadId`, then legacy `id`, then a generated id.
-    this.threadId = options.threadId ?? this.uniqueId
+    // `threadId` is the only identity. Do not mint a random id during
+    // construct: hooks build this client during render.
+    this.threadId = options.threadId ?? ''
+    this.uniqueId = this.threadId
     this.connection = options.connection
     this.fetcher = options.fetcher
     this.hydrateGenerationHandler = options.hydrateGeneration
@@ -192,10 +189,17 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   }
 
   private buildDevtoolsBridgeOptions(): VideoDevtoolsBridgeOptions<TOutput> {
+    const client = this
     return {
-      hookId: this.uniqueId,
-      clientId: this.uniqueId,
-      threadId: this.threadId,
+      get hookId() {
+        return client.uniqueId
+      },
+      get clientId() {
+        return client.uniqueId
+      },
+      get threadId() {
+        return client.threadId
+      },
       metadata: this.devtoolsMetadata,
       getCoreState: () => ({
         input: this.input,
@@ -211,6 +215,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   }
 
   mountDevtools(): void {
+    this.ensureThreadId()
     // Mounting revives a disposed client. Framework hooks call this from
     // their mount effect, so a dispose → remount cycle (e.g. React
     // StrictMode's mount → cleanup → mount replay against the same memoized
@@ -677,6 +682,14 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     }
   }
 
+  private ensureThreadId(): string {
+    if (!this.threadId) {
+      this.threadId = this.generateUniqueId('video')
+    }
+    this.uniqueId = this.threadId
+    return this.threadId
+  }
+
   private generateUniqueId(prefix: string): string {
     return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
   }