@dbx-tools/ui-mastra 0.3.7 → 0.3.8

package/README.md

@@ -140,13 +140,26 @@ import {
 } from "@dbx-tools/ui-mastra/react";
 
 const client = new MastraPluginClient(clientConfig);
-client.setModelOverride("claude sonnet");
-client.setThreadId(activeThreadId);
+
+// Routing (thread + model) is passed per call, so concurrent runs on
+// different threads never share state.
+const stream = await client.streamAgent({
+  agentId: client.defaultAgent,
+  messages: [{ role: "user", content: "Hello" }],
+  runId,
+  threadId: activeThreadId,
+  model: "claude sonnet",
+  signal: controller.signal,
+});
 
 const models = await client.models();
-const history = await client.history({ page: 0, perPage: 20 });
+const history = await client.history({ threadId: activeThreadId, page: 0, perPage: 20 });
 ```
 
+Each conversation thread runs independently: start a turn on one thread, switch
+to another and start a second, and both stream concurrently. Cancel one via its
+`AbortSignal` (or the driver's `onCancelThread`) without touching the others.
+
 `MastraPluginClient` extends `@mastra/client-js` with the AppKit-Mastra custom
 routes. It uses `credentials: "include"` so session cookies travel with streaming
 and REST calls. The React hooks wrap common route calls for model catalogues,

package/package.json

@@ -26,19 +26,19 @@
     "shiki": "^3.0.0",
     "sql-formatter": "^15.6.9",
     "streamdown": "^2.5.0",
-    "@dbx-tools/shared-core": "0.3.7",
-    "@dbx-tools/shared-genie": "0.3.7",
-    "@dbx-tools/shared-mastra": "0.3.7",
-    "@dbx-tools/ui-appkit": "0.3.7",
-    "@dbx-tools/shared-model": "0.3.7",
-    "@dbx-tools/ui-branding": "0.3.7"
+    "@dbx-tools/shared-core": "0.3.8",
+    "@dbx-tools/shared-mastra": "0.3.8",
+    "@dbx-tools/shared-model": "0.3.8",
+    "@dbx-tools/ui-appkit": "0.3.8",
+    "@dbx-tools/shared-genie": "0.3.8",
+    "@dbx-tools/ui-branding": "0.3.8"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.7",
+  "version": "0.3.8",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/react/chat-view.tsx

@@ -124,6 +124,7 @@ export const ChatView = ({
   onNewThread,
   onDeleteThread,
   onRenameThread,
+  onCancelThread,
   sidebarOpen: sidebarOpenProp,
   onToggleSidebar,
   onExportConversation,
@@ -424,6 +425,7 @@ export const ChatView = ({
                     : {})}
                   {...(onDeleteThread ? { onDelete: onDeleteThread } : {})}
                   {...(onRenameThread ? { onRename: onRenameThread } : {})}
+                  {...(onCancelThread ? { onCancel: onCancelThread } : {})}
                   onHide={toggleSidebar}
                   className="relative z-10 w-[85vw] max-w-xs shadow-xl"
                 />
@@ -444,6 +446,7 @@ export const ChatView = ({
                 {...(onNewThread ? { onNew: onNewThread } : {})}
                 {...(onDeleteThread ? { onDelete: onDeleteThread } : {})}
                 {...(onRenameThread ? { onRename: onRenameThread } : {})}
+                {...(onCancelThread ? { onCancel: onCancelThread } : {})}
                 onHide={toggleSidebar}
               />
             )
@@ -630,7 +633,7 @@ export const ChatView = ({
                     type="button"
                     size="icon-sm"
                     variant="default"
-                    onClick={onStop}
+                    onClick={() => onStop()}
                     aria-label="Stop response"
                   >
                     <SquareIcon className="size-3 fill-current" />

package/src/react/mastra-chat.tsx

@@ -246,18 +246,20 @@ export const useMastraChat = (
   // using it as a hook dep doesn't refire the initial-history fetch on
   // every parent render.
   const mastraClient = useMastraClient();
-  // Apply the selected model as a per-request override header in place,
-  // so the next `agent.stream()` picks it up without rebuilding the
-  // client (which would refire history loads on every model change).
-  useEffect(() => {
-    mastraClient.setModelOverride(model || undefined);
-  }, [mastraClient, model]);
+  // The selected model rides each turn as a per-call override (see
+  // `runStream`), never stored on the shared client - so two threads can
+  // stream under different models without clobbering each other. Mirror it
+  // into a ref so the send path reads the latest selection without adding
+  // `model` to its dependency list.
+  const modelRef = useRef(model);
+  modelRef.current = model;
   const agentId = options.agentId ?? mastraClient.defaultAgent;
   // Built-in conversation management. When on, the chat always drives an
   // explicit client thread id (rather than leaning on the per-session
   // cookie) so it can reference, persist, and switch between the
-  // conversations a user owns. Selecting a thread routes every call
-  // (stream + history + clear) at it via `mastraClient.setThreadId`.
+  // conversations a user owns. Each call (stream / history / clear) carries
+  // its thread id per request, so many threads can run concurrently without
+  // sharing routing state.
   const enableThreads = options.enableThreads !== false;
   // Export is opt-in (default off): the host turns it on explicitly.
   const enableExport = options.enableExport === true;
@@ -693,7 +695,7 @@ export const useMastraChat = (
     async (
       threadId: string,
       assistantId: string,
-      open: () => Promise<MastraStreamResponse>,
+      open: (signal: AbortSignal) => Promise<MastraStreamResponse>,
     ) => {
       const controller = new AbortController();
       let token = 0;
@@ -712,10 +714,7 @@ export const useMastraChat = (
       });
       const runIdRef = { current: getSession(threadId).runId };
       try {
-        const streamThreadId =
-          threadId === DEFAULT_THREAD_SESSION_KEY ? undefined : threadId;
-        mastraClient.setThreadId(streamThreadId);
-        const stream = await open();
+        const stream = await open(controller.signal);
         await processStream(threadId, stream, assistantId, runIdRef, controller.signal);
         updateSession(threadId, (session) => {
           if (session.runToken !== token) return session;
@@ -745,7 +744,7 @@ export const useMastraChat = (
         }));
       }
     },
-    [getSession, mastraClient, processStream, refreshThreadsSoon, updateSession],
+    [getSession, processStream, refreshThreadsSoon, updateSession],
   );
 
   const runStream = useCallback(
@@ -757,35 +756,53 @@ export const useMastraChat = (
         assistantId,
         runId,
       }));
-      return driveStream(threadId, assistantId, () => {
-        const agent = mastraClient.getAgent(agentId);
-        const messagesForAgent = history.flatMap((m) =>
+      // Capture this run's thread + model at send time and pass them per
+      // call, so a run keeps its own routing even if the user switches
+      // threads or changes the model picker while it streams.
+      const streamThreadId =
+        threadId === DEFAULT_THREAD_SESSION_KEY ? undefined : threadId;
+      const model = modelRef.current || undefined;
+      return driveStream(threadId, assistantId, (signal) => {
+        const messages = history.flatMap((m) =>
           m.parts
             .filter((p): p is { type: "text"; text: string } => p.type === "text")
             .map((p) => ({ role: m.role, content: p.text })),
-        ) as Parameters<typeof agent.stream>[0];
-        return agent.stream(messagesForAgent, {
+        );
+        return mastraClient.streamAgent({
+          agentId,
+          messages,
           runId,
-        }) as Promise<MastraStreamResponse>;
+          threadId: streamThreadId,
+          model,
+          signal,
+        });
       });
     },
     [driveStream, mastraClient, agentId, updateSession],
   );
 
-  const stop = useCallback(() => {
-    const threadId = activeKey;
-    updateSession(threadId, (session) => {
-      if (!isSessionRunning(session)) return session;
-      session.abortController?.abort();
-      return {
-        ...session,
-        abortController: null,
-        runToken: session.runToken + 1,
-        error: null,
-        status: "ready",
-      };
-    });
-  }, [activeKey, updateSession]);
+  // Cancel a thread's in-flight run. Defaults to the active thread (the
+  // composer stop button), but takes an explicit thread id so the sidebar
+  // can cancel a background thread without switching to it. Aborting one
+  // thread's controller leaves every other run streaming - each run owns
+  // its own controller and routing.
+  const stop = useCallback(
+    (threadId?: string) => {
+      const key = threadId ?? activeKey;
+      updateSession(key, (session) => {
+        if (!isSessionRunning(session)) return session;
+        session.abortController?.abort();
+        return {
+          ...session,
+          abortController: null,
+          runToken: session.runToken + 1,
+          error: null,
+          status: "ready",
+        };
+      });
+    },
+    [activeKey, updateSession],
+  );
 
   /**
    * Approve or deny an in-flight `requireApproval` tool call. The
@@ -830,10 +847,22 @@ export const useMastraChat = (
         toolCallId,
         runId,
       });
-      await driveStream(activeKey, assistantId, () =>
+      const streamThreadId =
+        activeKey === DEFAULT_THREAD_SESSION_KEY ? undefined : activeKey;
+      await driveStream(activeKey, assistantId, (signal) =>
         decision.approved
-          ? mastraClient.approveToolCallStream(agentId, { runId, toolCallId })
-          : mastraClient.declineToolCallStream(agentId, { runId, toolCallId }),
+          ? mastraClient.approveToolCallStream(agentId, {
+              runId,
+              toolCallId,
+              threadId: streamThreadId,
+              signal,
+            })
+          : mastraClient.declineToolCallStream(agentId, {
+              runId,
+              toolCallId,
+              threadId: streamThreadId,
+              signal,
+            }),
       );
     },
     [activeKey, driveStream, getSession, mastraClient, agentId, updateSession],
@@ -882,7 +911,7 @@ export const useMastraChat = (
   const handleClear = useCallback(async () => {
     const threadId = activeKey;
     try {
-      const result = await mastraClient.clearHistory({ agentId });
+      const result = await mastraClient.clearHistory({ agentId, threadId: activeThreadId });
       logger.info("history cleared", { cleared: result.cleared });
     } catch (error) {
       logger.error("history clear error", {
@@ -1039,7 +1068,6 @@ export const useMastraChat = (
   // refetching or aborting other threads' runs.
   useEffect(() => {
     const threadId = activeKey;
-    mastraClient.setThreadId(activeThreadId);
     const session = getSession(threadId);
     if (session.historyLoaded) {
       setIsLoadingHistory(false);
@@ -1053,6 +1081,7 @@ export const useMastraChat = (
     mastraClient
       .history({
         agentId,
+        threadId: activeThreadId,
         page: 0,
         perPage: HISTORY_PAGE_SIZE,
         signal: controller.signal,
@@ -1096,7 +1125,7 @@ export const useMastraChat = (
     const page = session.historyPage;
     updateSession(threadId, (current) => ({ ...current, historyPage: page + 1 }));
     mastraClient
-      .history({ agentId, page, perPage: HISTORY_PAGE_SIZE })
+      .history({ agentId, threadId: activeThreadId, page, perPage: HISTORY_PAGE_SIZE })
       .then((response) => {
         const uiMessages = response.uiMessages as unknown as UIMessage[];
         if (uiMessages.length > 0) {
@@ -1123,7 +1152,15 @@ export const useMastraChat = (
         historyInFlightRef.current = false;
         setIsLoadingMore(false);
       });
-  }, [activeKey, getSession, mastraClient, agentId, updateSession, writeMessages]);
+  }, [
+    activeKey,
+    activeThreadId,
+    getSession,
+    mastraClient,
+    agentId,
+    updateSession,
+    writeMessages,
+  ]);
 
   // Chat export (opt-in). Resolves `[chart:<id>]` / `[data:<id>]` embeds
   // straight off the client so the export inlines the same charts /
@@ -1356,6 +1393,9 @@ export const useMastraChat = (
           onNewThread: newThread,
           onDeleteThread: deleteThread,
           onRenameThread: renameThread,
+          // Cancel a background thread's run from the sidebar without
+          // switching to it.
+          onCancelThread: stop,
           // Persisted sidebar visibility, controlled from the driver so
           // the show/hide choice survives reloads.
           sidebarOpen,

package/src/react/thread-sidebar.tsx

@@ -13,6 +13,7 @@ import {
   MessageSquarePlusIcon,
   PanelLeftIcon,
   PencilIcon,
+  SquareIcon,
   Trash2Icon,
 } from "lucide-react";
 import { useState } from "react";
@@ -42,6 +43,12 @@ export interface ThreadSidebarProps {
   onDelete?: (threadId: string) => void;
   /** Rename a thread. Per-row edit affordance (inline text field) hidden when omitted. */
   onRename?: (threadId: string, title: string) => void;
+  /**
+   * Cancel a thread's in-flight run. When provided, a streaming row (one in
+   * {@link streamingThreadIds}) shows a stop button in place of its spinner
+   * on hover, so a background run can be cancelled without switching to it.
+   */
+  onCancel?: (threadId: string) => void;
   /** Collapse the sidebar. Renders the hide button in the header when provided. */
   onHide?: () => void;
   /** Extra classes merged onto the sidebar root. */
@@ -67,6 +74,7 @@ export const ThreadSidebar = ({
   onNew,
   onDelete,
   onRename,
+  onCancel,
   onHide,
   className,
 }: ThreadSidebarProps) => {
@@ -212,12 +220,34 @@ export const ThreadSidebar = ({
                   >
                     <div className="min-w-0 flex-1">
                       <div className="flex items-center gap-1.5 truncate">
-                        {isStreaming && (
-                          <Loader2Icon
-                            aria-label="Streaming"
-                            className="size-3 shrink-0 animate-spin text-primary"
-                          />
-                        )}
+                        {isStreaming &&
+                          (onCancel ? (
+                            <Tooltip>
+                              <TooltipTrigger asChild>
+                                <Button
+                                  type="button"
+                                  variant="ghost"
+                                  size="icon"
+                                  onClick={(e) => {
+                                    e.stopPropagation();
+                                    onCancel(thread.id);
+                                  }}
+                                  aria-label="Stop generating"
+                                  className="size-4 shrink-0 text-primary"
+                                >
+                                  {/* Spinner by default; swap to a stop square on hover/focus. */}
+                                  <Loader2Icon className="size-3 animate-spin group-hover:hidden" />
+                                  <SquareIcon className="hidden size-3 fill-current group-hover:block" />
+                                </Button>
+                              </TooltipTrigger>
+                              <TooltipContent>Stop generating</TooltipContent>
+                            </Tooltip>
+                          ) : (
+                            <Loader2Icon
+                              aria-label="Streaming"
+                              className="size-3 shrink-0 animate-spin text-primary"
+                            />
+                          ))}
                         <span className="truncate">{threadTitle(thread)}</span>
                       </div>
                       {thread.updatedAt && (

package/src/react/types.ts

@@ -99,7 +99,7 @@ export type ChatViewProps = {
    * to hide the Stop affordance (the Send button just disables while a
    * response streams).
    */
-  onStop?: () => void;
+  onStop?: (threadId?: string) => void;
   /** Extra classes merged onto the root layout container. */
   className?: string;
   /**
@@ -220,6 +220,13 @@ export type ChatViewProps = {
    * affordance that swaps the title into an inline text field.
    */
   onRenameThread?: (threadId: string, title: string) => void;
+  /**
+   * Cancel a thread's in-flight run by id, without switching to it. When
+   * provided, each running sidebar row shows a stop affordance next to its
+   * streaming indicator (see {@link streamingThreadIds}). Isolated to that
+   * thread - other threads keep streaming.
+   */
+  onCancelThread?: (threadId: string) => void;
   /**
    * Controlled open/closed state for the conversation sidebar. When
    * omitted the view manages its own (session-only) open state; pass

package/src/support/mastra-client.ts

@@ -72,43 +72,55 @@ export class MastraPluginClient extends MastraClient {
   }
 
   /**
-   * Set (or clear) the per-request model override sent on every
-   * streaming call as `X-Mastra-Model`. The Mastra plugin's middleware
-   * reads it and overrides the resolved model for that request without
-   * an agent redeploy. `model` is either a concrete endpoint name
-   * (fuzzy-matched server-side) or a model class slug
-   * (`ModelClass.ChatFast` / `"chat-thinking"`); pass `undefined` to
-   * fall back to the agent's configured default.
+   * Build the per-request routing headers for a call: the thread-selection
+   * header (`THREAD_ID_HEADER`) so the server pins `RequestContext`'s thread
+   * id, and the model-override header (`MODEL_OVERRIDE_HEADER`) so the server
+   * swaps the resolved model for that request without an agent redeploy.
    *
-   * Mutates the shared `options.headers` in place (rather than
-   * rebuilding the client) so the client identity stays stable across
-   * model changes - hooks can depend on it without refiring history
-   * loads when only the model changes.
+   * Routing is per-CALL - never stored on the shared client - so concurrent
+   * runs on different threads / models can't clobber each other's headers.
+   * `threadId` is a conversation id (omit to fall back to the per-session
+   * cookie thread); `model` is a concrete endpoint name (fuzzy-matched
+   * server-side) or a model-class slug (`"chat-fast"` / `"chat-thinking"`).
    */
-  setModelOverride(model?: string): void {
-    const headers = (this.options.headers ??= {});
-    if (model) headers[override.MODEL_OVERRIDE_HEADER] = model;
-    else delete headers[override.MODEL_OVERRIDE_HEADER];
+  #routingHeaders(routing: { threadId?: string; model?: string }): Record<string, string> {
+    const headers: Record<string, string> = {};
+    if (routing.threadId) headers[thread.THREAD_ID_HEADER] = routing.threadId;
+    if (routing.model) headers[override.MODEL_OVERRIDE_HEADER] = routing.model;
+    return headers;
   }
 
   /**
-   * Select (or clear) the conversation thread every subsequent request
-   * targets, sent as the thread-selection header (`THREAD_ID_HEADER`).
-   * The plugin's middleware pins `RequestContext`'s thread id to it, so
-   * the agent stream persists into - and `history()` reads from - the
-   * chosen thread instead of the default per-session one. Pass
-   * `undefined` to fall back to the session thread.
-   *
-   * Mutates the shared `options.headers` in place (like
-   * {@link setModelOverride}) so the client identity stays stable; the
-   * inherited `agent.stream()` and the custom routes
-   * ({@link history} / {@link clearHistory} / {@link threads}) all read
-   * these headers, so selecting a thread routes every call at once.
+   * Open an agent stream for one conversation turn, routed and cancelled
+   * PER CALL. Posts to the agent `/stream` route with this run's own thread
+   * id + model as request headers and its own `AbortSignal` on the fetch, so
+   * many threads can stream at once and aborting one leaves the others
+   * untouched. Reads the SSE directly (like the tool-approval streams) rather
+   * than through the inherited `agent.stream()`, whose shared-client headers
+   * and single client-level abort signal can't isolate concurrent runs.
    */
-  setThreadId(threadId?: string): void {
-    const headers = (this.options.headers ??= {});
-    if (threadId) headers[thread.THREAD_ID_HEADER] = threadId;
-    else delete headers[thread.THREAD_ID_HEADER];
+  async streamAgent(params: {
+    agentId: string;
+    messages: Array<{ role: string; content: string }>;
+    runId: string;
+    threadId?: string;
+    model?: string;
+    signal?: AbortSignal;
+  }): Promise<MastraStreamResponse> {
+    const url = `${this.basePath}/agents/${encodeURIComponent(params.agentId)}/stream`;
+    const init: RequestInit = {
+      method: "POST",
+      credentials: "include",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.#routingHeaders(params),
+      },
+      body: JSON.stringify({ messages: params.messages, runId: params.runId }),
+    };
+    if (params.signal) init.signal = params.signal;
+    const response = await fetch(url, init);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return asMastraStreamResponse(response);
   }
 
   /**
@@ -120,7 +132,7 @@ export class MastraPluginClient extends MastraClient {
    */
   async approveToolCallStream(
     agentId: string,
-    params: { runId: string; toolCallId: string },
+    params: { runId: string; toolCallId: string; threadId?: string; signal?: AbortSignal },
   ): Promise<MastraStreamResponse> {
     return this.#toolApprovalStream(agentId, "approve-tool-call", params);
   }
@@ -131,7 +143,7 @@ export class MastraPluginClient extends MastraClient {
    */
   async declineToolCallStream(
     agentId: string,
-    params: { runId: string; toolCallId: string },
+    params: { runId: string; toolCallId: string; threadId?: string; signal?: AbortSignal },
   ): Promise<MastraStreamResponse> {
     return this.#toolApprovalStream(agentId, "decline-tool-call", params);
   }
@@ -139,24 +151,22 @@ export class MastraPluginClient extends MastraClient {
   async #toolApprovalStream(
     agentId: string,
     route: "approve-tool-call" | "decline-tool-call",
-    params: { runId: string; toolCallId: string },
+    params: { runId: string; toolCallId: string; threadId?: string; signal?: AbortSignal },
   ): Promise<MastraStreamResponse> {
-    const response = (await this.request(
-      `/agents/${encodeURIComponent(agentId)}/${route}`,
-      {
-        method: "POST",
-        body: params,
-        stream: true,
+    const url = `${this.basePath}/agents/${encodeURIComponent(agentId)}/${route}`;
+    const init: RequestInit = {
+      method: "POST",
+      credentials: "include",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.#routingHeaders({ threadId: params.threadId }),
       },
-    )) as Response;
-    if (!response.body) throw new Error("No response body");
-    return asMastraStreamResponse(
-      new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: response.headers,
-      }),
-    );
+      body: JSON.stringify({ runId: params.runId, toolCallId: params.toolCallId }),
+    };
+    if (params.signal) init.signal = params.signal;
+    const response = await fetch(url, init);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return asMastraStreamResponse(response);
   }
 
   /**
@@ -209,11 +219,14 @@ export class MastraPluginClient extends MastraClient {
   /**
    * Fetch one page of thread history from `GET ${basePath}/history`.
    * Messages come back oldest -> newest so the caller can prepend them
-   * to a live transcript.
+   * to a live transcript. `threadId` targets a specific conversation
+   * (sent as the `?threadId=` query so it doesn't depend on shared client
+   * state); omit it to read the per-session cookie thread.
    */
   async history(
     options: {
       agentId?: string;
+      threadId?: string;
       page?: number;
       perPage?: number;
       signal?: AbortSignal;
@@ -222,6 +235,7 @@ export class MastraPluginClient extends MastraClient {
     const params = new URLSearchParams();
     if (options.page !== undefined) params.set("page", String(options.page));
     if (options.perPage !== undefined) params.set("perPage", String(options.perPage));
+    if (options.threadId) params.set(thread.THREAD_ID_QUERY, options.threadId);
     const qs = params.toString();
     const base = this.#agentScoped(routes.MASTRA_ROUTES.history, options.agentId);
     return this.#getJson(
@@ -232,19 +246,26 @@ export class MastraPluginClient extends MastraClient {
   }
 
   /**
-   * Wipe the caller's thread history (`DELETE ${basePath}/history`).
-   * The session cookie that anchors the thread id is preserved - only
-   * the messages go away. Idempotent: a fresh thread reports
+   * Wipe a thread's history (`DELETE ${basePath}/history`). `threadId`
+   * targets a specific conversation via the thread-selection header (so it
+   * doesn't depend on shared client state); omit it to clear the per-session
+   * cookie thread. The session cookie that anchors the thread id is
+   * preserved - only the messages go away. Idempotent: a fresh thread reports
    * `cleared: 0` without erroring.
    */
   async clearHistory(
-    options: { agentId?: string; signal?: AbortSignal } = {},
+    options: { agentId?: string; threadId?: string; signal?: AbortSignal } = {},
   ): Promise<MastraClearHistoryResponse> {
     return this.#mutateJson(
       this.#agentScoped(routes.MASTRA_ROUTES.history, options.agentId),
       "DELETE",
       wire.MastraClearHistoryResponseSchema,
-      options.signal ? { signal: options.signal } : {},
+      {
+        ...(options.threadId
+          ? { headers: { [thread.THREAD_ID_HEADER]: options.threadId } }
+          : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+      },
     );
   }
 
@@ -282,9 +303,8 @@ export class MastraPluginClient extends MastraClient {
    * clashing with the inherited `MastraClient.deleteThread`, which hits
    * Mastra's stock thread route rather than our OBO-scoped, custom
    * mount). The id is sent as the thread-selection header for this one
-   * call (without disturbing the client's currently-selected thread,
-   * set via {@link setThreadId}), so the sidebar can remove any thread
-   * while the user stays on another. Idempotent: deleting an unknown /
+   * call, so the sidebar can remove any thread while the user stays on
+   * another (routing is per call, never shared). Idempotent: deleting an unknown /
    * already-removed thread reports `deleted: false` without erroring.
    */
   async removeThread(
@@ -306,9 +326,8 @@ export class MastraPluginClient extends MastraClient {
    * Rename a single conversation thread via the plugin's own
    * `PATCH ${basePath}/threads` route. The id travels as the
    * thread-selection header for this one call (mirroring
-   * {@link removeThread}, so the sidebar can rename any thread without
-   * disturbing the client's currently-selected thread) and the new
-   * `title` rides in the JSON body. The server enforces ownership and
+   * {@link removeThread}, so the sidebar can rename any thread; routing is
+   * per call, never shared) and the new `title` rides in the JSON body. The server enforces ownership and
    * echoes back the updated thread, so the caller can reflect the new
    * title immediately. Throws on an unknown / unowned thread (HTTP 404).
    */
@@ -384,13 +403,13 @@ export class MastraPluginClient extends MastraClient {
   }
 
   /**
-   * Snapshot of the client's per-request override headers (model +
-   * thread selection) for the custom-route fetches that don't go
-   * through `@mastra/client-js`'s own request pipeline. Returns a fresh
-   * object each call so a caller can safely add one-off headers without
-   * mutating the shared `options.headers`. The thread-selection header
-   * here is what routes `history()` / `clearHistory()` / `threads()` to
-   * the currently-selected thread (see {@link setThreadId}).
+   * Snapshot of the client's base headers for the custom-route fetches
+   * that don't go through `@mastra/client-js`'s own request pipeline.
+   * Returns a fresh object each call so a caller can safely add one-off
+   * headers without mutating the shared `options.headers`. Routing
+   * (thread selection, model override) is passed per call - via a
+   * `?threadId=` query or the thread-selection header on the individual
+   * request - not stored here, so concurrent calls never share routing.
    */
   #defaultHeaders(): Record<string, string> {
     return { ...((this.options.headers as Record<string, string>) ?? {}) };
@@ -416,9 +435,8 @@ export class MastraPluginClient extends MastraClient {
    * `POST` / `DELETE` / `PATCH` + JSON-parse + schema-validate for the
    * mutating routes (`clearHistory` / `removeThread` / `renameThread` /
    * `feedback`). A JSON body, when present, sets `Content-Type`;
-   * `options.headers` add one-off headers (e.g. the thread-selection
-   * header for a targeted delete / rename) over the client's default
-   * override headers.
+   * `options.headers` add per-call headers (e.g. the thread-selection
+   * header for a targeted delete / rename) over the client's base headers.
    */
   async #mutateJson<T>(
     url: string,
@@ -477,12 +495,12 @@ export const useMastraConfig = (): MastraClientConfig =>
 /**
  * The single {@link MastraPluginClient} for the plugin, built once from
  * the published `basePath`. Use it for everything: stream a turn with
- * `client.getAgent(agentId).stream(...)`, page history with
- * `client.history()`, resolve embeds with `client.chart(id)`, etc.
- * Rebuilt only when `basePath` / `defaultAgent` change (e.g. a custom
- * mount), so it's safe as a `useMemo` / `useCallback` / `useEffect`
- * dependency; the per-request model override is applied in place via
- * {@link MastraPluginClient.setModelOverride} without changing identity.
+ * `client.streamAgent({ agentId, messages, runId, threadId, model, signal })`,
+ * page history with `client.history()`, resolve embeds with
+ * `client.chart(id)`, etc. Rebuilt only when `basePath` / `defaultAgent`
+ * change (e.g. a custom mount), so it's safe as a `useMemo` / `useCallback`
+ * / `useEffect` dependency; per-turn thread + model routing is passed per
+ * call rather than stored on the client, so concurrent runs stay isolated.
  */
 export const useMastraClient = (): MastraPluginClient => {
   const config = useMastraConfig();