@tanstack/ai-client 0.31.0 → 0.32.0

package/src/connection-adapters.ts

@@ -531,12 +531,48 @@ function errorFromXhrStatus(xhr: XMLHttpRequest): Error {
   return new Error(`XHR error! status: ${xhr.status} ${xhr.statusText}`)
 }
 
+function chatHydrationSearchParams(
+  threadId: string,
+  options?: ChatHydrateOptions,
+): Record<string, string> {
+  const values: Record<string, string> = { threadId }
+  if (options?.limit !== undefined) {
+    values.limit = String(options.limit)
+  }
+  if (options?.before !== undefined) {
+    values.before = options.before
+  }
+  return values
+}
+
+function readChatHydrationPage(
+  value: unknown,
+): { truncated: false } | { truncated: true; cursor: string } {
+  if (value === null || typeof value !== 'object') {
+    return { truncated: false }
+  }
+  if (!('truncated' in value) || value.truncated !== true) {
+    return { truncated: false }
+  }
+  if (
+    !('cursor' in value) ||
+    typeof value.cursor !== 'string' ||
+    value.cursor === ''
+  ) {
+    return { truncated: false }
+  }
+  return { truncated: true, cursor: value.cursor }
+}
+
 /**
  * GET the hydration endpoint for a thread and parse its JSON `{ messages,
  * activeRun }` body. This is the transport-agnostic reconnect probe: keyed on
  * the STABLE thread id, it returns the stored transcript and — if a run is still
  * generating — a cursor the caller tails via `joinRun`. Shared by every fetch/
  * XHR adapter so the client never has to know which transport is in use.
+ *
+ * Pass `limit` / `before` to page. Old servers that omit `page` are treated as
+ * a full list (`truncated: false`).
  */
 async function fetchThreadHydration(
   fetchClient: typeof globalThis.fetch,
@@ -544,12 +580,16 @@ async function fetchThreadHydration(
   headers: Record<string, string>,
   credentials: RequestCredentials,
   threadId: string,
+  options?: ChatHydrateOptions,
 ): Promise<ChatHydrationResult> {
-  const response = await fetchClient(withSearchParams(url, { threadId }), {
-    method: 'GET',
-    headers: { Accept: 'application/json', ...headers },
-    credentials,
-  })
+  const response = await fetchClient(
+    withSearchParams(url, chatHydrationSearchParams(threadId, options)),
+    {
+      method: 'GET',
+      headers: { Accept: 'application/json', ...headers },
+      credentials,
+    },
+  )
   await assertResponseOk(response)
   const data = (await response.json()) as {
     messages?: Array<UIMessage>
@@ -558,6 +598,7 @@ async function fetchThreadHydration(
       runId?: unknown
       pending?: unknown
     } | null
+    page?: unknown
   }
   const activeRun =
     data.activeRun && typeof data.activeRun.runId === 'string'
@@ -579,6 +620,7 @@ async function fetchThreadHydration(
       : [],
     activeRun,
     interrupts,
+    page: readChatHydrationPage(data.page),
   }
 }
 
@@ -881,7 +923,10 @@ export interface ConnectConnectionAdapter {
    * `fetchServerSentEvents` / `fetchHttpStream`, and on `stream()` /
    * `rpcStream()` when supplied via {@link StreamConnectionHandlers}.
    */
-  hydrate?: (threadId: string) => Promise<ChatHydrationResult>
+  hydrate?: (
+    threadId: string,
+    options?: ChatHydrateOptions,
+  ) => Promise<ChatHydrationResult>
 }
 
 /**
@@ -911,11 +956,23 @@ export interface GenerationHydrationResult {
   activeRun: { runId: string } | null
 }
 
+/**
+ * Optional paging for a chat hydrate GET.
+ * Omit both fields to load the full thread.
+ */
+export interface ChatHydrateOptions {
+  limit?: number
+  before?: string
+}
+
 /**
  * Server-resolved hydration for a thread. `messages` is the stored transcript;
  * `activeRun` is a cursor to a run still generating for the thread (or `null`).
  * Keyed on the STABLE thread id — the client never handles a run id, so a turn
  * that spans several runs (interrupt/tool continuations) reconnects correctly.
+ *
+ * `page` is additive. Old servers omit it; treat that as a full list
+ * (`truncated: false`).
  */
 export interface ChatHydrationResult {
   messages: Array<UIMessage>
@@ -929,6 +986,11 @@ export interface ChatHydrationResult {
     runId: string
     pending: Array<ChatPendingInterrupt>
   } | null
+  /**
+   * Whether this window is a slice of a longer thread.
+   * `cursor` is set when `truncated` is true and is sent back as `before`.
+   */
+  page?: { truncated: false } | { truncated: true; cursor: string }
 }
 
 /**
@@ -952,7 +1014,10 @@ export interface ResumableConnectConnectionAdapter extends ConnectConnectionAdap
    * JSON GET (`?threadId`), so it is transport-agnostic regardless of how the
    * delivery stream is served.
    */
-  hydrate?: (threadId: string) => Promise<ChatHydrationResult>
+  hydrate?: (
+    threadId: string,
+    options?: ChatHydrateOptions,
+  ) => Promise<ChatHydrationResult>
 }
 
 export interface SubscribeConnectionAdapter {
@@ -984,7 +1049,10 @@ export interface SubscribeConnectionAdapter {
    * cursor). Present only when the underlying connection supports it. The client
    * calls it on mount to re-hydrate without any app-side loader or prop.
    */
-  hydrate?: (threadId: string) => Promise<ChatHydrationResult>
+  hydrate?: (
+    threadId: string,
+    options?: ChatHydrateOptions,
+  ) => Promise<ChatHydrationResult>
 }
 
 /**
@@ -1042,6 +1110,7 @@ export function normalizeConnectionAdapter(
   // Legacy connect() wrapper
   let activeBuffer: Array<StreamChunk> = []
   let activeWaiters: Array<(chunk: StreamChunk | null) => void> = []
+  let activeSubscriber: typeof activeWaiters | undefined
 
   function push(chunk: StreamChunk, runId?: string): void {
     if (runId) {
@@ -1062,18 +1131,16 @@ export function normalizeConnectionAdapter(
     // previous chunk has left processIncomingChunk. Empty waiters with an
     // empty buffer is in-flight delivery, not idle.
     const idle = () =>
-      activeBuffer.length === 0 &&
-      (activeWaiters.length > 0 || abortSignal?.aborted)
+      activeSubscriber !== activeWaiters ||
+      (activeBuffer.length === 0 &&
+        (activeWaiters.length > 0 || abortSignal?.aborted))
     for (let i = 0; i < 16 && !abortSignal?.aborted; i++) {
       if (idle()) return
       await Promise.resolve()
     }
-    let macrotaskWaits = 0
     while (!abortSignal?.aborted) {
       if (idle()) return
       await new Promise<void>((resolve) => setTimeout(resolve, 0))
-      macrotaskWaits++
-      if (activeWaiters.length === 0 && macrotaskWaits >= 32) return
     }
   }
 
@@ -1087,22 +1154,27 @@ export function normalizeConnectionAdapter(
       activeWaiters = myWaiters
 
       return (async function* () {
-        while (!abortSignal?.aborted) {
-          let chunk: StreamChunk | null
-          const buffered = myBuffer.shift()
-          if (buffered !== undefined) {
-            chunk = buffered
-          } else {
-            chunk = await new Promise<StreamChunk | null>((resolve) => {
-              const onAbort = () => resolve(null)
-              myWaiters.push((c) => {
-                abortSignal?.removeEventListener('abort', onAbort)
-                resolve(c)
+        activeSubscriber = myWaiters
+        try {
+          while (!abortSignal?.aborted) {
+            let chunk: StreamChunk | null
+            const buffered = myBuffer.shift()
+            if (buffered !== undefined) {
+              chunk = buffered
+            } else {
+              chunk = await new Promise<StreamChunk | null>((resolve) => {
+                const onAbort = () => resolve(null)
+                myWaiters.push((c) => {
+                  abortSignal?.removeEventListener('abort', onAbort)
+                  resolve(c)
+                })
+                abortSignal?.addEventListener('abort', onAbort, { once: true })
               })
-              abortSignal?.addEventListener('abort', onAbort, { once: true })
-            })
+            }
+            if (chunk !== null) yield chunk
           }
-          if (chunk !== null) yield chunk
+        } finally {
+          if (activeSubscriber === myWaiters) activeSubscriber = undefined
         }
       })()
     },
@@ -1205,7 +1277,10 @@ export function normalizeConnectionAdapter(
       // (no non-null assertion). Present only when the connection supports it.
       const hydrate = (connection as ResumableConnectConnectionAdapter).hydrate
       return typeof hydrate === 'function'
-        ? { hydrate: (threadId: string) => hydrate(threadId) }
+        ? {
+            hydrate: (threadId: string, options?: ChatHydrateOptions) =>
+              hydrate(threadId, options),
+          }
         : {}
     })(),
   }
@@ -1419,7 +1494,7 @@ export function fetchServerSentEvents(
         resolvedOptions.reconnect,
       )
     },
-    async hydrate(threadId) {
+    async hydrate(threadId, hydrateOptions) {
       const resolvedUrl = typeof url === 'function' ? url() : url
       const resolvedOptions =
         typeof options === 'function' ? await options() : options
@@ -1429,6 +1504,7 @@ export function fetchServerSentEvents(
         mergeHeaders(resolvedOptions.headers),
         resolvedOptions.credentials || 'same-origin',
         threadId,
+        hydrateOptions,
       )
     },
     async hydrateGeneration(threadId) {
@@ -1575,7 +1651,7 @@ export function fetchHttpStream(
         resolvedOptions.reconnect,
       )
     },
-    async hydrate(threadId) {
+    async hydrate(threadId, hydrateOptions) {
       const resolvedUrl = typeof url === 'function' ? url() : url
       const resolvedOptions =
         typeof options === 'function' ? await options() : options
@@ -1585,6 +1661,7 @@ export function fetchHttpStream(
         mergeHeaders(resolvedOptions.headers),
         resolvedOptions.credentials || 'same-origin',
         threadId,
+        hydrateOptions,
       )
     },
     async hydrateGeneration(threadId) {
@@ -1913,7 +1990,7 @@ export function xhrServerSentEvents(
         resolvedOptions.reconnect,
       )
     },
-    async hydrate(threadId) {
+    async hydrate(threadId, hydrateOptions) {
       const resolvedUrl = typeof url === 'function' ? url() : url
       const resolvedOptions = await resolveXhrConnectionOptions(options)
       // Hydration is a non-streaming JSON GET, so fetch is fine even for the
@@ -1924,6 +2001,7 @@ export function xhrServerSentEvents(
         mergeHeaders(resolvedOptions.headers),
         resolvedOptions.withCredentials ? 'include' : 'same-origin',
         threadId,
+        hydrateOptions,
       )
     },
     async hydrateGeneration(threadId) {
@@ -1996,7 +2074,7 @@ export function xhrHttpStream(
         resolvedOptions.reconnect,
       )
     },
-    async hydrate(threadId) {
+    async hydrate(threadId, hydrateOptions) {
       const resolvedUrl = typeof url === 'function' ? url() : url
       const resolvedOptions = await resolveXhrConnectionOptions(options)
       // Hydration is a non-streaming JSON GET, so fetch is fine even for the
@@ -2007,6 +2085,7 @@ export function xhrHttpStream(
         mergeHeaders(resolvedOptions.headers),
         resolvedOptions.withCredentials ? 'include' : 'same-origin',
         threadId,
+        hydrateOptions,
       )
     },
     async hydrateGeneration(threadId) {
@@ -2447,7 +2526,10 @@ export interface StreamConnectionHandlers {
    * Server-driven chat hydration for `persistence: true`: the stored
    * transcript for `threadId` plus a cursor to an in-flight run.
    */
-  hydrate?: (threadId: string) => Promise<ChatHydrationResult>
+  hydrate?: (
+    threadId: string,
+    options?: ChatHydrateOptions,
+  ) => Promise<ChatHydrationResult>
   /**
    * Server-driven generation hydration for `persistence: true`: the last
    * generation's resume snapshot for `threadId` plus a cursor to a run still

package/src/types.ts

@@ -751,14 +751,23 @@ export type ChatPersistenceOptions<
   | {
       persistence: true
       threadId: string
+      /**
+       * Newest-window size for server hydrate. Only with `persistence: true`.
+       * Without this, hydrate still loads the full thread.
+       */
+      history?: {
+        pageSize: number
+      }
     }
   | {
       persistence: ChatClientPersistence<TTools>
       threadId: string
+      history?: never
     }
   | {
       persistence?: false | undefined
       threadId?: string
+      history?: never
     }
 
 type IsUnknown<T> = unknown extends T