@tanstack/ai-client 0.7.1 → 0.7.4

package/README.md

@@ -87,18 +87,18 @@ Available adapters: `openaiText`, `openaiEmbed`, `openaiSummarize`, `anthropicTe
     <td>
       <a href="https://www.coderabbit.ai/?via=tanstack&dub_id=aCcEEdAOqqutX6OS" >
         <picture>
-          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-CMcuvjEy.svg" height="40" />
-          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" />
-          <img src="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" alt="CodeRabbit" />
+         <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-D643Zkrv.svg" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-CIzGLYU_.svg" />
+          <img src="https://tanstack.com/assets/coderabbit-light-CIzGLYU_.svg" height="40" alt="CodeRabbit" />
         </picture>
       </a>
     </td>
     <td>
       <a href="https://www.cloudflare.com?utm_source=tanstack">
         <picture>
-          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-DQDB7UaL.svg" height="60" />
-          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" />
-          <img src="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" alt="Cloudflare" />
+           <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-Co-Tyjbl.svg" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-6Ojsn8yh.svg" />
+          <img src="https://tanstack.com/assets/cloudflare-white-Co-Tyjbl.svg" height="60" alt="Cloudflare" />
         </picture>
       </a>
     </td>

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, MultimodalContent, UIMessage } from './types.js';
+import { ChatClientOptions, ChatClientState, ConnectionStatus, MultimodalContent, UIMessage } from './types.js';
 export declare class ChatClient {
     private processor;
     private connection;
@@ -8,8 +8,10 @@ export declare class ChatClient {
     private body;
     private pendingMessageBody;
     private isLoading;
+    private isSubscribed;
     private error;
     private status;
+    private connectionStatus;
     private abortController;
     private events;
     private clientToolsRef;
@@ -18,17 +20,44 @@ export declare class ChatClient {
     private postStreamActions;
     private pendingToolExecutions;
     private continuationPending;
+    private subscriptionAbortController;
+    private processingResolve;
+    private errorReportedGeneration;
+    private streamGeneration;
     private continuationSkipped;
+    private sessionGenerating;
+    private activeRunIds;
     private callbacksRef;
     constructor(options: ChatClientOptions);
     private generateUniqueId;
     private setIsLoading;
     private setStatus;
+    private setIsSubscribed;
+    private setConnectionStatus;
+    private setSessionGenerating;
+    private resetSessionGenerating;
     private setError;
+    private abortSubscriptionLoop;
+    private resolveProcessing;
+    private cancelInFlightStream;
+    private reportStreamError;
     /**
-     * Process a stream through the StreamProcessor
+     * Start the background subscription loop.
      */
-    private processStream;
+    private startSubscription;
+    /**
+     * Consume chunks from the connection subscription.
+     */
+    private consumeSubscription;
+    /**
+     * Ensure subscription loop is running, starting it if needed.
+     */
+    private ensureSubscription;
+    /**
+     * Create a promise that resolves when onStreamEnd fires.
+     * Used by streamResponse to await processing completion.
+     */
+    private waitForProcessing;
     /**
      * Send a message and stream the response.
      * Supports both simple string content and multimodal content (images, audio, video, documents).
@@ -83,6 +112,18 @@ export declare class ChatClient {
      * Returns true if the stream completed successfully, false on abort or error.
      */
     private streamResponse;
+    /**
+     * Start the client subscription loop.
+     * This controls the connection lifecycle independently from request lifecycle.
+     */
+    subscribe(options?: {
+        restart?: boolean;
+    }): void;
+    /**
+     * Unsubscribe and fully tear down live behavior.
+     * This aborts an in-flight request and the subscription loop.
+     */
+    unsubscribe(): void;
     /**
      * Reload the last assistant message
      */
@@ -140,6 +181,21 @@ export declare class ChatClient {
      * Get current status
      */
     getStatus(): ChatClientState;
+    /**
+     * Get whether the subscription loop is active
+     */
+    getIsSubscribed(): boolean;
+    /**
+     * Get current connection lifecycle status
+     */
+    getConnectionStatus(): ConnectionStatus;
+    /**
+     * Whether the shared session is actively generating.
+     * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+     * Unlike `isLoading` (request-local), this reflects shared generation
+     * activity visible to all subscribers (e.g. across tabs/devices).
+     */
+    getSessionGenerating(): boolean;
     /**
      * Get current error
      */
@@ -159,6 +215,9 @@ export declare class ChatClient {
         onChunk?: (chunk: StreamChunk) => void;
         onFinish?: (message: UIMessage) => void;
         onError?: (error: Error) => void;
+        onSubscriptionChange?: (isSubscribed: boolean) => void;
+        onConnectionStatusChange?: (status: ConnectionStatus) => void;
+        onSessionGeneratingChange?: (isGenerating: boolean) => void;
         onCustomEvent?: (eventType: string, data: unknown, context: {
             toolCallId?: string;
         }) => void;

package/dist/esm/chat-client.js

@@ -1,22 +1,31 @@
 import { StreamProcessor, normalizeToUIMessage, generateMessageId } from "@tanstack/ai";
 import { DefaultChatClientEventEmitter } from "./events.js";
+import { normalizeConnectionAdapter } from "./connection-adapters.js";
 class ChatClient {
   constructor(options) {
     this.body = {};
     this.pendingMessageBody = void 0;
     this.isLoading = false;
+    this.isSubscribed = false;
     this.error = void 0;
     this.status = "ready";
+    this.connectionStatus = "disconnected";
     this.abortController = null;
     this.currentStreamId = null;
     this.currentMessageId = null;
     this.postStreamActions = [];
     this.pendingToolExecutions = /* @__PURE__ */ new Map();
     this.continuationPending = false;
+    this.subscriptionAbortController = null;
+    this.processingResolve = null;
+    this.errorReportedGeneration = null;
+    this.streamGeneration = 0;
     this.continuationSkipped = false;
+    this.sessionGenerating = false;
+    this.activeRunIds = /* @__PURE__ */ new Set();
     this.uniqueId = options.id || this.generateUniqueId("chat");
     this.body = options.body || {};
-    this.connection = options.connection;
+    this.connection = normalizeConnectionAdapter(options.connection);
     this.events = new DefaultChatClientEventEmitter(this.uniqueId);
     this.clientToolsRef = { current: /* @__PURE__ */ new Map() };
     if (options.tools) {
@@ -42,6 +51,12 @@ class ChatClient {
         }),
         onStatusChange: options.onStatusChange || (() => {
         }),
+        onSubscriptionChange: options.onSubscriptionChange || (() => {
+        }),
+        onConnectionStatusChange: options.onConnectionStatusChange || (() => {
+        }),
+        onSessionGeneratingChange: options.onSessionGeneratingChange || (() => {
+        }),
         onCustomEvent: options.onCustomEvent || (() => {
         })
       }
@@ -55,15 +70,29 @@ class ChatClient {
         },
         onStreamStart: () => {
           this.setStatus("streaming");
+          const assistantMessageId = this.processor.getCurrentAssistantMessageId();
+          if (!assistantMessageId) {
+            return;
+          }
+          const messages = this.processor.getMessages();
+          const assistantMessage = messages.find(
+            (m) => m.id === assistantMessageId
+          );
+          if (assistantMessage) {
+            this.currentMessageId = assistantMessage.id;
+            this.events.messageAppended(
+              assistantMessage,
+              this.currentStreamId || void 0
+            );
+          }
         },
         onStreamEnd: (message) => {
           this.callbacksRef.current.onFinish(message);
           this.setStatus("ready");
+          this.resolveProcessing();
         },
         onError: (error) => {
-          this.setError(error);
-          this.setStatus("error");
-          this.callbacksRef.current.onError(error);
+          this.reportStreamError(error);
         },
         onTextUpdate: (messageId, content) => {
           if (this.currentStreamId) {
@@ -156,47 +185,135 @@ class ChatClient {
     this.status = status;
     this.callbacksRef.current.onStatusChange(status);
   }
+  setIsSubscribed(isSubscribed) {
+    this.isSubscribed = isSubscribed;
+    this.callbacksRef.current.onSubscriptionChange(isSubscribed);
+  }
+  setConnectionStatus(status) {
+    this.connectionStatus = status;
+    this.callbacksRef.current.onConnectionStatusChange(status);
+  }
+  setSessionGenerating(isGenerating) {
+    if (this.sessionGenerating === isGenerating) return;
+    this.sessionGenerating = isGenerating;
+    this.callbacksRef.current.onSessionGeneratingChange(isGenerating);
+  }
+  resetSessionGenerating() {
+    this.activeRunIds.clear();
+    this.setSessionGenerating(false);
+  }
   setError(error) {
     this.error = error;
     this.callbacksRef.current.onErrorChange(error);
     this.events.errorChanged(error?.message || null);
   }
+  abortSubscriptionLoop() {
+    this.subscriptionAbortController?.abort();
+    this.subscriptionAbortController = null;
+  }
+  resolveProcessing() {
+    this.processingResolve?.();
+    this.processingResolve = null;
+  }
+  cancelInFlightStream(options) {
+    this.abortController?.abort();
+    this.abortController = null;
+    if (options?.abortSubscription) {
+      this.abortSubscriptionLoop();
+    }
+    this.resolveProcessing();
+    this.setIsLoading(false);
+    if (options?.setReadyStatus) {
+      this.setStatus("ready");
+    }
+  }
+  reportStreamError(error) {
+    const alreadyReported = this.errorReportedGeneration === this.streamGeneration;
+    this.setError(error);
+    if (this.isLoading || this.status === "submitted" || this.status === "streaming") {
+      this.setStatus("error");
+    }
+    if (!alreadyReported) {
+      this.errorReportedGeneration = this.streamGeneration;
+      this.callbacksRef.current.onError(error);
+    }
+  }
+  /**
+   * Start the background subscription loop.
+   */
+  startSubscription() {
+    this.subscriptionAbortController = new AbortController();
+    const signal = this.subscriptionAbortController.signal;
+    this.consumeSubscription(signal).catch((err) => {
+      if (err instanceof Error && err.name !== "AbortError") {
+        this.setConnectionStatus("error");
+        this.resetSessionGenerating();
+        this.setIsSubscribed(false);
+        this.reportStreamError(err);
+      }
+      this.resolveProcessing();
+    }).finally(() => {
+      if (this.subscriptionAbortController?.signal !== signal) {
+        return;
+      }
+      this.subscriptionAbortController = null;
+      if (!signal.aborted && this.isSubscribed) {
+        this.setIsSubscribed(false);
+        if (this.connectionStatus !== "error") {
+          this.setConnectionStatus("disconnected");
+        }
+      }
+    });
+  }
   /**
-   * Process a stream through the StreamProcessor
+   * Consume chunks from the connection subscription.
    */
-  async processStream(source) {
-    this.currentStreamId = this.generateUniqueId("stream");
-    this.processor.prepareAssistantMessage();
-    for await (const chunk of source) {
+  async consumeSubscription(signal) {
+    const stream = this.connection.subscribe(signal);
+    for await (const chunk of stream) {
+      if (signal.aborted) break;
+      if (this.connectionStatus === "connecting") {
+        this.setConnectionStatus("connected");
+      }
       this.callbacksRef.current.onChunk(chunk);
       this.processor.processChunk(chunk);
-      if (!this.currentMessageId) {
-        const newMessageId = this.processor.getCurrentAssistantMessageId() ?? null;
-        if (newMessageId) {
-          this.currentMessageId = newMessageId;
-          const assistantMessage = this.processor.getMessages().find((m) => m.id === newMessageId);
-          if (assistantMessage) {
-            this.events.messageAppended(
-              assistantMessage,
-              this.currentStreamId || void 0
-            );
-          }
+      if (chunk.type === "RUN_STARTED") {
+        this.activeRunIds.add(chunk.runId);
+        this.setSessionGenerating(true);
+      }
+      if (chunk.type === "RUN_FINISHED" || chunk.type === "RUN_ERROR") {
+        if (chunk.runId) {
+          this.activeRunIds.delete(chunk.runId);
+        } else if (chunk.type === "RUN_ERROR") {
+          this.activeRunIds.clear();
         }
+        this.setSessionGenerating(this.activeRunIds.size > 0);
+        this.resolveProcessing();
       }
       await new Promise((resolve) => setTimeout(resolve, 0));
     }
-    if (this.pendingToolExecutions.size > 0) {
-      await Promise.all(this.pendingToolExecutions.values());
+  }
+  /**
+   * Ensure subscription loop is running, starting it if needed.
+   */
+  ensureSubscription() {
+    if (!this.isSubscribed) {
+      this.subscribe();
+      return;
     }
-    this.processor.finalizeStream();
-    const messageId = this.processor.getCurrentAssistantMessageId();
-    this.currentStreamId = null;
-    this.currentMessageId = null;
-    if (messageId) {
-      const messages = this.processor.getMessages();
-      return messages.find((m) => m.id === messageId) || null;
+    if (!this.subscriptionAbortController || this.subscriptionAbortController.signal.aborted) {
+      this.subscribe({ restart: true });
     }
-    return null;
+  }
+  /**
+   * Create a promise that resolves when onStreamEnd fires.
+   * Used by streamResponse to await processing completion.
+   */
+  waitForProcessing() {
+    this.resolveProcessing();
+    return new Promise((resolve) => {
+      this.processingResolve = resolve;
+    });
   }
   /**
    * Send a message and stream the response.
@@ -289,9 +406,11 @@ class ChatClient {
     if (this.isLoading) {
       return false;
     }
+    const generation = ++this.streamGeneration;
     this.setIsLoading(true);
     this.setStatus("submitted");
     this.setError(void 0);
+    this.errorReportedGeneration = null;
     this.abortController = new AbortController();
     this.pendingToolExecutions.clear();
     let streamCompletedSuccessfully = false;
@@ -304,41 +423,89 @@ class ChatClient {
         conversationId: this.uniqueId
       };
       this.pendingMessageBody = void 0;
-      const stream = this.connection.connect(
+      this.currentStreamId = this.generateUniqueId("stream");
+      this.currentMessageId = null;
+      this.processor.prepareAssistantMessage();
+      this.ensureSubscription();
+      const processingComplete = this.waitForProcessing();
+      await this.connection.send(
         messages,
         mergedBody,
         this.abortController.signal
       );
-      await this.processStream(stream);
+      await processingComplete;
+      if (generation !== this.streamGeneration) {
+        return false;
+      }
+      if (this.status === "error") {
+        return false;
+      }
+      if (this.pendingToolExecutions.size > 0) {
+        await Promise.all(this.pendingToolExecutions.values());
+      }
+      this.processor.finalizeStream();
       streamCompletedSuccessfully = true;
     } catch (err) {
       if (err instanceof Error) {
         if (err.name === "AbortError") {
           return false;
         }
-        this.setError(err);
-        this.setStatus("error");
-        this.callbacksRef.current.onError(err);
+        if (generation === this.streamGeneration) {
+          this.reportStreamError(err);
+        }
       }
     } finally {
-      this.abortController = null;
-      this.setIsLoading(false);
-      this.pendingMessageBody = void 0;
-      await this.drainPostStreamActions();
-      if (streamCompletedSuccessfully) {
-        const messages = this.processor.getMessages();
-        const lastPart = messages.at(-1)?.parts.at(-1);
-        if (lastPart?.type === "tool-result" && this.shouldAutoSend()) {
-          try {
-            await this.checkForContinuation();
-          } catch (error) {
-            console.error("Failed to continue flow after tool result:", error);
+      if (generation === this.streamGeneration) {
+        this.currentStreamId = null;
+        this.currentMessageId = null;
+        this.abortController = null;
+        this.setIsLoading(false);
+        this.pendingMessageBody = void 0;
+        await this.drainPostStreamActions();
+        if (streamCompletedSuccessfully) {
+          const messages = this.processor.getMessages();
+          const lastPart = messages.at(-1)?.parts.at(-1);
+          if (lastPart?.type === "tool-result" && this.shouldAutoSend()) {
+            try {
+              await this.checkForContinuation();
+            } catch (error) {
+              console.error("Failed to continue flow after tool result:", error);
+            }
           }
         }
       }
     }
     return streamCompletedSuccessfully;
   }
+  /**
+   * Start the client subscription loop.
+   * This controls the connection lifecycle independently from request lifecycle.
+   */
+  subscribe(options) {
+    const restart = options?.restart === true;
+    if (this.isSubscribed && !restart) {
+      return;
+    }
+    if (this.isSubscribed && restart) {
+      this.abortSubscriptionLoop();
+    }
+    this.setIsSubscribed(true);
+    this.setConnectionStatus("connecting");
+    this.startSubscription();
+  }
+  /**
+   * Unsubscribe and fully tear down live behavior.
+   * This aborts an in-flight request and the subscription loop.
+   */
+  unsubscribe() {
+    this.cancelInFlightStream({
+      setReadyStatus: true,
+      abortSubscription: true
+    });
+    this.resetSessionGenerating();
+    this.setIsSubscribed(false);
+    this.setConnectionStatus("disconnected");
+  }
   /**
    * Reload the last assistant message
    */
@@ -349,6 +516,9 @@ class ChatClient {
       (m) => m.role === "user"
     );
     if (lastUserMessageIndex === -1) return;
+    if (this.isLoading) {
+      this.cancelInFlightStream();
+    }
     this.events.reloaded(lastUserMessageIndex);
     this.processor.removeMessagesAfter(lastUserMessageIndex);
     await this.streamResponse();
@@ -357,12 +527,7 @@ class ChatClient {
    * Stop the current stream
    */
   stop() {
-    if (this.abortController) {
-      this.abortController.abort();
-      this.abortController = null;
-    }
-    this.setIsLoading(false);
-    this.setStatus("ready");
+    this.cancelInFlightStream({ setReadyStatus: true });
     this.events.stopped();
   }
   /**
@@ -485,6 +650,27 @@ class ChatClient {
   getStatus() {
     return this.status;
   }
+  /**
+   * Get whether the subscription loop is active
+   */
+  getIsSubscribed() {
+    return this.isSubscribed;
+  }
+  /**
+   * Get current connection lifecycle status
+   */
+  getConnectionStatus() {
+    return this.connectionStatus;
+  }
+  /**
+   * Whether the shared session is actively generating.
+   * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+   * Unlike `isLoading` (request-local), this reflects shared generation
+   * activity visible to all subscribers (e.g. across tabs/devices).
+   */
+  getSessionGenerating() {
+    return this.sessionGenerating;
+  }
   /**
    * Get current error
    */
@@ -502,7 +688,22 @@ class ChatClient {
    */
   updateOptions(options) {
     if (options.connection !== void 0) {
-      this.connection = options.connection;
+      const wasSubscribed = this.isSubscribed;
+      if (this.isLoading) {
+        this.cancelInFlightStream({
+          setReadyStatus: true,
+          abortSubscription: true
+        });
+      } else if (wasSubscribed) {
+        this.abortSubscriptionLoop();
+      }
+      this.resetSessionGenerating();
+      this.setIsSubscribed(false);
+      this.setConnectionStatus("disconnected");
+      this.connection = normalizeConnectionAdapter(options.connection);
+      if (wasSubscribed) {
+        this.subscribe();
+      }
     }
     if (options.body !== void 0) {
       this.body = options.body;
@@ -525,6 +726,15 @@ class ChatClient {
     if (options.onError !== void 0) {
       this.callbacksRef.current.onError = options.onError;
     }
+    if (options.onSubscriptionChange !== void 0) {
+      this.callbacksRef.current.onSubscriptionChange = options.onSubscriptionChange;
+    }
+    if (options.onConnectionStatusChange !== void 0) {
+      this.callbacksRef.current.onConnectionStatusChange = options.onConnectionStatusChange;
+    }
+    if (options.onSessionGeneratingChange !== void 0) {
+      this.callbacksRef.current.onSessionGeneratingChange = options.onSessionGeneratingChange;
+    }
     if (options.onCustomEvent !== void 0) {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent;
     }