@tanstack/ai-client 0.25.1 → 0.26.0

package/src/chat-client.ts

@@ -3,8 +3,11 @@ import {
   convertSchemaToJsonSchema,
   generateMessageId,
   isStandardSchema,
+  mergeMetadata,
   normalizeToUIMessage,
   parseWithStandardSchema,
+  restoreInboundChunk,
+  tanstackMetadata,
 } from '@tanstack/ai/client'
 import { createNoOpChatDevtoolsBridge } from './devtools-noop'
 import {
@@ -189,6 +192,7 @@ export function normalizeQueueOption(
  * Merge a run of queued messages into a single send for `drain: 'batch'`.
  * All-string content is joined with newlines; mixed/multimodal content is
  * flattened into a single `ContentPart` array. The last item's `body` wins.
+ * Object-form metadata is merged last-write-wins per key.
  */
 function mergeQueuedMessages(items: Array<InternalQueuedMessage>): {
   content: string | MultimodalContent
@@ -209,17 +213,24 @@ function mergeQueuedMessages(items: Array<InternalQueuedMessage>): {
     }
   }
   const parts: Array<ContentPart> = []
+  let metadata: Record<string, any> | undefined
   for (const item of items) {
     if (typeof item.content === 'string') {
       parts.push({ type: 'text', content: item.content })
-    } else if (typeof item.content.content === 'string') {
+      continue
+    }
+    if (typeof item.content.content === 'string') {
       parts.push({ type: 'text', content: item.content.content })
     } else {
       parts.push(...item.content.content)
     }
+    metadata = mergeMetadata(metadata, item.content.metadata)
   }
   return {
-    content: { content: parts },
+    content: {
+      content: parts,
+      ...(metadata !== undefined ? { metadata } : {}),
+    },
     ...(body !== undefined ? { body } : {}),
   }
 }
@@ -1747,12 +1758,14 @@ export class ChatClient<
     chunk: StreamChunk,
     options?: { defer?: boolean },
   ): Promise<void> {
+    chunk = restoreInboundChunk(chunk)
     if (
       chunk.type === 'RUN_ERROR' &&
       this.isActiveInterruptSubmissionFailure(chunk)
     ) {
+      const interruptErrors = tanstackMetadata(chunk)?.interruptErrors
       this.interruptSubmissionFailure = {
-        errors: chunk['tanstack:interruptErrors'] ?? [],
+        errors: Array.isArray(interruptErrors) ? interruptErrors : [],
       }
     }
     if (this.connectionStatus === 'connecting') {
@@ -1776,11 +1789,13 @@ export class ChatClient<
     this.processor.processChunk(chunk)
     this.updateRunLifecycle(chunk)
     this.observeInterruptState(chunk)
-    // The live path yields a macrotask between chunks so React can paint each
-    // delta progressively. A resume replay passes `defer: false` to skip it, so
-    // the buffered backlog applies in one batch (instant catch-up) instead of
-    // re-typing the whole reply.
-    if (options?.defer !== false) {
+    // Live path: yield a macrotask so the UI can paint. Skip when the page is
+    // hidden. Browsers clamp setTimeout there, and that wait paces stream pull.
+    // Replay passes defer: false so a backlog applies in one batch.
+    if (
+      options?.defer !== false &&
+      (typeof document === 'undefined' || !document.hidden)
+    ) {
       await new Promise((resolve) => setTimeout(resolve, 0))
     }
     this.resolveJoinedRun(chunk)
@@ -1790,8 +1805,10 @@ export class ChatClient<
     chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
   ): boolean {
     const submission = this.activeInterruptSubmission
-    const errors = chunk['tanstack:interruptErrors']
-    if (!submission || !errors || errors.length === 0) return false
+    const errors = tanstackMetadata(chunk)?.interruptErrors
+    if (!submission || !Array.isArray(errors) || errors.length === 0) {
+      return false
+    }
     const runId = getChunkRunId(chunk)
     if (runId !== undefined && runId !== this.currentRunId) return false
     if (
@@ -1800,12 +1817,22 @@ export class ChatClient<
     ) {
       return false
     }
-    return errors.every(
-      (error) =>
+    return errors.every((error) => {
+      if (
+        error == null ||
+        typeof error !== 'object' ||
+        typeof error.threadId !== 'string' ||
+        typeof error.interruptedRunId !== 'string' ||
+        typeof error.generation !== 'number'
+      ) {
+        return false
+      }
+      return (
         error.threadId === submission.threadId &&
         error.interruptedRunId === submission.interruptedRunId &&
-        error.generation === submission.generation,
-    )
+        error.generation === submission.generation
+      )
+    })
   }
 
   private resolveJoinedRun(chunk: StreamChunk): void {
@@ -1980,6 +2007,7 @@ export class ChatClient<
       const userMessage = this.processor.addUserMessage(
         normalizedContent.content,
         normalizedContent.id,
+        normalizedContent.metadata,
       )
       this.events.messageSent(userMessage.id, normalizedContent.content)
       return await this.streamResponse()
@@ -2039,17 +2067,22 @@ export class ChatClient<
   }
 
   /**
-   * Normalize the message input to extract content and optional id.
-   * Trims string content automatically.
+   * Normalize the message input to extract content, optional id, and
+   * optional metadata. String form has no metadata. Trims string content.
    */
   private normalizeMessageInput(input: string | MultimodalContent): {
     content: string | Array<ContentPart>
     id?: string
+    metadata?: Record<string, any>
   } {
     if (typeof input === 'string') {
       return { content: input.trim() }
     }
-    return { content: input.content, id: input.id }
+    return {
+      content: input.content,
+      id: input.id,
+      ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+    }
   }
 
   /**

package/src/connection-adapters.ts

@@ -1,4 +1,11 @@
-import { EventType, uiMessagesToWire } from '@tanstack/ai/client'
+import {
+  EventType,
+  getChunkRunId as getNormalizedChunkRunId,
+  restoreInboundChunk,
+  tanstackMetadata,
+  uiMessagesToWire,
+  withTanstackMetadata,
+} from '@tanstack/ai/client'
 import {
   createResponseStreamTextDecoder,
   getResponseStreamReader,
@@ -8,7 +15,6 @@ import type {
   ModelMessage,
   RunAgentResumeItem,
   RunErrorEvent,
-  RunFinishedEvent,
   StreamChunk,
   UIMessage,
 } from '@tanstack/ai/client'
@@ -34,12 +40,7 @@ export function getChunkRunId(chunk: StreamChunk): string | undefined {
   // the client's run identity to win when a provider stamps its own id; for
   // resumable reconnect/join the two ids match, so precedence is moot there.
   const requestRunId = chunkRunIds.get(chunk)
-  return (
-    requestRunId ??
-    ('runId' in chunk && typeof chunk.runId === 'string'
-      ? chunk.runId
-      : undefined)
-  )
+  return requestRunId ?? getNormalizedChunkRunId(chunk)
 }
 
 /**
@@ -385,6 +386,22 @@ function isNdjsonEnvelope(
   )
 }
 
+/** Rebuild pre-wire extras after SSE/NDJSON ingest. */
+function restoreInboundUsage(chunk: StreamChunk): StreamChunk {
+  return restoreInboundChunk(chunk)
+}
+
+function sseChunkModel(chunk: StreamChunk): string | undefined {
+  const tanstackModel = tanstackMetadata(chunk)?.model
+  if (typeof tanstackModel === 'string') return tanstackModel
+  const usage = 'usage' in chunk ? chunk.usage : undefined
+  if (Array.isArray(usage)) {
+    const model = (usage[0] as { model?: unknown } | undefined)?.model
+    if (typeof model === 'string') return model
+  }
+  return undefined
+}
+
 /**
  * Parse SSE-format lines into stream events, pairing each chunk with the `id:`
  * offset of the event it arrived on. Shared by the fetch- and XHR-backed SSE
@@ -431,27 +448,31 @@ async function* linesToSSEEvents(
     }
     const data = parseSseDataLine(line)
     if (data === '[DONE]') {
-      const synthetic: RunFinishedEvent = {
-        type: EventType.RUN_FINISHED,
-        threadId: lastThreadId ?? fallbackIds?.threadId ?? '',
-        runId: lastRunId ?? fallbackIds?.runId ?? '',
-        model: lastModel ?? '',
-        timestamp: Date.now(),
-        finishReason: 'stop',
+      yield {
+        chunk: withTanstackMetadata(
+          {
+            type: EventType.RUN_FINISHED,
+            threadId: lastThreadId ?? fallbackIds?.threadId ?? '',
+            runId: lastRunId ?? fallbackIds?.runId ?? '',
+            timestamp: Date.now(),
+          },
+          {
+            finishReason: 'stop',
+            ...(lastModel !== undefined ? { model: lastModel } : {}),
+          },
+        ) as StreamChunk,
       }
-      yield { chunk: synthetic }
       return
     }
-    const chunk = JSON.parse(data) as StreamChunk
+    const chunk = restoreInboundUsage(JSON.parse(data) as StreamChunk)
     if ('threadId' in chunk && typeof chunk.threadId === 'string') {
       lastThreadId = chunk.threadId
     }
     if ('runId' in chunk && typeof chunk.runId === 'string') {
       lastRunId = chunk.runId
     }
-    if ('model' in chunk && typeof chunk.model === 'string') {
-      lastModel = chunk.model
-    }
+    const model = sseChunkModel(chunk)
+    if (model !== undefined) lastModel = model
     const id = pendingId
     pendingId = undefined
     yield { chunk, ...(id !== undefined ? { id } : {}) }
@@ -470,9 +491,9 @@ async function* linesToNdjsonEvents(
   for await (const line of lines) {
     const parsed = JSON.parse(line) as unknown
     if (isNdjsonEnvelope(parsed)) {
-      yield { chunk: parsed.chunk, id: parsed.id }
+      yield { chunk: restoreInboundUsage(parsed.chunk), id: parsed.id }
     } else {
-      yield { chunk: parsed as StreamChunk }
+      yield { chunk: restoreInboundUsage(parsed as StreamChunk) }
     }
   }
 }
@@ -1064,21 +1085,24 @@ export function normalizeConnectionAdapter(
         // observed, but stamp the caller's request runId so getChunkRunId()
         // correlates to activeRunIds / currentRunId (same as real stream chunks).
         if (!abortSignal?.aborted && !hasTerminalEvent) {
-          const synthetic: RunFinishedEvent = {
-            type: EventType.RUN_FINISHED,
-            threadId: requireSyntheticId(
-              upstreamThreadId ?? runContext?.threadId,
-              'threadId',
-            ),
-            runId: requireSyntheticId(
-              upstreamRunId ?? runContext?.runId,
-              'runId',
-            ),
-            model: 'connect-wrapper',
-            timestamp: Date.now(),
-            finishReason: 'stop',
-          }
-          push(synthetic, runContext?.runId)
+          push(
+            withTanstackMetadata(
+              {
+                type: EventType.RUN_FINISHED,
+                threadId: requireSyntheticId(
+                  upstreamThreadId ?? runContext?.threadId,
+                  'threadId',
+                ),
+                runId: requireSyntheticId(
+                  upstreamRunId ?? runContext?.runId,
+                  'runId',
+                ),
+                timestamp: Date.now(),
+              },
+              { finishReason: 'stop', model: 'connect-wrapper' },
+            ) as StreamChunk,
+            runContext?.runId,
+          )
         }
       } catch (err) {
         if (!abortSignal?.aborted && !hasTerminalEvent) {
@@ -2143,9 +2167,9 @@ export function webSocket(
       }
       if (isPingFrame(parsed)) return
       const envelopeId = isNdjsonEnvelope(parsed) ? parsed.id : undefined
-      const chunk = isNdjsonEnvelope(parsed)
-        ? parsed.chunk
-        : (parsed as StreamChunk)
+      const chunk = restoreInboundUsage(
+        isNdjsonEnvelope(parsed) ? parsed.chunk : (parsed as StreamChunk),
+      )
 
       // Thread durable chunks through the active run session's tracker (if
       // any) so a later reconnect knows the last offset and can skip a
@@ -2325,7 +2349,9 @@ export function webSocket(
         }
         if (isPingFrame(parsed)) return
         pipe.push(
-          isNdjsonEnvelope(parsed) ? parsed.chunk : (parsed as StreamChunk),
+          restoreInboundUsage(
+            isNdjsonEnvelope(parsed) ? parsed.chunk : (parsed as StreamChunk),
+          ),
         )
       }
       ws.onclose = (event?: CloseEvent) => {

package/src/generation-client.ts

@@ -10,6 +10,7 @@ import {
 } from './generation-types'
 import { createNoOpGenerationDevtoolsBridge } from './devtools-noop'
 import { parseSSEResponse } from './sse-parser'
+import { restoreInboundChunk } from '@tanstack/ai/client'
 import type { StreamChunk } from '@tanstack/ai/client'
 import type {
   ConnectConnectionAdapter,
@@ -349,9 +350,10 @@ export class GenerationClient<
     let streamRunId: string | undefined
     let sawTerminalChunk = false
 
-    for await (const chunk of source) {
+    for await (const raw of source) {
       if (signal.aborted) break
 
+      const chunk = restoreInboundChunk(raw)
       this.callbacksRef.onChunk?.(chunk)
       this.observeResumeSnapshot(chunk)
       const chunkRunId =
@@ -390,11 +392,9 @@ export class GenerationClient<
           this.devtoolsBridge.ensureRunStarted(
             chunkRunId ?? streamRunId ?? fallbackRunId,
           )
-          // Prefer spec `message`; fall back to deprecated `error.message`
+          // Spec RUN_ERROR message. Missing message uses this fallback.
           const msg =
-            (chunk.message as string | undefined) ||
-            chunk.error?.message ||
-            'An error occurred'
+            (chunk.message as string | undefined) || 'An error occurred'
           throw new Error(msg)
         }
         default:

package/src/generation-types.ts

@@ -1,3 +1,4 @@
+import { tanstackMetadata } from '@tanstack/ai/client'
 import type {
   MediaPrompt,
   PersistedArtifactRef,
@@ -461,8 +462,13 @@ export function updateGenerationResumeSnapshot(
   previous: GenerationResumeSnapshot | null | undefined,
   chunk: StreamChunk,
 ): GenerationResumeSnapshot {
-  const threadId = stringField(chunk, 'threadId')
-  const runId = stringField(chunk, 'runId')
+  const tanstack = tanstackMetadata(chunk)
+  const threadId =
+    stringField(chunk, 'threadId') ??
+    (typeof tanstack?.threadId === 'string' ? tanstack.threadId : undefined)
+  const runId =
+    stringField(chunk, 'runId') ??
+    (typeof tanstack?.runId === 'string' ? tanstack.runId : undefined)
   const carried = chunk.type === 'RUN_STARTED' ? undefined : previous
   const previousArtifacts = carried?.pendingArtifacts ?? []
   const next: GenerationResumeSnapshot = {

package/src/types.ts

@@ -397,6 +397,18 @@ export interface MultimodalContent {
    * If not provided, a unique ID will be generated.
    */
   id?: string
+  /**
+   * Optional AG-UI metadata bag copied onto the resulting UIMessage.
+   *
+   * @example
+   * ```ts
+   * await client.sendMessage({
+   *   content: 'Show me failed logins',
+   *   metadata: { author: { id: 'user-42', name: 'Dana' } },
+   * })
+   * ```
+   */
+  metadata?: Record<string, any>
 }
 
 /**
@@ -616,6 +628,11 @@ export interface UIMessage<
   role: 'system' | 'user' | 'assistant'
   parts: Array<MessagePart<TTools, TData>>
   createdAt?: Date
+  /**
+   * Optional AG-UI metadata bag. TanStack writes the `tanstack` key.
+   * User keys stay at the top.
+   */
+  metadata?: Record<string, any>
 }
 
 /**

package/src/video-generation-client.ts

@@ -10,6 +10,7 @@ import {
 } from './generation-types'
 import { createNoOpVideoDevtoolsBridge } from './devtools-noop'
 import { parseSSEResponse } from './sse-parser'
+import { restoreInboundChunk } from '@tanstack/ai/client'
 import type { StreamChunk } from '@tanstack/ai/client'
 import type {
   ConnectConnectionAdapter,
@@ -343,9 +344,10 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     let streamRunId: string | undefined
     let sawTerminalChunk = false
 
-    for await (const chunk of source) {
+    for await (const raw of source) {
       if (signal.aborted) break
 
+      const chunk = restoreInboundChunk(raw)
       this.callbacksRef.onChunk?.(chunk)
       this.observeResumeSnapshot(chunk)
       const chunkRunId =
@@ -395,11 +397,9 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
           this.devtoolsBridge.ensureRunStarted(
             chunkRunId ?? streamRunId ?? fallbackRunId,
           )
-          // Prefer spec `message`; fall back to deprecated `error.message`
+          // Spec RUN_ERROR message. Missing message uses this fallback.
           const msg =
-            (chunk.message as string | undefined) ||
-            chunk.error?.message ||
-            'An error occurred'
+            (chunk.message as string | undefined) || 'An error occurred'
           throw new Error(msg)
         }
         default: