@dbx-tools/ui-mastra 0.9.118 → 0.9.120

package/src/react/feedback-controls.tsx

@@ -23,6 +23,7 @@ import type { FeedbackSubmission, FeedbackValue } from "./types.ts";
 // wires feedback (which only happens when MLflow logging is enabled and
 // the turn has a captured trace id).
 
+/** Render per-message rating and comment controls for an MLflow-backed trace. */
 export const FeedbackControls = ({
   value,
   onSubmit,

package/src/react/markdown.tsx

@@ -18,6 +18,7 @@ import {
 import { CheckIcon, CopyIcon } from "lucide-react";
 import React, { useEffect, useRef, useState } from "react";
 import { Streamdown } from "streamdown";
+import { ExternalLinkDialog } from "./_external-link-dialog.tsx";
 import { DataGrid, TABLE_WRAPPER_CLASSES, colorizeDelta, type DataRow } from "./data-grid.tsx";
 import { copyText } from "../support/clipboard.ts";
 
@@ -183,6 +184,14 @@ const TOOL_MARKDOWN_COMPONENTS = {
  */
 const SHIKI_PLUGIN = { code: createShikiPlugin() };
 
+/** Keep Streamdown's link confirmation while matching the chat's AppKit UI. */
+const LINK_SAFETY = {
+  enabled: true,
+  renderModal: (props: React.ComponentProps<typeof ExternalLinkDialog>) => (
+    <ExternalLinkDialog {...props} />
+  ),
+};
+
 /**
  * Per-word fade-in applied while a reply is still streaming. Streamdown
  * wraps each newly arrived token in a `[data-sd-animate]` span and only
@@ -235,6 +244,7 @@ export const AssistantMarkdown = ({
     components={MARKDOWN_COMPONENTS}
     plugins={SHIKI_PLUGIN}
     controls={false}
+    linkSafety={LINK_SAFETY}
     animated={animate ? ANIMATE_OPTIONS : false}
     isAnimating={animate}
     className={cn(
@@ -269,6 +279,7 @@ export const ToolMarkdown = ({ children, className }: { children: string; classN
     components={TOOL_MARKDOWN_COMPONENTS}
     plugins={SHIKI_PLUGIN}
     controls={false}
+    linkSafety={LINK_SAFETY}
     className={cn(
       "prose prose-sm dark:prose-invert max-w-none break-words",
       "text-xs leading-snug text-muted-foreground",

package/src/react/mastra-assistant.tsx

@@ -84,6 +84,8 @@ export interface MastraAssistantProps<TValues extends Record<string, unknown>> e
   closeIcon?: ReactNode;
   newConversationIcon?: ReactNode;
   historyIcon?: ReactNode;
+  /** Host controls rendered immediately before the History action and in the sidebar header. */
+  historyLeadingActions?: ReactNode;
   contentClassName?: string;
   panelClassName?: string;
   headerClassName?: string;
@@ -205,6 +207,7 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
   closeIcon,
   newConversationIcon,
   historyIcon,
+  historyLeadingActions,
   className,
   contentClassName,
   panelClassName,
@@ -493,6 +496,7 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
         onCancel={chatView.onCancelThread}
         newIcon={newConversationIcon}
         historyIcon={historyIcon}
+        historyLeadingActions={historyLeadingActions}
         actions={closeAction}
       />
     ) : (
@@ -550,6 +554,8 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
           threadBarActions={!header ? closeAction : undefined}
           threadNewIcon={newConversationIcon}
           threadHistoryIcon={historyIcon}
+          threadHistoryLeadingActions={historyLeadingActions}
+          threadSidebarHeaderActions={historyLeadingActions}
           className={cn("min-h-0 flex-1", chatClassName)}
         />
         {!header && chatView.threadPlacement !== "top" ? (

package/src/react/mastra-chat.tsx

@@ -4,6 +4,7 @@ import type { ReasoningEffort } from "@dbx-tools/shared-model";
 import { useBrand } from "@dbx-tools/ui/branding/react";
 import type { FileUIPart, UIMessage } from "ai";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { toChronologicalUiMessages } from "./_history-messages.ts";
 import { useChatApprovals } from "./chat-approvals.ts";
 import { useChatFeedback } from "./chat-feedback.ts";
 import { useChatHistory } from "./chat-history.ts";
@@ -12,6 +13,12 @@ import { useChatStream } from "./chat-stream.ts";
 import { ChatView } from "./chat-view.tsx";
 import { dedupeSuggestions } from "./suggestions.ts";
 import type { ChatViewProps, ThreadPlacement, ThreadSummary } from "./types.ts";
+import {
+  activeRunStorageKey,
+  readStoredActiveRuns,
+  removeStoredActiveRun,
+  storeActiveRun,
+} from "../support/active-runs.ts";
 import type { EmbedResolver, ExportFormat } from "../support/export.ts";
 import {
   useMastraClient,
@@ -20,6 +27,7 @@ import {
   useMastraModels,
   useMastraSuggestions,
   useMastraThreads,
+  MastraChatRequestError,
   type MastraMemoryThread,
   type MastraStreamResponse,
 } from "../support/mastra-client.ts";
@@ -189,7 +197,7 @@ export interface UseMastraChatOptions<
    * Where conversation management renders: `"left"` / `"right"` dock the list
    * to that edge, `"top"` shows the open conversations as an editor-style tab
    * strip with a history menu, `"disabled"` turns thread management off, and
-   * the default `"auto"` picks `"left"` while the chat is wide enough for a
+   * the default `"auto"` picks `"right"` while the chat is wide enough for a
    * side panel and `"top"` once it gets too narrow for one (measured on the
    * chat's own width, so an embedded panel decides on its own space).
    */
@@ -292,6 +300,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
   const feedbackAvailable = enableFeedback && mastraClient.feedbackEnabled;
   const { url: mlflowExperimentUrl } = useMastraMlflowExperiment(feedbackAvailable);
   const threadKey = threadStorageKey(mastraClient.basePath, agentId);
+  const activeRunsKey = activeRunStorageKey(mastraClient.basePath, agentId);
   const [activeThreadId, setActiveThreadId] = useState<string>(() =>
     enableThreads ? (readStoredThreadId(threadKey) ?? hash.id()) : hash.id(),
   );
@@ -471,6 +480,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
           if (
             controller.signal.aborted ||
             getSession(threadId).runToken !== token ||
+            initialError instanceof MastraChatRequestError ||
             !mastraClient.backgroundTurns ||
             !runId
           ) {
@@ -478,7 +488,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
           }
           logger.warn("chat stream disconnected; reconnecting to background run", {
             runId,
-            error: errorUtils.errorMessage(initialError),
+            error: errorUtils.toError(initialError),
           });
           const messagesBeforeReplay = getSession(threadId).messages;
           writeMessages(
@@ -510,6 +520,8 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
           };
         });
         if (getSession(threadId).runToken === token) {
+          const completedRunId = runIdRef.current;
+          if (completedRunId) removeStoredActiveRun(activeRunsKey, completedRunId);
           refreshThreadsSoon();
           // Turn finished on its own: start the oldest queued steer, if any.
           drainQueueRef.current(threadId);
@@ -518,7 +530,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
         if (getSession(threadId).runToken !== token) return;
         if (isStaleMastraResumeError(caught)) {
           logger.warn("ignored stale mastra resume", {
-            error: errorUtils.errorMessage(caught),
+            error: errorUtils.toError(caught),
           });
           updateSession(threadId, (session) => {
             if (session.runToken !== token) return session;
@@ -531,12 +543,14 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
               runId: runIdRef.current,
             };
           });
+          const staleRunId = runIdRef.current;
+          if (staleRunId) removeStoredActiveRun(activeRunsKey, staleRunId);
           refreshThreadsSoon();
           drainQueueRef.current(threadId);
           return;
         }
         logger.error("stream error", {
-          error: errorUtils.errorMessage(caught),
+          error: errorUtils.toError(caught),
         });
         updateSession(threadId, (session) => ({
           ...session,
@@ -545,10 +559,13 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
           abortController: session.abortController === controller ? null : session.abortController,
           runId: runIdRef.current,
         }));
+        const failedRunId = runIdRef.current;
+        if (failedRunId) removeStoredActiveRun(activeRunsKey, failedRunId);
       }
     },
     [
       agentId,
+      activeRunsKey,
       getSession,
       mastraClient,
       processStream,
@@ -562,6 +579,13 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
     (threadId: string, message: UIMessage, requestContext?: MastraRequestContextSnapshot) => {
       const assistantId = hash.id();
       const runId = hash.id();
+      storeActiveRun(activeRunsKey, {
+        threadId,
+        runId,
+        assistantId,
+        userMessage: message,
+        startedAt: Date.now(),
+      });
       updateSession(threadId, (session) => ({
         ...session,
         assistantId,
@@ -595,9 +619,50 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
         });
       });
     },
-    [driveStream, mastraClient, agentId, updateSession],
+    [activeRunsKey, driveStream, mastraClient, agentId, updateSession],
   );
 
+  const recoveredRunsKeyRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (!mastraClient.backgroundTurns || recoveredRunsKeyRef.current === activeRunsKey) return;
+    recoveredRunsKeyRef.current = activeRunsKey;
+    for (const run of readStoredActiveRuns(activeRunsKey)) {
+      const session = getSession(run.threadId);
+      if (isSessionRunning(session) || session.runId === run.runId) continue;
+      updateSession(run.threadId, (current) => ({
+        ...current,
+        messages: current.messages.some((message) => message.id === run.userMessage.id)
+          ? current.messages
+          : [...current.messages, run.userMessage],
+        assistantId: run.assistantId,
+        runId: run.runId,
+        runs: {
+          ...current.runs,
+          [run.runId]: { assistantId: run.assistantId },
+        },
+      }));
+      void driveStream(run.threadId, run.assistantId, (signal) =>
+        mastraClient.observeAgentStream({
+          agentId,
+          runId: run.runId,
+          threadId: run.threadId === DEFAULT_THREAD_SESSION_KEY ? undefined : run.threadId,
+          signal,
+        }),
+      ).then(async () => {
+        if (run.threadId === DEFAULT_THREAD_SESSION_KEY) return;
+        const history = await mastraClient
+          .history({
+            agentId,
+            threadId: run.threadId,
+            page: 0,
+            perPage: 20,
+          })
+          .catch(() => undefined);
+        if (history) writeMessages(run.threadId, toChronologicalUiMessages(history));
+      });
+    }
+  }, [activeRunsKey, agentId, driveStream, getSession, mastraClient, updateSession, writeMessages]);
+
   // Start the oldest queued steer as the next turn (FIFO drain). Called from
   // `driveStream` when a turn ends normally; a no-op when the queue is empty.
   // Kept behind `drainQueueRef` so `driveStream` can reach it without a
@@ -632,10 +697,13 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
             runId: current.runId,
             threadId: streamThreadId,
           })
+          .then((aborted) => {
+            if (aborted && current.runId) removeStoredActiveRun(activeRunsKey, current.runId);
+          })
           .catch((error: unknown) => {
             logger.warn("failed to abort background run", {
               runId: current.runId,
-              error: errorUtils.errorMessage(error),
+              error: errorUtils.toError(error),
             });
           });
       }
@@ -651,7 +719,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
         };
       });
     },
-    [activeKey, agentId, getSession, mastraClient, updateSession],
+    [activeKey, activeRunsKey, agentId, getSession, mastraClient, updateSession],
   );
 
   const handleApproval = useChatApprovals({
@@ -777,7 +845,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
       logger.info("history cleared", { threadId });
     } catch (error) {
       logger.error("history clear error", {
-        error: errorUtils.errorMessage(error),
+        error: errorUtils.toError(error),
       });
     }
     resetSession(threadId, true);
@@ -818,7 +886,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
       } catch (error) {
         logger.error("thread delete error", {
           threadId,
-          error: errorUtils.errorMessage(error),
+          error: errorUtils.toError(error),
         });
       }
       removeSession(threadId);
@@ -863,7 +931,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
       } catch (error) {
         logger.error("thread rename error", {
           threadId,
-          error: errorUtils.errorMessage(error),
+          error: errorUtils.toError(error),
         });
         setRenamedThreads((prev) => {
           if (!(threadId in prev)) return prev;
@@ -906,7 +974,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
       .catch((error: unknown) => {
         logger.error("regenerate cleanup error", {
           threadId,
-          error: errorUtils.errorMessage(error),
+          error: errorUtils.toError(error),
         });
         updateSession(threadId, (session) => ({
           ...session,
@@ -976,7 +1044,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
       } catch (error) {
         logger.error("conversation export error", {
           format,
-          error: errorUtils.errorMessage(error),
+          error: errorUtils.toError(error),
         });
       }
     },
@@ -998,7 +1066,7 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
       } catch (error) {
         logger.error("message export error", {
           format,
-          error: errorUtils.errorMessage(error),
+          error: errorUtils.toError(error),
         });
       }
     },
@@ -1155,6 +1223,10 @@ export interface MastraChatProps<
   modelSelectorActions?: ReactNode;
   /** Host controls placed on the left side of the composer footer. */
   composerLeadingActions?: ReactNode;
+  /** Host controls rendered immediately before the responsive History action. */
+  threadHistoryLeadingActions?: ReactNode;
+  /** Host controls rendered in the full conversation-list header. */
+  threadSidebarHeaderActions?: ReactNode;
 }
 
 /**
@@ -1167,7 +1239,7 @@ export interface MastraChatProps<
  * of the resource's threads with select / new / delete, persisted
  * across reloads) - all with no host wiring. The model picker is opt-in
  * via `showModelPicker`; thread management is on by default, laid out per
- * `threadPlacement` (`auto` docks it left and falls back to a tab strip on a
+ * `threadPlacement` (`auto` docks it right and falls back to a tab strip on a
  * narrow chat) and turned off with `threadPlacement: "disabled"`.
  */
 export const MastraChat = <TValues extends Record<string, unknown> = Record<string, unknown>>({
@@ -1175,6 +1247,8 @@ export const MastraChat = <TValues extends Record<string, unknown> = Record<stri
   composerActions,
   modelSelectorActions,
   composerLeadingActions,
+  threadHistoryLeadingActions,
+  threadSidebarHeaderActions,
   ...options
 }: MastraChatProps<TValues>) => {
   const chat = useMastraChat(options);
@@ -1185,6 +1259,8 @@ export const MastraChat = <TValues extends Record<string, unknown> = Record<stri
       composerActions={composerActions}
       modelSelectorActions={modelSelectorActions}
       composerLeadingActions={composerLeadingActions}
+      threadHistoryLeadingActions={threadHistoryLeadingActions}
+      threadSidebarHeaderActions={threadSidebarHeaderActions}
     />
   );
 };

package/src/react/suggestion-pills.tsx

@@ -5,6 +5,7 @@ import { Button, cn } from "@dbx-tools/ui/react";
 // the per-message follow-up suggestions use this so the two look and
 // behave identically.
 
+/** Props for the shared starter and follow-up question pill row. */
 export interface SuggestionPillsProps {
   /** Questions to render as clickable pills. Empty renders nothing. */
   questions: string[];

package/src/react/thread-sidebar.tsx

@@ -16,7 +16,7 @@ import {
   SquareIcon,
   Trash2Icon,
 } from "lucide-react";
-import { useState } from "react";
+import { type ReactNode, useState } from "react";
 import type { ThreadSummary } from "./types.ts";
 import { relativeTime, threadTitle } from "../support/thread-labels.ts";
 
@@ -52,6 +52,8 @@ export interface ThreadSidebarProps {
   onCancel?: (threadId: string) => void;
   /** Collapse the sidebar. Renders the hide button in the header when provided. */
   onHide?: () => void;
+  /** Host controls rendered in the conversation-list header. */
+  headerActions?: ReactNode;
   /**
    * Edge the sidebar is docked to. Only affects framing - which side carries
    * the divider, and which way the collapse icon points. Defaults to `left`.
@@ -82,6 +84,7 @@ export const ThreadSidebar = ({
   onRename,
   onCancel,
   onHide,
+  headerActions,
   side = "left",
   className,
 }: ThreadSidebarProps) => {
@@ -134,7 +137,7 @@ export const ThreadSidebar = ({
         className,
       )}
     >
-      {(onNew || onHide) && (
+      {(onNew || headerActions || onHide) && (
         <div className="flex items-center gap-2 p-2">
           {onNew && (
             <Button
@@ -148,6 +151,7 @@ export const ThreadSidebar = ({
               New chat
             </Button>
           )}
+          {headerActions}
           {onHide && (
             <Tooltip>
               <TooltipTrigger asChild>

package/src/react/thread-tabs.tsx

@@ -44,6 +44,8 @@ export interface ThreadTabsProps extends Omit<ThreadSidebarProps, "onHide" | "si
   newIcon?: ReactNode;
   /** Replacement for the default history icon. */
   historyIcon?: ReactNode;
+  /** Host controls rendered immediately before History. */
+  historyLeadingActions?: ReactNode;
 }
 
 /** New/history controls reused by the tab strip and persistent assistant header. */
@@ -54,10 +56,17 @@ export interface ThreadActionsProps extends Omit<
   actions?: ReactNode;
   newIcon?: ReactNode;
   historyIcon?: ReactNode;
+  historyLeadingActions?: ReactNode;
 }
 
 /** Render New and History controls, plus optional host actions, as one group. */
-export const ThreadActions = ({ actions, newIcon, historyIcon, ...list }: ThreadActionsProps) => {
+export const ThreadActions = ({
+  actions,
+  newIcon,
+  historyIcon,
+  historyLeadingActions,
+  ...list
+}: ThreadActionsProps) => {
   const { onSelect, onNew } = list;
   const [historyOpen, setHistoryOpen] = useState(false);
   return (
@@ -79,6 +88,7 @@ export const ThreadActions = ({ actions, newIcon, historyIcon, ...list }: Thread
           <TooltipContent>New chat</TooltipContent>
         </Tooltip>
       )}
+      {historyLeadingActions}
       <Popover open={historyOpen} onOpenChange={setHistoryOpen}>
         <Tooltip>
           <TooltipTrigger asChild>
@@ -136,6 +146,7 @@ export const ThreadTabs = ({
   showActions = true,
   newIcon,
   historyIcon,
+  historyLeadingActions,
   className,
   ...list
 }: ThreadTabsProps) => {
@@ -207,7 +218,13 @@ export const ThreadTabs = ({
           })}
         </div>
         {showActions ? (
-          <ThreadActions {...list} actions={actions} newIcon={newIcon} historyIcon={historyIcon} />
+          <ThreadActions
+            {...list}
+            actions={actions}
+            newIcon={newIcon}
+            historyIcon={historyIcon}
+            historyLeadingActions={historyLeadingActions}
+          />
         ) : null}
       </div>
     </div>

package/src/react/tool-pill.tsx

@@ -124,8 +124,8 @@ type MessageGroup = {
  * are resolved out-of-band via the chart cache; suggestions live at
  * message scope.
  *
- * Genie `thinking` and `text` entries render in the assistant bubble's
- * consolidated Thoughts panel and are intentionally omitted here.
+ * Genie `thinking` entries render as interleaved Thoughts disclosures in the
+ * assistant activity timeline and are intentionally omitted here.
  *
  * `groups` preserves first-seen order so the rendered detail view
  * walks Genie sub-calls in the order the LLM dispatched them.
@@ -190,7 +190,7 @@ const summarizeProgress = (progress: ToolProgress[]): ToolDetailSummary => {
         break;
       }
       case "thinking": {
-        // Reasoning is rendered once in the assistant bubble's Thoughts panel.
+        // Reasoning is rendered once in the assistant activity timeline.
         break;
       }
       case "query": {
@@ -424,6 +424,7 @@ const RawToolPayload = ({
   );
 };
 
+/** Compact source-code preview extracted from a tool request payload. */
 export type ToolInputPresentation = {
   label: "Code" | "Command" | "Output";
   language: "typescript" | "javascript" | "python" | "sql" | "json" | "bash" | "text";
@@ -511,6 +512,7 @@ const ToolInputSource = ({ presentation }: { presentation: ToolInputPresentation
 
 type ToolStatusProgress = Extract<ToolProgress, { type: "tool_status" }>;
 
+/** One native web-search request and the result progress events associated with it. */
 export type WebSearchProgressGroup = {
   key: string;
   search?: ToolStatusProgress;

package/src/react/types.ts

@@ -265,7 +265,7 @@ export type ChatViewProps = {
   /**
    * Where the conversation list renders (or `"disabled"` to hide it even when
    * {@link threads} and {@link onSelectThread} are wired). Defaults to
-   * `"auto"`: a left side panel while the chat is wide, a tab strip once it
+   * `"auto"`: a right side panel while the chat is wide, a tab strip once it
    * is too narrow for one. See {@link ThreadPlacement}.
    */
   threadPlacement?: ThreadPlacement;
@@ -274,6 +274,10 @@ export type ChatViewProps = {
    * actions. The persistent assistant uses this for its panel Close button.
    */
   threadBarActions?: ReactNode;
+  /** Host controls rendered immediately before the top-row History action. */
+  threadHistoryLeadingActions?: ReactNode;
+  /** Host controls rendered in the docked or drawer conversation-list header. */
+  threadSidebarHeaderActions?: ReactNode;
   /** Whether the top tab row renders its built-in New/History controls. */
   showThreadBarActions?: boolean;
   /** Replacement icon for the top tab row's New action. */

package/src/support/active-runs.ts

@@ -0,0 +1,111 @@
+import type { UIMessage } from "ai";
+import { z } from "zod";
+
+const ACTIVE_RUN_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+
+export const StoredActiveRunSchema = z
+  .object({
+    threadId: z.string().min(1).describe("Mastra thread receiving the background turn."),
+    runId: z.string().min(1).describe("Mastra background run identifier."),
+    assistantId: z.string().min(1).describe("Client assistant message identifier."),
+    userMessage: z
+      .object({
+        id: z.string().min(1),
+        role: z.literal("user"),
+        parts: z.array(z.unknown()),
+      })
+      .passthrough()
+      .describe("Submitted user message restored before stream replay."),
+    startedAt: z.number().int().nonnegative().describe("Client epoch time when the run started."),
+  })
+  .strict()
+  .describe("Reload-recoverable Mastra background run metadata.");
+
+/** Reload-recoverable metadata for one active Mastra background run. */
+export type StoredActiveRun = Omit<z.infer<typeof StoredActiveRunSchema>, "userMessage"> & {
+  userMessage: UIMessage;
+};
+
+const StoredActiveRunFileSchema = z
+  .object({
+    version: z.literal(1).describe("Active run storage format version."),
+    runs: z.array(StoredActiveRunSchema).describe("Background runs awaiting terminal completion."),
+  })
+  .strict()
+  .describe("Browser-persisted Mastra background run registry.");
+
+type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+
+/** Build the browser storage key for one Mastra agent's active runs. */
+export const activeRunStorageKey = (basePath: string, agentId: string): string =>
+  `dbx-mastra-active-runs:${basePath}:${agentId}`;
+
+function browserStorage(): StorageLike | undefined {
+  try {
+    return typeof window === "undefined" ? undefined : window.localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read current non-stale background runs, deleting malformed storage. */
+export function readStoredActiveRuns(
+  key: string,
+  storage: StorageLike | undefined = browserStorage(),
+  now = Date.now(),
+): StoredActiveRun[] {
+  if (!storage) return [];
+  try {
+    const serialized = storage.getItem(key);
+    if (!serialized) return [];
+    const parsed = StoredActiveRunFileSchema.parse(JSON.parse(serialized));
+    const parsedRuns: StoredActiveRun[] = parsed.runs.map((run) => ({
+      ...run,
+      userMessage: run.userMessage as UIMessage,
+    }));
+    const runs = parsedRuns.filter((run) => now - run.startedAt <= ACTIVE_RUN_MAX_AGE_MS);
+    if (runs.length !== parsed.runs.length) writeStoredActiveRuns(key, runs, storage);
+    return runs as StoredActiveRun[];
+  } catch {
+    try {
+      storage.removeItem(key);
+    } catch {}
+    return [];
+  }
+}
+
+/** Add or replace one reload-recoverable background run. */
+export function storeActiveRun(
+  key: string,
+  run: StoredActiveRun,
+  storage: StorageLike | undefined = browserStorage(),
+): void {
+  if (!storage) return;
+  const runs = readStoredActiveRuns(key, storage).filter(
+    (candidate) => candidate.runId !== run.runId,
+  );
+  writeStoredActiveRuns(key, [...runs, run], storage);
+}
+
+/** Remove one terminal or explicitly aborted background run. */
+export function removeStoredActiveRun(
+  key: string,
+  runId: string,
+  storage: StorageLike | undefined = browserStorage(),
+): void {
+  if (!storage) return;
+  const runs = readStoredActiveRuns(key, storage).filter((run) => run.runId !== runId);
+  writeStoredActiveRuns(key, runs, storage);
+}
+
+function writeStoredActiveRuns(key: string, runs: StoredActiveRun[], storage: StorageLike): void {
+  try {
+    if (runs.length === 0) {
+      storage.removeItem(key);
+      return;
+    }
+    storage.setItem(key, JSON.stringify({ version: 1, runs }));
+  } catch {
+    // Browser persistence is best-effort; the live in-memory run remains valid.
+  }
+}

package/src/support/index.ts

@@ -2,6 +2,7 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 
+export * as activeRuns from "./active-runs.ts";
 export * as chartOption from "./chart-option.ts";
 export * as chartTheme from "./chart-theme.ts";
 export * as clipboard from "./clipboard.ts";
@@ -14,10 +15,12 @@ export * as threadLabels from "./thread-labels.ts";
 export * as threadSessions from "./thread-sessions.ts";
 export * as threadTabs from "./thread-tabs.ts";
 export * as toolEvents from "./tool-events.ts";
+export { StoredActiveRunSchema, activeRunStorageKey } from "./active-runs.ts";
+export type { StoredActiveRun } from "./active-runs.ts";
 export { LIGHT_CHART_CHROME } from "./chart-theme.ts";
 export type { ChartChrome } from "./chart-theme.ts";
 export type { ExportFormat, ExportBrand, EmbedResolver, ExportChatOptions } from "./export.ts";
-export { MastraPluginClient, useMastraConfig, useMastraClient, useMastraMlflowExperiment, useMastraModels, useMastraDefaultModel, useMastraSuggestions, useMastraThreads, useChartFetch, useStatementFetch } from "./mastra-client.ts";
+export { MastraChatRequestError, MastraPluginClient, useMastraConfig, useMastraClient, useMastraMlflowExperiment, useMastraModels, useMastraDefaultModel, useMastraSuggestions, useMastraThreads, useChartFetch, useStatementFetch } from "./mastra-client.ts";
 export type { MastraStreamResponse, MastraMemoryThread, ByIdFetchState } from "./mastra-client.ts";
 export { defaultReasoningEffort, modelStorageKey, readStoredModel, storeSelectedModel } from "./model-selection.ts";
 export type { MastraRequestContextInput, MastraRequestContextSource, MastraRequestContextSnapshot } from "./request-context.ts";