@tanstack/ai-client 0.11.8 → 0.13.0

package/src/chat-client.ts

@@ -4,8 +4,11 @@ import {
   generateMessageId,
   normalizeToUIMessage,
 } from '@tanstack/ai'
-import { DefaultChatClientEventEmitter } from './events'
-import { normalizeConnectionAdapter } from './connection-adapters'
+import { createNoOpChatDevtoolsBridge } from './devtools-noop'
+import {
+  fetcherToConnectionAdapter,
+  normalizeConnectionAdapter,
+} from './connection-adapters'
 import type {
   AnyClientTool,
   ContentPart,
@@ -16,10 +19,19 @@ import type {
   ConnectionAdapter,
   SubscribeConnectionAdapter,
 } from './connection-adapters'
-import type { ChatClientEventEmitter } from './events'
+import type {
+  ChatClientEventEmitter,
+  ChatClientRunEventContext,
+} from './events'
+import type {
+  AIDevtoolsChatSnapshot,
+  ChatDevtoolsBridge,
+  ChatDevtoolsBridgeOptions,
+} from './devtools'
 import type {
   ChatClientOptions,
   ChatClientState,
+  ChatFetcher,
   ConnectionStatus,
   MessagePart,
   MultimodalContent,
@@ -27,6 +39,21 @@ import type {
   UIMessage,
 } from './types'
 
+function resolveTransport(transport: {
+  connection?: ConnectionAdapter
+  fetcher?: ChatFetcher
+}): ConnectionAdapter {
+  const { connection, fetcher } = transport
+  if (connection && fetcher) {
+    throw new Error(
+      'ChatClient: pass either `connection` or `fetcher`, not both.',
+    )
+  }
+  if (connection) return connection
+  if (fetcher) return fetcherToConnectionAdapter(fetcher)
+  throw new Error('ChatClient: either `connection` or `fetcher` is required.')
+}
+
 export class ChatClient {
   private readonly processor: StreamProcessor
   private connection: SubscribeConnectionAdapter
@@ -45,8 +72,15 @@ export class ChatClient {
   private status: ChatClientState = 'ready'
   private connectionStatus: ConnectionStatus = 'disconnected'
   private abortController: AbortController | null = null
-  private readonly events: ChatClientEventEmitter
   private readonly clientToolsRef: { current: Map<string, AnyClientTool> }
+  private readonly devtoolsBridge: ChatDevtoolsBridge
+  /**
+   * Alias for `this.events`. The bridge installs an
+   * emitter that auto-attaches run/thread context and auto-emits a
+   * snapshot after every event, so chat-client only ever calls
+   * `this.events.X(...)` exactly like it did before devtools landed.
+   */
+  private readonly events: ChatClientEventEmitter
   private currentStreamId: string | null = null
   private currentMessageId: string | null = null
   private readonly postStreamActions: Array<() => Promise<void>> = []
@@ -64,6 +98,7 @@ export class ChatClient {
   private draining = false
   private sessionGenerating = false
   private readonly activeRunIds = new Set<string>()
+  private devtoolsMounted = false
 
   private readonly callbacksRef: {
     current: {
@@ -96,8 +131,7 @@ export class ChatClient {
     // winning on key collision.
     this.bodyOption = options.body || {}
     this.forwardedPropsOption = options.forwardedProps || {}
-    this.connection = normalizeConnectionAdapter(options.connection)
-    this.events = new DefaultChatClientEventEmitter(this.uniqueId)
+    this.connection = normalizeConnectionAdapter(resolveTransport(options))
 
     // Build client tools map
     this.clientToolsRef = { current: new Map() }
@@ -107,6 +141,11 @@ export class ChatClient {
       }
     }
 
+    this.devtoolsBridge = (
+      options.devtoolsBridgeFactory ?? createNoOpChatDevtoolsBridge
+    )(this.buildDevtoolsBridgeOptions(options.devtools))
+    this.events = this.devtoolsBridge.events
+
     this.callbacksRef = {
       current: {
         onResponse: options.onResponse || (() => {}),
@@ -181,9 +220,41 @@ export class ChatClient {
               this.currentStreamId,
               messageId,
               content,
+              undefined,
             )
           }
         },
+        onStructuredOutputChange: (args) => {
+          const streamId = this.devtoolsBridge.resolveStreamId()
+          const eventName =
+            args.phase === 'start'
+              ? 'structured-output:started'
+              : args.phase === 'complete'
+                ? 'structured-output:completed'
+                : args.phase === 'error'
+                  ? 'structured-output:errored'
+                  : 'structured-output:updated'
+
+          this.currentMessageId = args.messageId
+          this.events.structuredOutputChanged(
+            eventName,
+            streamId,
+            args.messageId,
+            {
+              status: args.status,
+              raw: args.raw,
+              ...(args.partial !== undefined ? { partial: args.partial } : {}),
+              ...(args.data !== undefined ? { data: args.data } : {}),
+              ...(args.reasoning !== undefined
+                ? { reasoning: args.reasoning }
+                : {}),
+              ...(args.errorMessage !== undefined
+                ? { errorMessage: args.errorMessage }
+                : {}),
+              ...(args.delta !== undefined ? { delta: args.delta } : {}),
+            },
+          )
+        },
         onToolCallStateChange: (
           messageId: string,
           toolCallId: string,
@@ -220,24 +291,36 @@ export class ChatClient {
           const clientTool = this.clientToolsRef.current.get(args.toolName)
           const executeFunc = clientTool?.execute
           if (executeFunc) {
+            // Capture the run context at execution-start so a tool whose
+            // result lands AFTER the originating run finishes still reports
+            // back against the originating run, not whatever run is
+            // current when the result emits.
+            const runEventContext =
+              this.devtoolsBridge.getCurrentRunEventContext()
             // Create and track the execution promise
             const executionPromise = (async () => {
               try {
                 const output = await executeFunc(args.input)
-                await this.addToolResult({
-                  toolCallId: args.toolCallId,
-                  tool: args.toolName,
-                  output,
-                  state: 'output-available',
-                })
+                await this.addToolResultInternal(
+                  {
+                    toolCallId: args.toolCallId,
+                    tool: args.toolName,
+                    output,
+                    state: 'output-available',
+                  },
+                  runEventContext,
+                )
               } catch (error: any) {
-                await this.addToolResult({
-                  toolCallId: args.toolCallId,
-                  tool: args.toolName,
-                  output: null,
-                  state: 'output-error',
-                  errorText: error.message,
-                })
+                await this.addToolResultInternal(
+                  {
+                    toolCallId: args.toolCallId,
+                    tool: args.toolName,
+                    output: null,
+                    state: 'output-error',
+                    errorText: error.message,
+                  },
+                  runEventContext,
+                )
               } finally {
                 // Remove from pending when complete
                 this.pendingToolExecutions.delete(args.toolCallId)
@@ -254,16 +337,20 @@ export class ChatClient {
           input: any
           approvalId: string
         }) => {
-          if (this.currentStreamId) {
-            this.events.approvalRequested(
-              this.currentStreamId,
-              this.currentMessageId || '',
-              args.toolCallId,
-              args.toolName,
-              args.input,
-              args.approvalId,
-            )
-          }
+          const streamId = this.devtoolsBridge.resolveStreamId()
+          const messageIdForApproval =
+            this.findMessageIdForToolCall(args.toolCallId) ??
+            this.currentMessageId ??
+            ''
+
+          this.events.approvalRequested(
+            streamId,
+            messageIdForApproval,
+            args.toolCallId,
+            args.toolName,
+            args.input,
+            args.approvalId,
+          )
         },
         onCustomEvent: (
           eventType: string,
@@ -274,8 +361,15 @@ export class ChatClient {
         },
       },
     })
+  }
+
+  mountDevtools(): void {
+    if (this.devtoolsMounted) {
+      return
+    }
 
-    this.events.clientCreated(this.processor.getMessages().length)
+    this.devtoolsMounted = true
+    this.devtoolsBridge.mountWithTools(this.processor.getMessages().length)
   }
 
   private generateUniqueId(prefix: string): string {
@@ -291,22 +385,26 @@ export class ChatClient {
   private setStatus(status: ChatClientState): void {
     this.status = status
     this.callbacksRef.current.onStatusChange(status)
+    this.devtoolsBridge.emitSnapshot()
   }
 
   private setIsSubscribed(isSubscribed: boolean): void {
     this.isSubscribed = isSubscribed
     this.callbacksRef.current.onSubscriptionChange(isSubscribed)
+    this.devtoolsBridge.emitSnapshot()
   }
 
   private setConnectionStatus(status: ConnectionStatus): void {
     this.connectionStatus = status
     this.callbacksRef.current.onConnectionStatusChange(status)
+    this.devtoolsBridge.emitSnapshot()
   }
 
   private setSessionGenerating(isGenerating: boolean): void {
     if (this.sessionGenerating === isGenerating) return
     this.sessionGenerating = isGenerating
     this.callbacksRef.current.onSessionGeneratingChange(isGenerating)
+    this.devtoolsBridge.emitSnapshot()
   }
 
   private resetSessionGenerating(): void {
@@ -320,6 +418,57 @@ export class ChatClient {
     this.events.errorChanged(error?.message || null)
   }
 
+  private buildDevtoolsBridgeOptions(
+    devtools: ChatClientOptions['devtools'],
+  ): ChatDevtoolsBridgeOptions {
+    return {
+      hookId: this.uniqueId,
+      clientId: this.uniqueId,
+      threadId: this.threadId,
+      metadata: {
+        hookName: devtools?.hookName ?? 'useChat',
+        outputKind: devtools?.outputKind ?? 'chat',
+        ...(devtools?.framework ? { framework: devtools.framework } : {}),
+        ...(devtools?.name ? { name: devtools.name } : {}),
+      },
+      getSnapshot: () => this.getDevtoolsSnapshot(),
+      getTools: () => this.clientToolsRef.current.values(),
+      getMessages: () => this.processor.getMessages(),
+      setMessages: (messages: Array<UIMessage>) => {
+        this.processor.setMessages(messages)
+      },
+      addToolResult: (toolCallId, output, errorText) => {
+        this.processor.addToolResult(toolCallId, output, errorText)
+      },
+      generateId: (prefix) => this.generateUniqueId(prefix),
+    }
+  }
+
+  private getDevtoolsSnapshot(): AIDevtoolsChatSnapshot {
+    return {
+      messages: this.processor.getMessages(),
+      status: this.status,
+      isLoading: this.isLoading,
+      isSubscribed: this.isSubscribed,
+      connectionStatus: this.connectionStatus,
+      sessionGenerating: this.sessionGenerating,
+      activeRunIds: Array.from(this.activeRunIds),
+      ...(this.error ? { error: this.error.message } : {}),
+    }
+  }
+
+  private findMessageIdForToolCall(toolCallId: string): string | undefined {
+    const messages = this.processor.getMessages()
+    for (const message of messages) {
+      const match = message.parts.find(
+        (part: MessagePart): part is ToolCallPart =>
+          part.type === 'tool-call' && part.id === toolCallId,
+      )
+      if (match) return message.id
+    }
+    return undefined
+  }
+
   private abortSubscriptionLoop(): void {
     this.subscriptionAbortController?.abort()
     this.subscriptionAbortController = null
@@ -409,11 +558,12 @@ export class ChatClient {
         this.setConnectionStatus('connected')
       }
       this.callbacksRef.current.onChunk(chunk)
-      this.processor.processChunk(chunk)
       if (chunk.type === 'RUN_STARTED') {
         this.activeRunIds.add(chunk.runId)
         this.setSessionGenerating(true)
       }
+      this.devtoolsBridge.observeChunk(chunk)
+      this.processor.processChunk(chunk)
       // RUN_FINISHED / RUN_ERROR signal run completion — resolve processing
       // (redundant if onStreamEnd already resolved it, harmless)
       if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
@@ -422,9 +572,9 @@ export class ChatClient {
         // both so a RUN_ERROR with a runId only clears that run, not every
         // active run in the session.
         const runId =
-          chunk.type === 'RUN_FINISHED'
+          'runId' in chunk && typeof chunk.runId === 'string'
             ? chunk.runId
-            : (chunk as { runId?: string }).runId
+            : undefined
         if (runId) {
           this.activeRunIds.delete(runId)
         } else if (chunk.type === 'RUN_ERROR') {
@@ -510,6 +660,7 @@ export class ChatClient {
     content: string | MultimodalContent,
     body?: Record<string, any>,
   ): Promise<void> {
+    this.mountDevtools()
     const emptyMessage = typeof content === 'string' && !content.trim()
     if (emptyMessage || this.isLoading) {
       return
@@ -548,6 +699,7 @@ export class ChatClient {
    * Append a message and stream the response
    */
   async append(message: UIMessage | ModelMessage): Promise<void> {
+    this.mountDevtools()
     // Normalize the message to ensure it has id and createdAt
     const normalizedMessage = normalizeToUIMessage(message, generateMessageId)
 
@@ -565,6 +717,7 @@ export class ChatClient {
     // Add to messages
     const messages = this.processor.getMessages()
     this.processor.setMessages([...messages, uiMessage])
+    this.devtoolsBridge.emitSnapshot()
 
     // If stream is in progress, queue the response for after it ends
     if (this.isLoading) {
@@ -602,6 +755,8 @@ export class ChatClient {
     // Reset pending tool executions for the new stream
     this.pendingToolExecutions.clear()
     let streamCompletedSuccessfully = false
+    let activeDevtoolsRunId: string | null = null
+    let runTerminalEventEmitted = false
 
     try {
       // Get UIMessages with parts (preserves approval state and client tool results)
@@ -639,6 +794,7 @@ export class ChatClient {
 
       // Generate stream ID — assistant message will be created by stream events
       this.currentStreamId = this.generateUniqueId('stream')
+      this.devtoolsBridge.setCurrentStreamId(this.currentStreamId)
       this.currentMessageId = null
 
       // Reset processor stream state for new response — prevents stale
@@ -674,6 +830,19 @@ export class ChatClient {
         ),
         forwardedProps: { ...mergedBody },
       }
+      this.devtoolsBridge.beginRun(runContext.runId, this.threadId)
+      activeDevtoolsRunId = runContext.runId
+      this.devtoolsBridge.emitRunLifecycle(
+        'run:created',
+        runContext.runId,
+        'created',
+      )
+      this.devtoolsBridge.emitRunLifecycle(
+        'run:started',
+        runContext.runId,
+        'started',
+      )
+      this.devtoolsBridge.emitSnapshot()
 
       // Send through normalized connection (pushes chunks to subscription queue)
       await this.connection.send(messages, mergedBody, signal, runContext)
@@ -690,6 +859,15 @@ export class ChatClient {
       // A RUN_ERROR from the stream transitions status to error.
       // Do not treat this stream as a successful completion.
       if (this.status === 'error') {
+        if (activeDevtoolsRunId) {
+          this.devtoolsBridge.emitRunLifecycle(
+            'run:errored',
+            activeDevtoolsRunId,
+            'errored',
+            this.error ? { error: this.error.message } : {},
+          )
+          runTerminalEventEmitted = true
+        }
         return false
       }
 
@@ -704,10 +882,27 @@ export class ChatClient {
     } catch (err) {
       if (err instanceof Error) {
         if (err.name === 'AbortError') {
+          if (activeDevtoolsRunId) {
+            this.devtoolsBridge.emitRunLifecycle(
+              'run:cancelled',
+              activeDevtoolsRunId,
+              'cancelled',
+            )
+            runTerminalEventEmitted = true
+          }
           return false
         }
         if (generation === this.streamGeneration) {
           this.reportStreamError(err)
+          if (activeDevtoolsRunId) {
+            this.devtoolsBridge.emitRunLifecycle(
+              'run:errored',
+              activeDevtoolsRunId,
+              'errored',
+              { error: err.message },
+            )
+            runTerminalEventEmitted = true
+          }
         }
       }
     } finally {
@@ -716,11 +911,28 @@ export class ChatClient {
       // clobber the new stream's abortController or isLoading state.
       if (generation === this.streamGeneration) {
         this.currentStreamId = null
+        this.devtoolsBridge.setCurrentStreamId(null)
         this.currentMessageId = null
         this.abortController = null
         this.setIsLoading(false)
         this.pendingMessageBody = undefined // Ensure it's cleared even on error
 
+        if (activeDevtoolsRunId && !runTerminalEventEmitted) {
+          if (streamCompletedSuccessfully) {
+            this.devtoolsBridge.emitRunLifecycle(
+              'run:completed',
+              activeDevtoolsRunId,
+              'completed',
+            )
+          } else if (signal.aborted) {
+            this.devtoolsBridge.emitRunLifecycle(
+              'run:cancelled',
+              activeDevtoolsRunId,
+              'cancelled',
+            )
+          }
+        }
+
         // Drain any actions that were queued while the stream was in progress
         await this.drainPostStreamActions()
 
@@ -792,7 +1004,7 @@ export class ChatClient {
 
     // Find the last user message
     const lastUserMessageIndex = messages.findLastIndex(
-      (m: UIMessage) => m.role === 'user',
+      (m) => m.role === 'user',
     )
 
     if (lastUserMessageIndex === -1) return
@@ -806,6 +1018,7 @@ export class ChatClient {
 
     // Remove all messages after the last user message
     this.processor.removeMessagesAfter(lastUserMessageIndex)
+    this.devtoolsBridge.emitSnapshot()
 
     // Resend
     await this.streamResponse()
@@ -838,11 +1051,25 @@ export class ChatClient {
     state?: 'output-available' | 'output-error'
     errorText?: string
   }): Promise<void> {
+    await this.addToolResultInternal(result)
+  }
+
+  private async addToolResultInternal(
+    result: {
+      toolCallId: string
+      tool: string
+      output: any
+      state?: 'output-available' | 'output-error'
+      errorText?: string
+    },
+    context?: ChatClientRunEventContext,
+  ): Promise<void> {
     this.events.toolResultAdded(
       result.toolCallId,
       result.tool,
       result.output,
       result.state || 'output-available',
+      context,
     )
 
     // Add result via processor
@@ -893,6 +1120,7 @@ export class ChatClient {
 
     // Add response via processor
     this.processor.addToolApprovalResponse(response.id, response.approved)
+    this.devtoolsBridge.emitSnapshot()
 
     // If stream is in progress, queue continuation check for after it ends
     if (this.isLoading) {
@@ -964,9 +1192,13 @@ export class ChatClient {
    */
   private shouldAutoSend(): boolean {
     const messages = this.processor.getMessages()
-    const lastAssistant = messages.findLast((m) => m.role === 'assistant')
+    const lastAssistant = messages.findLast(
+      (m: UIMessage) => m.role === 'assistant',
+    )
     if (!lastAssistant) return false
-    const hasToolCalls = lastAssistant.parts.some((p) => p.type === 'tool-call')
+    const hasToolCalls = lastAssistant.parts.some(
+      (p: MessagePart) => p.type === 'tool-call',
+    )
     if (!hasToolCalls) return false
     return this.processor.areAllToolsComplete()
   }
@@ -1028,6 +1260,7 @@ export class ChatClient {
    */
   setMessagesManually(messages: Array<UIMessage>): void {
     this.processor.setMessages(messages)
+    this.devtoolsBridge.emitSnapshot()
   }
 
   /**
@@ -1035,6 +1268,7 @@ export class ChatClient {
    */
   updateOptions(options: {
     connection?: ConnectionAdapter
+    fetcher?: ChatFetcher
     /** @deprecated Use `forwardedProps` instead. */
     body?: Record<string, any>
     forwardedProps?: Record<string, any>
@@ -1052,7 +1286,7 @@ export class ChatClient {
       context: { toolCallId?: string },
     ) => void
   }): void {
-    if (options.connection !== undefined) {
+    if (options.connection !== undefined || options.fetcher !== undefined) {
       const wasSubscribed = this.isSubscribed
 
       if (this.isLoading) {
@@ -1067,7 +1301,12 @@ export class ChatClient {
       this.resetSessionGenerating()
       this.setIsSubscribed(false)
       this.setConnectionStatus('disconnected')
-      this.connection = normalizeConnectionAdapter(options.connection)
+      this.connection = normalizeConnectionAdapter(
+        resolveTransport({
+          connection: options.connection,
+          fetcher: options.fetcher,
+        }),
+      )
 
       if (wasSubscribed) {
         this.subscribe()
@@ -1075,7 +1314,7 @@ export class ChatClient {
     }
     // Replace each slot independently so callers can update one without
     // wiping the other. (Passing `undefined` for either field is a "leave
-    // unchanged" signal — to clear a slot, pass an empty object `{}`.)
+    // unchanged" signal - to clear a slot, pass an empty object `{}`.)
     if (options.body !== undefined) {
       this.bodyOption = options.body
     }
@@ -1087,6 +1326,7 @@ export class ChatClient {
       for (const tool of options.tools) {
         this.clientToolsRef.current.set(tool.name, tool)
       }
+      this.devtoolsBridge.notifyToolsChanged()
     }
     if (options.onResponse !== undefined) {
       this.callbacksRef.current.onResponse = options.onResponse
@@ -1116,4 +1356,10 @@ export class ChatClient {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent
     }
   }
+
+  dispose(): void {
+    this.unsubscribe()
+    this.devtoolsBridge.dispose()
+    this.devtoolsMounted = false
+  }
 }