@tanstack/ai-client 0.23.3 → 0.25.1

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,
@@ -38,6 +39,9 @@ export type {
   ChatInterrupt,
   ChatInterruptState,
   GenericAGUIInterrupt,
+  GenericInterrupt,
+  RegisteredGenericInterrupt,
+  ResolvableChatInterrupt,
   UnboundInterrupt,
   InterruptItemStatus,
   ToolApprovalInterrupt,
@@ -143,6 +147,7 @@ export {
   xhrHttpStream,
   stream,
   rpcStream,
+  webSocket,
   StreamTruncatedError,
   DurableStreamIncompleteError,
   StreamReconnectLimitError,
@@ -155,6 +160,7 @@ export {
   type RunAgentInputContext,
   type StreamConnectionHandlers,
   type SubscribeConnectionAdapter,
+  type WebSocketConnectionOptions,
   type XhrConnectionOptions,
 } from './connection-adapters'