@tanstack/ai-client 0.12.0 → 0.14.0

package/src/index.ts

@@ -43,13 +43,23 @@ export type {
   VideoGenerateInput,
 } from './generation-types'
 export { GENERATION_EVENTS } from './generation-types'
+export { UnsupportedResponseStreamError } from './response-stream'
 export { clientTools, createChatClientOptions } from './types'
+export {
+  createAIDevtoolsGenerationPreview,
+  type AIDevtoolsClientMetadata,
+  type AIDevtoolsDisplayOptions,
+  type AIDevtoolsGenerationMediaItem,
+  type AIDevtoolsGenerationPreview,
+  type AIDevtoolsGenerationProgress,
+  type AIDevtoolsGenerationVideoJob,
+} from './devtools'
 export type {
   ExtractToolNames,
   ExtractToolInput,
   ExtractToolOutput,
 } from './tool-types'
-export type { AnyClientTool } from '@tanstack/ai'
+export type { AnyClientTool } from '@tanstack/ai/client'
 export type {
   RealtimeAdapter,
   RealtimeConnection,
@@ -60,6 +70,8 @@ export type {
 export {
   fetchServerSentEvents,
   fetchHttpStream,
+  xhrServerSentEvents,
+  xhrHttpStream,
   stream,
   rpcStream,
   StreamTruncatedError,
@@ -68,6 +80,7 @@ export {
   type FetchConnectionOptions,
   type RunAgentInputContext,
   type SubscribeConnectionAdapter,
+  type XhrConnectionOptions,
 } from './connection-adapters'
 
 // Re-export message converters from @tanstack/ai
@@ -78,7 +91,7 @@ export {
   convertMessagesToModelMessages,
   normalizeToUIMessage,
   generateMessageId,
-} from '@tanstack/ai'
+} from '@tanstack/ai/client'
 
 // Re-export stream processing from @tanstack/ai (shared implementation)
 export {
@@ -101,4 +114,4 @@ export {
   type ChunkRecording,
   type ProcessorResult,
   type ProcessorState,
-} from '@tanstack/ai'
+} from '@tanstack/ai/client'

package/src/realtime-client.ts

@@ -1,4 +1,4 @@
-import { convertSchemaToJsonSchema } from '@tanstack/ai'
+import { convertSchemaToJsonSchema } from '@tanstack/ai/client'
 import type {
   AnyClientTool,
   AudioVisualization,
@@ -6,7 +6,7 @@ import type {
   RealtimeMode,
   RealtimeStatus,
   RealtimeToken,
-} from '@tanstack/ai'
+} from '@tanstack/ai/client'
 import type {
   RealtimeClientOptions,
   RealtimeClientState,

package/src/realtime-types.ts

@@ -8,7 +8,7 @@ import type {
   RealtimeSessionConfig,
   RealtimeStatus,
   RealtimeToken,
-} from '@tanstack/ai'
+} from '@tanstack/ai/client'
 
 // ============================================================================
 // Adapter Interface

package/src/response-stream.ts

@@ -0,0 +1,42 @@
+export type MissingResponseStreamFeature =
+  | 'TextDecoder'
+  | 'Response.body'
+  | 'Response.body.getReader'
+
+export class UnsupportedResponseStreamError extends Error {
+  readonly missingFeature: MissingResponseStreamFeature
+
+  constructor(missingFeature: MissingResponseStreamFeature) {
+    super(createUnsupportedResponseStreamMessage(missingFeature))
+    this.name = 'UnsupportedResponseStreamError'
+    this.missingFeature = missingFeature
+  }
+}
+
+function createUnsupportedResponseStreamMessage(
+  missingFeature: MissingResponseStreamFeature,
+): string {
+  return `Streaming fetch responses are not supported in this runtime because ${missingFeature} is unavailable. React Native users need a compatible fetch/stream/TextDecoder polyfill, or should use a fetch, XHR, or custom transport that can deliver streaming chunks.`
+}
+
+export function getResponseStreamReader(
+  response: Response,
+): ReadableStreamDefaultReader<Uint8Array> {
+  if (!response.body) {
+    throw new UnsupportedResponseStreamError('Response.body')
+  }
+
+  if (typeof response.body.getReader !== 'function') {
+    throw new UnsupportedResponseStreamError('Response.body.getReader')
+  }
+
+  return response.body.getReader()
+}
+
+export function createResponseStreamTextDecoder(): TextDecoder {
+  if (typeof globalThis.TextDecoder !== 'function') {
+    throw new UnsupportedResponseStreamError('TextDecoder')
+  }
+
+  return new globalThis.TextDecoder()
+}

package/src/sse-parser.ts

@@ -1,4 +1,9 @@
-import type { StreamChunk } from '@tanstack/ai'
+import {
+  createResponseStreamTextDecoder,
+  getResponseStreamReader,
+} from './response-stream'
+import { parseSseDataLine } from './sse-utils'
+import type { StreamChunk } from '@tanstack/ai/client'
 
 /**
  * Read lines from a stream (newline-delimited)
@@ -8,7 +13,7 @@ async function* readStreamLines(
   abortSignal?: AbortSignal,
 ): AsyncGenerator<string> {
   try {
-    const decoder = new TextDecoder()
+    const decoder = createResponseStreamTextDecoder()
     let buffer = ''
 
     while (!abortSignal?.aborted) {
@@ -51,13 +56,10 @@ export async function* parseSSEResponse(
     )
   }
 
-  const reader = response.body?.getReader()
-  if (!reader) {
-    throw new Error('Response body is not readable')
-  }
+  const reader = getResponseStreamReader(response)
 
   for await (const line of readStreamLines(reader, abortSignal)) {
-    const data = line.startsWith('data: ') ? line.slice(6) : line
+    const data = parseSseDataLine(line)
 
     if (data === '[DONE]') {
       console.warn(

package/src/sse-utils.ts

@@ -0,0 +1,8 @@
+export function parseSseDataLine(line: string): string {
+  if (!line.startsWith('data:')) {
+    return line
+  }
+
+  const data = line.slice(5)
+  return data.startsWith(' ') ? data.slice(1) : data
+}

package/src/tool-types.ts

@@ -2,7 +2,7 @@ import type {
   AnyClientTool,
   InferToolInput,
   InferToolOutput,
-} from '@tanstack/ai'
+} from '@tanstack/ai/client'
 
 /**
  * Extract all tool names from a tools array as a union type

package/src/types.ts

@@ -11,10 +11,12 @@ import type {
   StreamChunk,
   StructuredOutputPart,
   VideoPart,
-} from '@tanstack/ai'
+} from '@tanstack/ai/client'
 import type { ConnectionAdapter } from './connection-adapters'
+import type { AIDevtoolsClientMetadata } from './devtools'
+import type { ChatDevtoolsBridgeFactory } from './devtools-noop'
 
-export type { StructuredOutputPart } from '@tanstack/ai'
+export type { StructuredOutputPart } from '@tanstack/ai/client'
 
 /**
  * `messages` is the full UIMessage history (not a delta). `data` is the
@@ -270,6 +272,7 @@ export interface UIMessage<
  */
 export type ChatClientOptions<
   TTools extends ReadonlyArray<AnyClientTool> = any,
+  TContext = unknown,
 > = {
   /**
    * Initial messages to populate the chat
@@ -387,6 +390,25 @@ export type ChatClientOptions<
    */
   tools?: TTools
 
+  /**
+   * Client-local context passed to client-side tool execution.
+   */
+  context?: TContext
+
+  /**
+   * Devtools hook metadata for this client instance.
+   */
+  devtools?: Partial<AIDevtoolsClientMetadata>
+
+  /**
+   * Factory that constructs the devtools bridge. Default is a no-op
+   * factory, which keeps `@tanstack/ai-client/devtools` (the heavy
+   * bridge implementation) out of the main entry's bundle. Frameworks
+   * that need live devtools should pass the real factory from
+   * `@tanstack/ai-client/devtools`.
+   */
+  devtoolsBridgeFactory?: ChatDevtoolsBridgeFactory
+
   /**
    * Stream processing options (optional)
    * Configure chunking strategy
@@ -444,7 +466,10 @@ export function clientTools<const T extends Array<AnyClientTool>>(
  */
 export function createChatClientOptions<
   const TTools extends ReadonlyArray<AnyClientTool>,
->(options: ChatClientOptions<TTools>): ChatClientOptions<TTools> {
+  TContext = unknown,
+>(
+  options: ChatClientOptions<TTools, TContext>,
+): ChatClientOptions<TTools, TContext> {
   return options
 }
 
@@ -463,4 +488,6 @@ export function createChatClientOptions<
  * ```
  */
 export type InferChatMessages<T> =
-  T extends ChatClientOptions<infer TTools> ? Array<UIMessage<TTools>> : never
+  T extends ChatClientOptions<infer TTools, any>
+    ? Array<UIMessage<TTools>>
+    : never

package/src/video-generation-client.ts

@@ -1,7 +1,17 @@
 import { GENERATION_EVENTS } from './generation-types'
+import { createNoOpVideoDevtoolsBridge } from './devtools-noop'
 import { parseSSEResponse } from './sse-parser'
-import type { StreamChunk } from '@tanstack/ai'
-import type { ConnectConnectionAdapter } from './connection-adapters'
+import type { StreamChunk } from '@tanstack/ai/client'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+} from './connection-adapters'
+import type {
+  AIDevtoolsClientMetadata,
+  AIDevtoolsGenerationProgress,
+  VideoDevtoolsBridge,
+  VideoDevtoolsBridgeOptions,
+} from './devtools'
 import type {
   GenerationClientState,
   GenerationFetcher,
@@ -74,9 +84,15 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private readonly fetcher:
     | GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
     | undefined
+  private readonly uniqueId: string
+  private readonly devtoolsMetadata: AIDevtoolsClientMetadata
+  private readonly devtoolsBridge: VideoDevtoolsBridge<TOutput>
+  private readonly threadId: string
   private body: Record<string, any>
 
   private result: TOutput | null = null
+  private input: VideoGenerateInput | null = null
+  private progress: AIDevtoolsGenerationProgress | null = null
   private jobId: string | null = null
   private videoStatus: VideoStatusInfo | null = null
   private isLoading = false
@@ -84,6 +100,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private status: GenerationClientState = 'idle'
   private abortController: AbortController | null = null
   private readonly callbacksRef: VideoCallbacks<TOutput>
+  private devtoolsMounted = false
 
   constructor(
     options: VideoGenerationClientOptions<TOutput> &
@@ -95,6 +112,8 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
           }
       ),
   ) {
+    this.uniqueId = options.id ?? this.generateUniqueId('video')
+    this.threadId = this.uniqueId
     this.connection = options.connection
     this.fetcher = options.fetcher
     this.body = options.body ?? {}
@@ -113,6 +132,40 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
       onJobIdChange: options.onJobIdChange,
       onVideoStatusChange: options.onVideoStatusChange,
     }
+
+    this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools)
+    this.devtoolsBridge = (
+      options.devtoolsBridgeFactory ?? createNoOpVideoDevtoolsBridge
+    )<TOutput>(this.buildDevtoolsBridgeOptions())
+  }
+
+  private buildDevtoolsBridgeOptions(): VideoDevtoolsBridgeOptions<TOutput> {
+    return {
+      hookId: this.uniqueId,
+      clientId: this.uniqueId,
+      threadId: this.threadId,
+      metadata: this.devtoolsMetadata,
+      getCoreState: () => ({
+        input: this.input,
+        result: this.result,
+        progress: this.progress,
+        status: this.status,
+        isLoading: this.isLoading,
+        jobId: this.jobId,
+        videoStatus: this.videoStatus,
+        ...(this.error ? { error: this.error.message } : {}),
+      }),
+    }
+  }
+
+  mountDevtools(): void {
+    if (this.devtoolsMounted) {
+      return
+    }
+
+    this.devtoolsMounted = true
+    this.devtoolsBridge.emitRegistered()
+    this.devtoolsBridge.emitSnapshot()
   }
 
   /**
@@ -120,8 +173,12 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
    * Only one generation can be in-flight at a time.
    */
   async generate(input: VideoGenerateInput): Promise<void> {
+    this.mountDevtools()
     if (this.isLoading) return
 
+    this.input = input
+    this.progress = null
+    const runId = this.devtoolsBridge.beginRun(input)
     this.setIsLoading(true)
     this.setStatus('generating')
     this.setError(undefined)
@@ -134,21 +191,39 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
 
     try {
       if (this.fetcher) {
-        await this.generateWithFetcher(input, signal)
+        await this.generateWithFetcher(input, signal, runId)
       } else if (this.connection) {
         const mergedData = { ...this.body, ...input }
-        const stream = this.connection.connect([], mergedData, signal)
-        await this.processStream(stream)
+        const stream = this.connection.connect(
+          [],
+          mergedData,
+          signal,
+          this.createRunContext(runId),
+        )
+        await this.processStream(stream, runId)
       } else {
         throw new Error(
           'VideoGenerationClient requires either a connection or fetcher option',
         )
       }
-    } catch (err: any) {
+      if (!signal.aborted && this.status === 'success') {
+        this.devtoolsBridge.finishRun(
+          this.devtoolsBridge.getActiveRunId() ?? runId,
+          'run:completed',
+          'completed',
+        )
+      }
+    } catch (err: unknown) {
       if (signal.aborted) return
       const error = err instanceof Error ? err : new Error(String(err))
       this.setError(error)
       this.setStatus('error')
+      this.devtoolsBridge.finishRun(
+        this.devtoolsBridge.getActiveRunId() ?? runId,
+        'run:errored',
+        'errored',
+        error.message,
+      )
       this.callbacksRef.onError?.(error)
     } finally {
       this.abortController = null
@@ -162,6 +237,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private async generateWithFetcher(
     input: VideoGenerateInput,
     signal: AbortSignal,
+    runId: string,
   ): Promise<void> {
     if (!this.fetcher) return
 
@@ -171,8 +247,9 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
 
     if (result instanceof Response) {
       // Server function returned SSE Response — parse stream
-      await this.processStream(parseSSEResponse(result, signal))
+      await this.processStream(parseSSEResponse(result, signal), runId)
     } else {
+      this.devtoolsBridge.ensureRunStarted(runId)
       this.setResult(result)
       this.setStatus('success')
     }
@@ -184,15 +261,28 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
    */
   private async processStream(
     source: AsyncIterable<StreamChunk>,
+    fallbackRunId: string,
   ): Promise<void> {
+    let streamRunId: string | undefined
+
     for await (const chunk of source) {
       if (this.abortController?.signal.aborted) break
 
       this.callbacksRef.onChunk?.(chunk)
+      const chunkRunId =
+        'runId' in chunk && typeof chunk.runId === 'string'
+          ? chunk.runId
+          : undefined
 
       // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType has ~22 variants; this consumer only handles the subset relevant to video generation lifecycle.
       switch (chunk.type) {
+        case 'RUN_STARTED': {
+          streamRunId = chunk.runId
+          this.devtoolsBridge.ensureRunStarted(chunk.runId)
+          break
+        }
         case 'CUSTOM': {
+          this.devtoolsBridge.ensureRunStarted(streamRunId ?? fallbackRunId)
           if (chunk.name === GENERATION_EVENTS.VIDEO_JOB_CREATED) {
             const { jobId } = chunk.value as { jobId: string }
             this.setJobId(jobId)
@@ -202,7 +292,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
             this.setVideoStatus(statusInfo)
             this.callbacksRef.onStatusUpdate?.(statusInfo)
             if (statusInfo.progress !== undefined) {
-              this.callbacksRef.onProgress?.(statusInfo.progress)
+              this.setProgress(statusInfo.progress)
             }
           } else if (chunk.name === GENERATION_EVENTS.RESULT) {
             this.setResult(chunk.value as VideoGenerateResult)
@@ -211,15 +301,20 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
               progress: number
               message?: string
             }
-            this.callbacksRef.onProgress?.(progress, message)
+            this.setProgress(progress, message)
           }
           break
         }
         case 'RUN_FINISHED': {
+          streamRunId = chunk.runId
+          this.devtoolsBridge.ensureRunStarted(chunk.runId)
           this.setStatus('success')
           break
         }
         case 'RUN_ERROR': {
+          this.devtoolsBridge.ensureRunStarted(
+            chunkRunId ?? streamRunId ?? fallbackRunId,
+          )
           // Prefer spec `message`; fall back to deprecated `error.message`
           const msg =
             (chunk.message as string | undefined) ||
@@ -237,6 +332,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
    * Abort any in-flight generation or polling.
    */
   stop(): void {
+    const runId = this.devtoolsBridge.getActiveRunId()
     if (this.abortController) {
       this.abortController.abort()
       this.abortController = null
@@ -244,6 +340,9 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     this.setIsLoading(false)
     if (this.status === 'generating') {
       this.setStatus('idle')
+      if (runId) {
+        this.devtoolsBridge.finishRun(runId, 'run:cancelled', 'cancelled')
+      }
     }
   }
 
@@ -253,10 +352,14 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   reset(): void {
     this.stop()
     this.setResult(null)
+    this.input = null
+    this.progress = null
+    this.devtoolsBridge.resetRuns()
     this.setJobId(null)
     this.setVideoStatus(null)
     this.setError(undefined)
     this.setStatus('idle')
+    this.devtoolsBridge.emitState()
   }
 
   /**
@@ -299,6 +402,12 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     }
   }
 
+  dispose(): void {
+    this.stop()
+    this.devtoolsBridge.dispose()
+    this.devtoolsMounted = false
+  }
+
   // ===========================
   // Getters
   // ===========================
@@ -335,50 +444,116 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     if (rawResult === null) {
       this.result = null
       this.callbacksRef.onResultChange?.(null)
+      this.devtoolsBridge.recordResultChange()
       return
     }
 
+    const completedStatus = this.createCompletedVideoStatus(rawResult)
+    if (this.progress?.value !== 100) {
+      this.setProgress(100, this.progress?.message)
+    }
+    this.setJobId(rawResult.jobId)
+    this.setVideoStatus(completedStatus)
+
     if (this.callbacksRef.onResult) {
       const transformed = this.callbacksRef.onResult(rawResult)
       if (transformed === null) {
-        // null return → keep previous result unchanged
+        // null return → keep previous result unchanged, just re-emit
+        this.devtoolsBridge.emitState()
         return
       }
       if (transformed !== undefined) {
         // Non-null, non-undefined → use transformed value
         this.result = transformed
         this.callbacksRef.onResultChange?.(this.result)
+        this.devtoolsBridge.recordResultChange()
         return
       }
     }
 
-    // No onResult callback, or callback returned void → use raw value
-    this.result = rawResult as TOutput
+    // No onResult callback, or callback returned void → use raw value as
+    // TOutput. When the caller did not supply an onResult transform,
+    // `TOutput` defaults to `VideoGenerateResult`, so the runtime cast is
+    // sound.
+    // eslint-disable-next-line no-restricted-syntax -- TOutput defaults to VideoGenerateResult when no onResult transform is supplied
+    this.result = rawResult as unknown as TOutput
     this.callbacksRef.onResultChange?.(this.result)
+    this.devtoolsBridge.recordResultChange()
   }
 
   private setJobId(jobId: string | null): void {
     this.jobId = jobId
     this.callbacksRef.onJobIdChange?.(jobId)
+    this.devtoolsBridge.recordJobIdChange()
   }
 
   private setVideoStatus(status: VideoStatusInfo | null): void {
     this.videoStatus = status
     this.callbacksRef.onVideoStatusChange?.(status)
+    this.devtoolsBridge.recordVideoStatusChange()
   }
 
   private setIsLoading(isLoading: boolean): void {
     this.isLoading = isLoading
     this.callbacksRef.onLoadingChange?.(isLoading)
+    this.devtoolsBridge.recordLoadingChange()
   }
 
   private setError(error: Error | undefined): void {
     this.error = error
     this.callbacksRef.onErrorChange?.(error)
+    this.devtoolsBridge.recordErrorChange(error)
   }
 
   private setStatus(status: GenerationClientState): void {
     this.status = status
     this.callbacksRef.onStatusChange?.(status)
+    this.devtoolsBridge.recordStatusChange(status)
+  }
+
+  private setProgress(value: number, message?: string): void {
+    this.progress = {
+      value,
+      ...(message ? { message } : {}),
+    }
+    if (message === undefined) {
+      this.callbacksRef.onProgress?.(value)
+    } else {
+      this.callbacksRef.onProgress?.(value, message)
+    }
+    this.devtoolsBridge.recordProgressChange()
+  }
+
+  private createCompletedVideoStatus(
+    result: VideoGenerateResult,
+  ): VideoStatusInfo {
+    return {
+      jobId: result.jobId,
+      status: result.status,
+      progress: 100,
+      url: result.url,
+    }
+  }
+
+  private createDevtoolsMetadata(
+    metadata?: Partial<AIDevtoolsClientMetadata>,
+  ): AIDevtoolsClientMetadata {
+    return {
+      hookName: metadata?.hookName ?? 'useGenerateVideo',
+      outputKind: metadata?.outputKind ?? 'video',
+      ...(metadata?.framework ? { framework: metadata.framework } : {}),
+      ...(metadata?.name ? { name: metadata.name } : {}),
+    }
+  }
+
+  private generateUniqueId(prefix: string): string {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+
+  private createRunContext(runId: string): RunAgentInputContext {
+    return {
+      threadId: this.threadId,
+      runId,
+    }
   }
 }