@tanstack/ai-client 0.11.8 → 0.13.0

package/dist/esm/chat-client.d.ts

@@ -1,6 +1,6 @@
 import { AnyClientTool, ModelMessage, StreamChunk } from '@tanstack/ai';
 import { ConnectionAdapter } from './connection-adapters.js';
-import { ChatClientOptions, ChatClientState, ConnectionStatus, MultimodalContent, UIMessage } from './types.js';
+import { ChatClientOptions, ChatClientState, ChatFetcher, ConnectionStatus, MultimodalContent, UIMessage } from './types.js';
 export declare class ChatClient {
     private readonly processor;
     private connection;
@@ -15,8 +15,15 @@ export declare class ChatClient {
     private status;
     private connectionStatus;
     private abortController;
-    private readonly events;
     private readonly clientToolsRef;
+    private readonly devtoolsBridge;
+    /**
+     * 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;
     private currentStreamId;
     private currentMessageId;
     private readonly postStreamActions;
@@ -30,8 +37,10 @@ export declare class ChatClient {
     private draining;
     private sessionGenerating;
     private readonly activeRunIds;
+    private devtoolsMounted;
     private readonly callbacksRef;
     constructor(options: ChatClientOptions);
+    mountDevtools(): void;
     private generateUniqueId;
     private setIsLoading;
     private setStatus;
@@ -40,6 +49,9 @@ export declare class ChatClient {
     private setSessionGenerating;
     private resetSessionGenerating;
     private setError;
+    private buildDevtoolsBridgeOptions;
+    private getDevtoolsSnapshot;
+    private findMessageIdForToolCall;
     private abortSubscriptionLoop;
     private resolveProcessing;
     private cancelInFlightStream;
@@ -149,6 +161,7 @@ export declare class ChatClient {
         state?: 'output-available' | 'output-error';
         errorText?: string;
     }): Promise<void>;
+    private addToolResultInternal;
     /**
      * Respond to a tool approval request
      */
@@ -214,6 +227,7 @@ export declare class ChatClient {
      */
     updateOptions(options: {
         connection?: ConnectionAdapter;
+        fetcher?: ChatFetcher;
         /** @deprecated Use `forwardedProps` instead. */
         body?: Record<string, any>;
         forwardedProps?: Record<string, any>;
@@ -229,4 +243,5 @@ export declare class ChatClient {
             toolCallId?: string;
         }) => void;
     }): void;
+    dispose(): void;
 }

package/dist/esm/chat-client.js

@@ -1,6 +1,17 @@
 import { StreamProcessor, normalizeToUIMessage, generateMessageId, convertSchemaToJsonSchema } from "@tanstack/ai";
-import { DefaultChatClientEventEmitter } from "./events.js";
-import { normalizeConnectionAdapter } from "./connection-adapters.js";
+import { createNoOpChatDevtoolsBridge } from "./devtools-noop.js";
+import { normalizeConnectionAdapter, fetcherToConnectionAdapter } from "./connection-adapters.js";
+function resolveTransport(transport) {
+  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.");
+}
 class ChatClient {
   processor;
   connection;
@@ -19,8 +30,15 @@ class ChatClient {
   status = "ready";
   connectionStatus = "disconnected";
   abortController = null;
-  events;
   clientToolsRef;
+  devtoolsBridge;
+  /**
+   * 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.
+   */
+  events;
   currentStreamId = null;
   currentMessageId = null;
   postStreamActions = [];
@@ -38,20 +56,22 @@ class ChatClient {
   draining = false;
   sessionGenerating = false;
   activeRunIds = /* @__PURE__ */ new Set();
+  devtoolsMounted = false;
   callbacksRef;
   constructor(options) {
     this.uniqueId = options.id || this.generateUniqueId("chat");
     this.threadId = options.threadId || this.generateUniqueId("thread");
     this.bodyOption = options.body || {};
     this.forwardedPropsOption = options.forwardedProps || {};
-    this.connection = normalizeConnectionAdapter(options.connection);
-    this.events = new DefaultChatClientEventEmitter(this.uniqueId);
+    this.connection = normalizeConnectionAdapter(resolveTransport(options));
     this.clientToolsRef = { current: /* @__PURE__ */ new Map() };
     if (options.tools) {
       for (const tool of options.tools) {
         this.clientToolsRef.current.set(tool.name, tool);
       }
     }
+    this.devtoolsBridge = (options.devtoolsBridgeFactory ?? createNoOpChatDevtoolsBridge)(this.buildDevtoolsBridgeOptions(options.devtools));
+    this.events = this.devtoolsBridge.events;
     this.callbacksRef = {
       current: {
         onResponse: options.onResponse || (() => {
@@ -123,10 +143,30 @@ class ChatClient {
             this.events.thinkingUpdated(
               this.currentStreamId,
               messageId,
-              content
+              content,
+              void 0
             );
           }
         },
+        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 !== void 0 ? { partial: args.partial } : {},
+              ...args.data !== void 0 ? { data: args.data } : {},
+              ...args.reasoning !== void 0 ? { reasoning: args.reasoning } : {},
+              ...args.errorMessage !== void 0 ? { errorMessage: args.errorMessage } : {},
+              ...args.delta !== void 0 ? { delta: args.delta } : {}
+            }
+          );
+        },
         onToolCallStateChange: (messageId, toolCallId, state, args) => {
           const messages = this.processor.getMessages();
           const message = messages.find((m) => m.id === messageId);
@@ -149,23 +189,30 @@ class ChatClient {
           const clientTool = this.clientToolsRef.current.get(args.toolName);
           const executeFunc = clientTool?.execute;
           if (executeFunc) {
+            const runEventContext = this.devtoolsBridge.getCurrentRunEventContext();
             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) {
-                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 {
                 this.pendingToolExecutions.delete(args.toolCallId);
               }
@@ -174,23 +221,29 @@ class ChatClient {
           }
         },
         onApprovalRequest: (args) => {
-          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, data, context) => {
           this.callbacksRef.current.onCustomEvent(eventType, data, context);
         }
       }
     });
-    this.events.clientCreated(this.processor.getMessages().length);
+  }
+  mountDevtools() {
+    if (this.devtoolsMounted) {
+      return;
+    }
+    this.devtoolsMounted = true;
+    this.devtoolsBridge.mountWithTools(this.processor.getMessages().length);
   }
   generateUniqueId(prefix) {
     return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
@@ -203,19 +256,23 @@ class ChatClient {
   setStatus(status) {
     this.status = status;
     this.callbacksRef.current.onStatusChange(status);
+    this.devtoolsBridge.emitSnapshot();
   }
   setIsSubscribed(isSubscribed) {
     this.isSubscribed = isSubscribed;
     this.callbacksRef.current.onSubscriptionChange(isSubscribed);
+    this.devtoolsBridge.emitSnapshot();
   }
   setConnectionStatus(status) {
     this.connectionStatus = status;
     this.callbacksRef.current.onConnectionStatusChange(status);
+    this.devtoolsBridge.emitSnapshot();
   }
   setSessionGenerating(isGenerating) {
     if (this.sessionGenerating === isGenerating) return;
     this.sessionGenerating = isGenerating;
     this.callbacksRef.current.onSessionGeneratingChange(isGenerating);
+    this.devtoolsBridge.emitSnapshot();
   }
   resetSessionGenerating() {
     this.activeRunIds.clear();
@@ -226,6 +283,51 @@ class ChatClient {
     this.callbacksRef.current.onErrorChange(error);
     this.events.errorChanged(error?.message || null);
   }
+  buildDevtoolsBridgeOptions(devtools) {
+    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) => {
+        this.processor.setMessages(messages);
+      },
+      addToolResult: (toolCallId, output, errorText) => {
+        this.processor.addToolResult(toolCallId, output, errorText);
+      },
+      generateId: (prefix) => this.generateUniqueId(prefix)
+    };
+  }
+  getDevtoolsSnapshot() {
+    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 } : {}
+    };
+  }
+  findMessageIdForToolCall(toolCallId) {
+    const messages = this.processor.getMessages();
+    for (const message of messages) {
+      const match = message.parts.find(
+        (part) => part.type === "tool-call" && part.id === toolCallId
+      );
+      if (match) return message.id;
+    }
+    return void 0;
+  }
   abortSubscriptionLoop() {
     this.subscriptionAbortController?.abort();
     this.subscriptionAbortController = null;
@@ -295,13 +397,14 @@ 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);
       if (chunk.type === "RUN_FINISHED" || chunk.type === "RUN_ERROR") {
-        const runId = chunk.type === "RUN_FINISHED" ? chunk.runId : chunk.runId;
+        const runId = "runId" in chunk && typeof chunk.runId === "string" ? chunk.runId : void 0;
         if (runId) {
           this.activeRunIds.delete(runId);
         } else if (chunk.type === "RUN_ERROR") {
@@ -375,6 +478,7 @@ class ChatClient {
    * ```
    */
   async sendMessage(content, body) {
+    this.mountDevtools();
     const emptyMessage = typeof content === "string" && !content.trim();
     if (emptyMessage || this.isLoading) {
       return;
@@ -402,6 +506,7 @@ class ChatClient {
    * Append a message and stream the response
    */
   async append(message) {
+    this.mountDevtools();
     const normalizedMessage = normalizeToUIMessage(message, generateMessageId);
     if (normalizedMessage.role === "system") {
       return;
@@ -410,6 +515,7 @@ class ChatClient {
     this.events.messageAppended(uiMessage);
     const messages = this.processor.getMessages();
     this.processor.setMessages([...messages, uiMessage]);
+    this.devtoolsBridge.emitSnapshot();
     if (this.isLoading) {
       this.queuePostStreamAction(async () => {
         await this.streamResponse();
@@ -435,6 +541,8 @@ class ChatClient {
     const signal = this.abortController.signal;
     this.pendingToolExecutions.clear();
     let streamCompletedSuccessfully = false;
+    let activeDevtoolsRunId = null;
+    let runTerminalEventEmitted = false;
     try {
       const messages = this.processor.getMessages();
       await this.callbacksRef.current.onResponse();
@@ -448,6 +556,7 @@ class ChatClient {
       };
       this.pendingMessageBody = void 0;
       this.currentStreamId = this.generateUniqueId("stream");
+      this.devtoolsBridge.setCurrentStreamId(this.currentStreamId);
       this.currentMessageId = null;
       this.processor.prepareAssistantMessage();
       this.ensureSubscription();
@@ -464,12 +573,34 @@ 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();
       await this.connection.send(messages, mergedBody, signal, runContext);
       await processingComplete;
       if (generation !== this.streamGeneration) {
         return false;
       }
       if (this.status === "error") {
+        if (activeDevtoolsRunId) {
+          this.devtoolsBridge.emitRunLifecycle(
+            "run:errored",
+            activeDevtoolsRunId,
+            "errored",
+            this.error ? { error: this.error.message } : {}
+          );
+          runTerminalEventEmitted = true;
+        }
         return false;
       }
       if (this.pendingToolExecutions.size > 0) {
@@ -480,19 +611,52 @@ 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 {
       if (generation === this.streamGeneration) {
         this.currentStreamId = null;
+        this.devtoolsBridge.setCurrentStreamId(null);
         this.currentMessageId = null;
         this.abortController = null;
         this.setIsLoading(false);
         this.pendingMessageBody = void 0;
+        if (activeDevtoolsRunId && !runTerminalEventEmitted) {
+          if (streamCompletedSuccessfully) {
+            this.devtoolsBridge.emitRunLifecycle(
+              "run:completed",
+              activeDevtoolsRunId,
+              "completed"
+            );
+          } else if (signal.aborted) {
+            this.devtoolsBridge.emitRunLifecycle(
+              "run:cancelled",
+              activeDevtoolsRunId,
+              "cancelled"
+            );
+          }
+        }
         await this.drainPostStreamActions();
         if (streamCompletedSuccessfully) {
           const messages = this.processor.getMessages();
@@ -554,6 +718,7 @@ class ChatClient {
     }
     this.events.reloaded(lastUserMessageIndex);
     this.processor.removeMessagesAfter(lastUserMessageIndex);
+    this.devtoolsBridge.emitSnapshot();
     await this.streamResponse();
   }
   /**
@@ -575,11 +740,15 @@ class ChatClient {
    * Add the result of a client-side tool execution
    */
   async addToolResult(result) {
+    await this.addToolResultInternal(result);
+  }
+  async addToolResultInternal(result, context) {
     this.events.toolResultAdded(
       result.toolCallId,
       result.tool,
       result.output,
-      result.state || "output-available"
+      result.state || "output-available",
+      context
     );
     this.processor.addToolResult(
       result.toolCallId,
@@ -615,6 +784,7 @@ class ChatClient {
       );
     }
     this.processor.addToolApprovalResponse(response.id, response.approved);
+    this.devtoolsBridge.emitSnapshot();
     if (this.isLoading) {
       this.queuePostStreamAction(() => this.checkForContinuation());
       return;
@@ -672,9 +842,13 @@ class ChatClient {
    */
   shouldAutoSend() {
     const messages = this.processor.getMessages();
-    const lastAssistant = messages.findLast((m) => m.role === "assistant");
+    const lastAssistant = messages.findLast(
+      (m) => m.role === "assistant"
+    );
     if (!lastAssistant) return false;
-    const hasToolCalls = lastAssistant.parts.some((p) => p.type === "tool-call");
+    const hasToolCalls = lastAssistant.parts.some(
+      (p) => p.type === "tool-call"
+    );
     if (!hasToolCalls) return false;
     return this.processor.areAllToolsComplete();
   }
@@ -728,12 +902,13 @@ class ChatClient {
    */
   setMessagesManually(messages) {
     this.processor.setMessages(messages);
+    this.devtoolsBridge.emitSnapshot();
   }
   /**
    * Update options refs (for use in React hooks to avoid recreating client)
    */
   updateOptions(options) {
-    if (options.connection !== void 0) {
+    if (options.connection !== void 0 || options.fetcher !== void 0) {
       const wasSubscribed = this.isSubscribed;
       if (this.isLoading) {
         this.cancelInFlightStream({
@@ -746,7 +921,12 @@ 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();
       }
@@ -762,6 +942,7 @@ class ChatClient {
       for (const tool of options.tools) {
         this.clientToolsRef.current.set(tool.name, tool);
       }
+      this.devtoolsBridge.notifyToolsChanged();
     }
     if (options.onResponse !== void 0) {
       this.callbacksRef.current.onResponse = options.onResponse;
@@ -788,6 +969,11 @@ class ChatClient {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent;
     }
   }
+  dispose() {
+    this.unsubscribe();
+    this.devtoolsBridge.dispose();
+    this.devtoolsMounted = false;
+  }
 }
 export {
   ChatClient