@tanstack/ai-client 0.12.0 → 0.13.0

package/src/types.ts

@@ -13,6 +13,8 @@ import type {
   VideoPart,
 } from '@tanstack/ai'
 import type { ConnectionAdapter } from './connection-adapters'
+import type { AIDevtoolsClientMetadata } from './devtools'
+import type { ChatDevtoolsBridgeFactory } from './devtools-noop'
 
 export type { StructuredOutputPart } from '@tanstack/ai'
 
@@ -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 {
+  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,
+    }
   }
 }