@tanstack/ai-client 0.12.0 → 0.14.0

package/src/events.ts

@@ -1,7 +1,57 @@
-import { aiEventClient } from '@tanstack/ai-event-client'
-import type { ContentPart } from '@tanstack/ai'
+import {
+  aiEventClient,
+  createAIDevtoolsEventEnvelope,
+} from '@tanstack/ai-event-client'
+import type { ContentPart } from '@tanstack/ai/client'
 import type { UIMessage } from './types'
 
+export interface ChatClientRunEventContext {
+  threadId: string
+  runId: string
+  toolCallId?: string
+}
+
+export interface ChatClientEventContext {
+  threadId?: string
+  runId?: string
+  toolCallId?: string
+}
+
+export interface ChatClientToolFixtureAppliedEvent {
+  hookId: string
+  threadId: string
+  toolName: string
+  input: unknown
+  output: unknown
+  execute?: boolean
+  message?: {
+    id: string
+    role: 'system' | 'user' | 'assistant'
+    parts: Array<unknown>
+    createdAt?: number | string
+  }
+  messageId: string
+  toolCallId: string
+  runId?: string
+  errorText?: string
+}
+
+export interface ChatClientStructuredOutputEvent {
+  status: 'streaming' | 'complete' | 'error'
+  raw?: string
+  partial?: unknown
+  data?: unknown
+  reasoning?: string
+  errorMessage?: string
+  delta?: string
+}
+
+export type ChatClientStructuredOutputEventName =
+  | 'structured-output:started'
+  | 'structured-output:updated'
+  | 'structured-output:completed'
+  | 'structured-output:errored'
+
 /**
  * Abstract base class for ChatClient event emission
  */
@@ -49,11 +99,17 @@ export abstract class ChatClientEventEmitter {
   /**
    * Emit text update events (combines processor and client events)
    */
-  textUpdated(streamId: string, messageId: string, content: string): void {
+  textUpdated(
+    streamId: string,
+    messageId: string,
+    content: string,
+    context?: ChatClientRunEventContext,
+  ): void {
     this.emitEvent('text:chunk:content', {
       streamId,
       messageId,
       content,
+      ...context,
     })
   }
 
@@ -67,6 +123,7 @@ export abstract class ChatClientEventEmitter {
     toolName: string,
     state: string,
     args: string,
+    context?: ChatClientRunEventContext,
   ): void {
     this.emitEvent('tools:call:updated', {
       streamId,
@@ -75,6 +132,7 @@ export abstract class ChatClientEventEmitter {
       toolName,
       state,
       arguments: args,
+      ...context,
     })
   }
 
@@ -89,12 +147,29 @@ export abstract class ChatClientEventEmitter {
     messageId: string,
     content: string,
     delta?: string,
+    context?: ChatClientRunEventContext,
   ): void {
     this.emitEvent('text:chunk:thinking', {
       streamId,
       messageId,
       content,
       delta,
+      ...context,
+    })
+  }
+
+  structuredOutputChanged(
+    eventName: ChatClientStructuredOutputEventName,
+    streamId: string,
+    messageId: string,
+    output: ChatClientStructuredOutputEvent,
+    context?: ChatClientRunEventContext,
+  ): void {
+    this.emitEvent(eventName, {
+      streamId,
+      messageId,
+      ...output,
+      ...context,
     })
   }
 
@@ -108,6 +183,7 @@ export abstract class ChatClientEventEmitter {
     toolName: string,
     input: unknown,
     approvalId: string,
+    context?: ChatClientRunEventContext,
   ): void {
     this.emitEvent('tools:approval:requested', {
       streamId,
@@ -116,13 +192,18 @@ export abstract class ChatClientEventEmitter {
       toolName,
       input,
       approvalId,
+      ...context,
     })
   }
 
   /**
    * Emit message appended event
    */
-  messageAppended(uiMessage: UIMessage, streamId?: string): void {
+  messageAppended(
+    uiMessage: UIMessage,
+    streamId?: string,
+    context?: ChatClientEventContext,
+  ): void {
     const content = uiMessage.parts
       .filter((part) => part.type === 'text')
       .map((part) => part.content)
@@ -134,6 +215,7 @@ export abstract class ChatClientEventEmitter {
       role: uiMessage.role,
       content,
       parts: uiMessage.parts,
+      ...context,
     })
   }
 
@@ -201,12 +283,14 @@ export abstract class ChatClientEventEmitter {
     toolName: string,
     output: unknown,
     state: string,
+    context?: ChatClientEventContext,
   ): void {
     this.emitEvent('tools:result:added', {
       toolCallId,
       toolName,
       output,
       state,
+      ...context,
     })
   }
 
@@ -217,13 +301,22 @@ export abstract class ChatClientEventEmitter {
     approvalId: string,
     toolCallId: string,
     approved: boolean,
+    context?: ChatClientRunEventContext,
   ): void {
     this.emitEvent('tools:approval:responded', {
       approvalId,
       toolCallId,
       approved,
+      ...context,
     })
   }
+
+  /**
+   * Emit tool fixture applied event.
+   */
+  toolFixtureApplied(fixture: ChatClientToolFixtureAppliedEvent): void {
+    this.emitEvent('devtools:tool-fixture:applied', { ...fixture })
+  }
 }
 
 /**
@@ -234,23 +327,61 @@ export class DefaultChatClientEventEmitter extends ChatClientEventEmitter {
    * Emit an event with automatic clientId and timestamp for client/tool events
    */
   protected emitEvent(eventName: string, data?: Record<string, any>): void {
-    // For client:* and tool:* events, automatically add clientId and timestamp
-    if (
+    const timestamp = Date.now()
+    const isUserVisibleEvent =
+      eventName.startsWith('text:') ||
+      eventName.startsWith('tools:') ||
+      eventName.startsWith('structured-output:') ||
+      eventName === 'devtools:tool-fixture:applied'
+    const includesClientContext =
       eventName.startsWith('client:') ||
       eventName.startsWith('tools:') ||
-      eventName.startsWith('text:')
-    ) {
-      aiEventClient.emit(eventName as any, {
-        ...data,
+      eventName.startsWith('text:') ||
+      eventName.startsWith('structured-output:') ||
+      eventName === 'devtools:tool-fixture:applied'
+    const visibility = isUserVisibleEvent ? 'user-visible' : 'client-state'
+    const envelopeContext = {
+      hookId: this.clientId,
+      ...(typeof data?.threadId === 'string'
+        ? { threadId: data.threadId }
+        : {}),
+      ...(typeof data?.runId === 'string' ? { runId: data.runId } : {}),
+      ...(typeof data?.streamId === 'string'
+        ? { streamId: data.streamId }
+        : {}),
+      ...(typeof data?.messageId === 'string'
+        ? { messageId: data.messageId }
+        : {}),
+      ...(typeof data?.toolCallId === 'string'
+        ? { toolCallId: data.toolCallId }
+        : {}),
+    }
+
+    // For client:* and tool:* events, automatically add clientId and timestamp
+    if (includesClientContext) {
+      const envelope = createAIDevtoolsEventEnvelope({
+        eventType: eventName,
         clientId: this.clientId,
+        ...envelopeContext,
         source: 'client',
-        timestamp: Date.now(),
+        visibility,
+        timestamp,
+      })
+      aiEventClient.emit(eventName as any, {
+        ...data,
+        ...envelope,
       })
     } else {
+      const envelope = createAIDevtoolsEventEnvelope({
+        eventType: eventName,
+        source: 'client',
+        visibility: 'client-state',
+        timestamp,
+      })
       // For other events, just add timestamp
       aiEventClient.emit(eventName as any, {
         ...data,
-        timestamp: Date.now(),
+        ...envelope,
       })
     }
   }

package/src/generation-client.ts

@@ -1,7 +1,17 @@
 import { GENERATION_EVENTS } from './generation-types'
+import { createNoOpGenerationDevtoolsBridge } 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,
+  GenerationDevtoolsBridge,
+  GenerationDevtoolsBridgeOptions,
+} from './devtools'
 import type {
   GenerationClientOptions,
   GenerationClientState,
@@ -67,13 +77,20 @@ export class GenerationClient<
 > {
   private readonly connection: ConnectConnectionAdapter | undefined
   private readonly fetcher: GenerationFetcher<TInput, TResult> | undefined
+  private readonly uniqueId: string
+  private readonly devtoolsMetadata: AIDevtoolsClientMetadata
+  private readonly devtoolsBridge: GenerationDevtoolsBridge<TOutput>
+  private readonly threadId: string
   private body: Record<string, any>
   private result: TOutput | null = null
+  private input: TInput | null = null
+  private progress: AIDevtoolsGenerationProgress | null = null
   private isLoading = false
   private error: Error | undefined = undefined
   private status: GenerationClientState = 'idle'
   private abortController: AbortController | null = null
   private readonly callbacksRef: GenerationCallbacks<TResult, TOutput>
+  private devtoolsMounted = false
 
   constructor(
     options: GenerationClientOptions<TInput, TResult, TOutput> &
@@ -85,6 +102,8 @@ export class GenerationClient<
           }
       ),
   ) {
+    this.uniqueId = options.id ?? this.generateUniqueId('generation')
+    this.threadId = this.uniqueId
     this.connection = options.connection
     this.fetcher = options.fetcher
     this.body = options.body ?? {}
@@ -99,6 +118,38 @@ export class GenerationClient<
       onErrorChange: options.onErrorChange,
       onStatusChange: options.onStatusChange,
     }
+
+    this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools)
+    this.devtoolsBridge = (
+      options.devtoolsBridgeFactory ?? createNoOpGenerationDevtoolsBridge
+    )<TOutput>(this.buildDevtoolsBridgeOptions())
+  }
+
+  private buildDevtoolsBridgeOptions(): GenerationDevtoolsBridgeOptions<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,
+        ...(this.error ? { error: this.error.message } : {}),
+      }),
+    }
+  }
+
+  mountDevtools(): void {
+    if (this.devtoolsMounted) {
+      return
+    }
+
+    this.devtoolsMounted = true
+    this.devtoolsBridge.emitRegistered()
+    this.devtoolsBridge.emitSnapshot()
   }
 
   /**
@@ -107,8 +158,12 @@ export class GenerationClient<
    * while already generating will be a no-op.
    */
   async generate(input: TInput): 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)
@@ -124,26 +179,50 @@ export class GenerationClient<
         if (signal.aborted) return
         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')
         }
       } else if (this.connection) {
         // Streaming adapter path
         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(
           'GenerationClient requires either a connection or fetcher option',
         )
       }
-    } catch (err: any) {
+      if (!signal.aborted && this.status === 'success') {
+        // Bump progress to 100 on successful completion so devtools
+        // snapshots reflect the final state. The bridge mirrors this in
+        // the run's recorded progress, but the snapshot reads `progress`
+        // from the client's core state.
+        this.progress = completeProgressValue(this.progress)
+        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
@@ -156,15 +235,28 @@ export class GenerationClient<
    */
   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 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.RESULT) {
             this.setResult(chunk.value as TResult)
           } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {
@@ -172,15 +264,20 @@ export class GenerationClient<
               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) ||
@@ -198,6 +295,7 @@ export class GenerationClient<
    * Abort any in-flight generation request.
    */
   stop(): void {
+    const runId = this.devtoolsBridge.getActiveRunId()
     if (this.abortController) {
       this.abortController.abort()
       this.abortController = null
@@ -205,6 +303,9 @@ export class GenerationClient<
     this.setIsLoading(false)
     if (this.status === 'generating') {
       this.setStatus('idle')
+      if (runId) {
+        this.devtoolsBridge.finishRun(runId, 'run:cancelled', 'cancelled')
+      }
     }
   }
 
@@ -214,8 +315,12 @@ export class GenerationClient<
   reset(): void {
     this.stop()
     this.setResult(null)
+    this.input = null
+    this.progress = null
+    this.devtoolsBridge.resetRuns()
     this.setError(undefined)
     this.setStatus('idle')
+    this.devtoolsBridge.emitState()
   }
 
   /**
@@ -246,6 +351,12 @@ export class GenerationClient<
     }
   }
 
+  dispose(): void {
+    this.stop()
+    this.devtoolsBridge.dispose()
+    this.devtoolsMounted = false
+  }
+
   // ===========================
   // Getters
   // ===========================
@@ -274,40 +385,96 @@ export class GenerationClient<
     if (rawResult === null) {
       this.result = null
       this.callbacksRef.onResultChange?.(null)
+      this.devtoolsBridge.recordResultChange()
       return
     }
 
     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 `TResult`, so the runtime cast is sound.
+    // eslint-disable-next-line no-restricted-syntax -- TOutput defaults to TResult when no onResult transform is supplied
+    this.result = rawResult as unknown as TOutput
     this.callbacksRef.onResultChange?.(this.result)
+    this.devtoolsBridge.recordResultChange()
   }
 
   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 createDevtoolsMetadata(
+    metadata?: Partial<AIDevtoolsClientMetadata>,
+  ): AIDevtoolsClientMetadata {
+    return {
+      hookName: metadata?.hookName ?? 'useGeneration',
+      ...(metadata?.framework ? { framework: metadata.framework } : {}),
+      ...(metadata?.outputKind ? { outputKind: metadata.outputKind } : {}),
+      ...(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,
+    }
+  }
+}
+
+function completeProgressValue(
+  progress: AIDevtoolsGenerationProgress | null,
+): AIDevtoolsGenerationProgress | null {
+  if (!progress) return null
+  const message = progress.message
+  return {
+    value: 100,
+    ...(message ? { message } : {}),
   }
 }

package/src/generation-types.ts

@@ -1,5 +1,10 @@
-import type { StreamChunk } from '@tanstack/ai'
+import type { StreamChunk } from '@tanstack/ai/client'
 import type { ConnectConnectionAdapter } from './connection-adapters'
+import type { AIDevtoolsClientMetadata } from './devtools'
+import type {
+  GenerationDevtoolsBridgeFactory,
+  VideoDevtoolsBridgeFactory,
+} from './devtools-noop'
 
 // ===========================
 // Inference Utilities
@@ -106,6 +111,15 @@ export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
 
+  /** Metadata used to register this generation hook with TanStack AI Devtools */
+  devtools?: Partial<AIDevtoolsClientMetadata>
+
+  /**
+   * Factory that constructs the devtools bridge. Default is a no-op
+   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
+   */
+  devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory
+
   /**
    * Callback when a result is received. Can optionally return a transformed value
    * that replaces the stored result.
@@ -172,11 +186,16 @@ export interface VideoGenerateResult {
  */
 export interface VideoGenerationClientOptions<
   TOutput = VideoGenerateResult,
-> extends GenerationClientOptions<
-  VideoGenerateInput,
-  VideoGenerateResult,
-  TOutput
+> extends Omit<
+  GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>,
+  'devtoolsBridgeFactory'
 > {
+  /**
+   * Factory that constructs the video devtools bridge. Default is a no-op
+   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
+   */
+  devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory
+
   /** Callback when a video job is created */
   onJobCreated?: (jobId: string) => void
   /** Callback on each status update */