@dbx-tools/ui-mastra 0.3.11 → 0.3.13

package/README.md

@@ -28,8 +28,9 @@ Key features:
 - Concurrent threads: run several conversations at once, switch between them
   while each keeps streaming, and cancel any one independently (per-thread abort
   + routing, no shared client state).
-- Mid-turn steering: submit a message while a turn streams to fold it into the
-  live run (Mastra queue-message), with an immediate interrupt-and-resend option.
+- Mid-turn steering queue: messages submitted while a turn streams stack up as
+  pending steers (they drain oldest-first when the turn ends); each queued item
+  can be sent now (interrupting the current turn) or removed.
 - Export menu for PDF and Markdown, resolving charts and tables so
   exported conversations remain useful offline.
 
@@ -49,9 +50,10 @@ understand Mastra-specific behavior:
   answer.
 - `[chart:<id>]` and `[data:<id>]` assistant markers rendered as ECharts charts
   and sortable tables.
-- Concurrent multi-thread streaming, per-thread cancel, and mid-turn steering
-  (queue-message with interrupt fallback) - the native AppKit chat surface runs
-  one turn at a time and has no steering.
+- Concurrent multi-thread streaming, per-thread cancel, and a mid-turn steering
+  queue (submit while running to enqueue; drain oldest-first, or send any item
+  now to interrupt) - the native AppKit chat surface runs one turn at a time and
+  has no steering.
 - Conversation export that resolves those embeds into Markdown or PDF.
 
 ## Add The Styles

package/index.ts

@@ -25,7 +25,7 @@ export type { DataRow } from "./src/react/data-grid";
 export type { UseMastraChatOptions, MastraChatProps } from "./src/react/mastra-chat";
 export type { SuggestionPillsProps } from "./src/react/suggestion-pills";
 export type { ThreadSidebarProps } from "./src/react/thread-sidebar";
-export type { ChatStatus, ToolEvent, ToolProgress, ChatModelOption, FeedbackValue, FeedbackSubmission, MessageFeedback, ThreadSummary, ChatViewProps, ApprovalDecision, PendingApproval } from "./src/react/types";
+export type { ChatStatus, ToolEvent, ToolProgress, ChatModelOption, QueuedSteer, FeedbackValue, FeedbackSubmission, MessageFeedback, ThreadSummary, ChatViewProps, ApprovalDecision, PendingApproval } from "./src/react/types";
 export type { ExportFormat, ExportBrand, EmbedResolver, ExportChatOptions } from "./src/support/export";
 export type { ByIdFetchState } from "./src/support/mastra-client";
 export type { MastraStreamChunk, MastraStreamResponse } from "./src/support/mastra-stream";

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.11",
-    "@dbx-tools/shared-genie": "0.3.11",
-    "@dbx-tools/shared-mastra": "0.3.11",
-    "@dbx-tools/shared-model": "0.3.11",
-    "@dbx-tools/ui-appkit": "0.3.11",
-    "@dbx-tools/ui-branding": "0.3.11"
+    "@dbx-tools/shared-core": "0.3.13",
+    "@dbx-tools/shared-mastra": "0.3.13",
+    "@dbx-tools/shared-model": "0.3.13",
+    "@dbx-tools/shared-genie": "0.3.13",
+    "@dbx-tools/ui-appkit": "0.3.13",
+    "@dbx-tools/ui-branding": "0.3.13"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.11",
+  "version": "0.3.13",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/react/chat-view.tsx

@@ -35,14 +35,15 @@ import {
 import { error as errorUtil } from "@dbx-tools/shared-core";
 import {
   ArrowDownIcon,
-  FastForwardIcon,
   MessageSquareIcon,
   PanelLeftIcon,
   RefreshCwIcon,
+  SendHorizontalIcon,
   SendIcon,
   SquareIcon,
   Trash2Icon,
   TriangleAlertIcon,
+  XIcon,
 } from "lucide-react";
 import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { AssistantBubble, UserBubble } from "./bubbles";
@@ -101,7 +102,9 @@ export const ChatView = ({
   status,
   error,
   sendMessage,
-  onInterrupt,
+  queuedSteers = [],
+  onSendSteerNow,
+  onRemoveSteer,
   regenerate,
   onStop,
   className,
@@ -278,16 +281,6 @@ export const ChatView = ({
     });
   };
 
-  // Interrupt-submit: force an immediate course-correction (abort the current
-  // run, resend with this text) rather than queuing to the live turn.
-  const handleInterrupt = () => {
-    const text = input.trim();
-    if (!text || !onInterrupt) return;
-    onInterrupt({ text });
-    setInput("");
-    setIsAtBottom(true);
-    pinToBottom();
-  };
 
   const lastMessage = messages.at(-1);
   const lastEvents = lastMessage ? toolEventsByMessage[lastMessage.id] : undefined;
@@ -635,6 +628,56 @@ export const ChatView = ({
             onSubmit={handleSubmit}
             className="mx-auto w-full max-w-4xl px-3 pt-2 pb-[max(1rem,env(safe-area-inset-bottom))] md:px-6"
           >
+            {queuedSteers.length > 0 && (
+              // Steers submitted while the turn is running, waiting to send.
+              // They drain oldest-first when the turn ends; each can be fired
+              // now (interrupts) or removed.
+              <div className="mb-2 flex flex-col gap-1">
+                {queuedSteers.map((steer) => (
+                  <div
+                    key={steer.id}
+                    className="flex items-center gap-1.5 rounded-lg border border-border/70 bg-muted/40 px-2 py-1 text-xs"
+                  >
+                    <span className="text-muted-foreground">Queued</span>
+                    <span className="min-w-0 flex-1 truncate">{steer.text}</span>
+                    {onSendSteerNow && (
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <Button
+                            type="button"
+                            variant="ghost"
+                            size="icon"
+                            className="size-6 shrink-0"
+                            onClick={() => onSendSteerNow(steer.id)}
+                            aria-label="Send now (interrupts current turn)"
+                          >
+                            <SendHorizontalIcon className="size-3" />
+                          </Button>
+                        </TooltipTrigger>
+                        <TooltipContent>Send now — interrupts</TooltipContent>
+                      </Tooltip>
+                    )}
+                    {onRemoveSteer && (
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <Button
+                            type="button"
+                            variant="ghost"
+                            size="icon"
+                            className="size-6 shrink-0"
+                            onClick={() => onRemoveSteer(steer.id)}
+                            aria-label="Remove queued message"
+                          >
+                            <XIcon className="size-3" />
+                          </Button>
+                        </TooltipTrigger>
+                        <TooltipContent>Remove</TooltipContent>
+                      </Tooltip>
+                    )}
+                  </div>
+                ))}
+              </div>
+            )}
             <InputGroup className="rounded-2xl border-border/80 shadow-sm transition-shadow focus-within:shadow-md">
               <InputGroupTextarea
                 ref={textareaRef}
@@ -665,38 +708,17 @@ export const ChatView = ({
                 ) : (
                   <>
                     {/*
-                     * Running with typed text: offer an immediate interrupt
-                     * alongside the steer Send. Interrupt aborts the current
-                     * turn and resends now; Send folds the message into the
-                     * live turn (queue-steer).
-                     */}
-                    {isRunning && onInterrupt && input.trim() && (
-                      <Tooltip>
-                        <TooltipTrigger asChild>
-                          <InputGroupButton
-                            type="button"
-                            size="icon-sm"
-                            variant="outline"
-                            onClick={handleInterrupt}
-                            aria-label="Interrupt and send now"
-                          >
-                            <FastForwardIcon className="size-3" />
-                          </InputGroupButton>
-                        </TooltipTrigger>
-                        <TooltipContent>Interrupt &amp; send now</TooltipContent>
-                      </Tooltip>
-                    )}
-                    {/*
-                     * Idle, or running with typed text: the primary button
-                     * sends. A send mid-run steers the live turn (see the
-                     * driver's sendMessage).
+                     * The primary button sends. Submitting while a turn is
+                     * running is a "send now": it interrupts the live run and
+                     * starts a fresh turn with this message immediately (see
+                     * the driver's sendMessage). Idle, it just sends.
                      */}
                     <InputGroupButton
                       type="submit"
                       size="icon-sm"
                       variant="default"
                       disabled={!input.trim()}
-                      aria-label={isRunning ? "Steer response" : "Send message"}
+                      aria-label={isRunning ? "Send now (interrupts)" : "Send message"}
                     >
                       <SendIcon className="size-3" />
                     </InputGroupButton>

package/src/react/mastra-chat.tsx

@@ -19,7 +19,9 @@ import type { MastraStreamResponse } from "../support/mastra-stream";
 import {
   createThreadSession,
   DEFAULT_THREAD_SESSION_KEY,
+  enqueueSteer,
   isSessionRunning,
+  removeSteer as removeSteerFromQueue,
   sessionKey,
   terminateRunningToolEvents,
   type ThreadSession,
@@ -409,6 +411,11 @@ export const useMastraChat = (
   const historyInFlightRef = useRef(false);
   const feedbackByMessageRef = useRef<Record<string, MessageFeedback>>({});
   feedbackByMessageRef.current = activeSession.feedbackByMessage;
+  // Drains the next queued steer when a turn ends. Held in a ref because it
+  // closes over `runStream`, which is defined below and itself calls
+  // `driveStream` (which invokes this) - the ref breaks that cycle without a
+  // stale-closure hazard (assigned each render, same pattern as `loadMoreRef`).
+  const drainQueueRef = useRef<(threadId: string) => void>(() => {});
 
   const writeMessages = useCallback(
     (threadId: string, next: UIMessage[]) => {
@@ -732,6 +739,8 @@ export const useMastraChat = (
         });
         if (getSession(threadId).runToken === token) {
           refreshThreadsSoon();
+          // Turn finished on its own: start the oldest queued steer, if any.
+          drainQueueRef.current(threadId);
         }
       } catch (caught) {
         if (getSession(threadId).runToken !== token) return;
@@ -785,6 +794,22 @@ export const useMastraChat = (
     [driveStream, mastraClient, agentId, updateSession],
   );
 
+  // 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
+  // definition cycle.
+  drainQueueRef.current = (threadId: string) => {
+    const queued = getSession(threadId).queuedSteers;
+    if (queued.length === 0) return;
+    const [head] = queued;
+    updateSession(threadId, (session) => ({
+      ...session,
+      queuedSteers: removeSteerFromQueue(session.queuedSteers, head.id),
+    }));
+    const { next } = appendUserMessage(threadId, head.text);
+    void runStream(threadId, next);
+  };
+
   // 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
@@ -901,53 +926,57 @@ export const useMastraChat = (
     [activeThreadId, getSession, noteThreadActivity, updateSession, writeMessages],
   );
 
+  // Send a message on the active thread. Submitting while a turn is already
+  // streaming ENQUEUES the message as a steer (it waits, no interrupt) - the
+  // queue drains oldest-first when the turn ends, or the user fires one early
+  // with `sendSteerNow`. An idle submit starts a turn right away.
   const sendMessage = useCallback<ChatViewProps["sendMessage"]>(
     (message) => {
       const text = message.text ?? "";
       if (!text) return;
       const threadId = activeKey;
-      const { before, next } = appendUserMessage(threadId, text);
-      // Steering: if a turn is already streaming on this thread, hand the
-      // message to the live run so the agent folds it into the current turn
-      // (no restart). If the server won't deliver it, fall back to
-      // interrupting + resending so a steer never silently drops.
-      if (isSessionRunning(before) && before.runId) {
-        const runId = before.runId;
-        const steerThreadId =
-          threadId === DEFAULT_THREAD_SESSION_KEY ? undefined : threadId;
-        void mastraClient
-          .queueMessage({ agentId, runId, threadId: steerThreadId, message: text })
-          .then((accepted) => {
-            if (accepted) {
-              logger.info("steer:queued", { runId });
-              return;
-            }
-            logger.info("steer:fallback-interrupt", { runId });
-            void runStream(threadId, getSession(threadId).messages);
-          });
+      if (isSessionRunning(getSession(threadId))) {
+        updateSession(threadId, (session) => ({
+          ...session,
+          queuedSteers: enqueueSteer(session.queuedSteers, { id: nanoid(), text }),
+        }));
         return;
       }
+      const { next } = appendUserMessage(threadId, text);
       void runStream(threadId, next);
     },
-    [appendUserMessage, runStream, activeKey, getSession, mastraClient, agentId],
+    [appendUserMessage, runStream, activeKey, getSession, updateSession],
   );
 
-  // Interrupt-and-resend: unconditionally abort any in-flight run on the
-  // active thread and start a fresh turn with `text` included immediately.
-  // The composer offers this alongside the queue-steer send so the user can
-  // force an immediate course-correction rather than waiting for the current
-  // turn to fold in a queued message. `runStream`/`driveStream` supersede the
-  // prior run (abort + runToken bump + pill cleanup).
-  const interrupt = useCallback(
-    (message: { text?: string }) => {
-      const text = message.text ?? "";
-      if (!text) return;
+  // Fire a queued steer immediately, out of order: remove it from the queue,
+  // append it, and start a turn. `runStream`/`driveStream` supersede any
+  // in-flight run (abort + runToken bump + settle running pills), so this
+  // interrupts the current turn and sends the chosen steer now.
+  const sendSteerNow = useCallback(
+    (steerId: string) => {
       const threadId = activeKey;
-      const { next } = appendUserMessage(threadId, text);
-      logger.info("steer:interrupt", { threadId });
+      const steer = getSession(threadId).queuedSteers.find((s) => s.id === steerId);
+      if (!steer) return;
+      updateSession(threadId, (session) => ({
+        ...session,
+        queuedSteers: removeSteerFromQueue(session.queuedSteers, steerId),
+      }));
+      logger.info("steer:send-now", { threadId });
+      const { next } = appendUserMessage(threadId, steer.text);
       void runStream(threadId, next);
     },
-    [appendUserMessage, runStream, activeKey],
+    [activeKey, appendUserMessage, getSession, runStream, updateSession],
+  );
+
+  // Drop a queued steer without sending it.
+  const removeSteer = useCallback(
+    (steerId: string) => {
+      updateSession(activeKey, (session) => ({
+        ...session,
+        queuedSteers: removeSteerFromQueue(session.queuedSteers, steerId),
+      }));
+    },
+    [activeKey, updateSession],
   );
 
   /**
@@ -1412,7 +1441,9 @@ export const useMastraChat = (
     status: activeSession.status,
     error: activeSession.error,
     sendMessage,
-    onInterrupt: interrupt,
+    queuedSteers: activeSession.queuedSteers,
+    onSendSteerNow: sendSteerNow,
+    onRemoveSteer: removeSteer,
     regenerate,
     onStop: stop,
     suggestions,

package/src/react/types.ts

@@ -41,6 +41,14 @@ export type ToolProgress = GenieWriterEvent;
  */
 export type ChatModelOption = { name: string; displayName?: string };
 
+/**
+ * A steer message submitted while a turn was already streaming. It waits in a
+ * per-thread queue until the running turn ends (auto-sent oldest-first) or the
+ * user fires it early with "send now". `id` is a stable key for rendering /
+ * removal.
+ */
+export type QueuedSteer = { id: string; text: string };
+
 /** Thumbs reaction a user can leave on an assistant turn. */
 export type FeedbackValue = "up" | "down";
 
@@ -89,16 +97,25 @@ export type ChatViewProps = {
    * a host driving `ChatView` itself supplies its own.
    */
   error?: Error | null;
+  /**
+   * Send a message on the active thread. Submitting while a turn is streaming
+   * ENQUEUES the message as a steer (it waits, no interrupt); the queue drains
+   * oldest-first when the turn ends. An idle submit starts a turn immediately.
+   */
   sendMessage: (message: { text: string }) => void;
   /**
-   * Send a message that interrupts the in-flight turn immediately: abort the
-   * current run and start a fresh turn with this message. When provided and
-   * the chat is running, the composer shows a small "interrupt" action next
-   * to the queue-steer Send, so the user can force an immediate
-   * course-correction instead of folding the message into the live turn.
-   * Omit to offer only the queue-steer send while running.
+   * Steers submitted mid-turn that are waiting to run (oldest first). When
+   * non-empty the composer shows them as chips above the input, each with a
+   * "send now" and a remove action.
+   */
+  queuedSteers?: QueuedSteer[];
+  /**
+   * Fire a queued steer immediately, out of order: interrupt the current turn
+   * and start a fresh turn with that steer (removing it from the queue).
    */
-  onInterrupt?: (message: { text: string }) => void;
+  onSendSteerNow?: (steerId: string) => void;
+  /** Drop a queued steer without sending it. */
+  onRemoveSteer?: (steerId: string) => void;
   regenerate?: () => void;
   /**
    * Abort the in-flight response. When provided and the chat is running

package/src/support/mastra-client.ts

@@ -123,50 +123,6 @@ export class MastraPluginClient extends MastraClient {
     return asMastraStreamResponse(response);
   }
 
-  /**
-   * Steer a live run by handing it another message mid-turn ("queue"), via
-   * the agent `/queue-message` route. `behavior` controls what happens when
-   * the run is active: `deliver` (default) folds the message into the current
-   * turn so the agent picks it up without restarting; `persist` holds it for
-   * the next turn; `discard` drops it. Routed per call (own thread header, no
-   * shared client state) like {@link streamAgent}.
-   *
-   * Resolves `true` when the server accepted the message for delivery, `false`
-   * otherwise (unknown run / route unsupported / non-2xx) - never throws for a
-   * rejected steer, so the caller can fall back to interrupting + resending.
-   * Queue / signal routes are `@experimental` in Mastra.
-   */
-  async queueMessage(params: {
-    agentId: string;
-    runId: string;
-    threadId?: string;
-    message: string;
-    behavior?: "deliver" | "persist" | "discard";
-  }): Promise<boolean> {
-    const url = `${this.basePath}/agents/${encodeURIComponent(params.agentId)}/queue-message`;
-    try {
-      const response = await fetch(url, {
-        method: "POST",
-        credentials: "include",
-        headers: {
-          "Content-Type": "application/json",
-          ...this.#routingHeaders({ threadId: params.threadId }),
-        },
-        body: JSON.stringify({
-          runId: params.runId,
-          ...(params.threadId ? { threadId: params.threadId } : {}),
-          message: params.message,
-          ifActive: { behavior: params.behavior ?? "deliver" },
-        }),
-      });
-      if (!response.ok) return false;
-      const body = (await response.json().catch(() => null)) as { accepted?: boolean } | null;
-      return body?.accepted === true;
-    } catch {
-      return false;
-    }
-  }
-
   /**
    * Resume a suspended `requireApproval` tool via `approve-tool-call`.
    * Reads SSE directly instead of `agent.approveToolCall()` so the

package/src/support/thread-sessions.ts

@@ -3,9 +3,12 @@ import type {
   ChatStatus,
   MessageFeedback,
   PendingApproval,
+  QueuedSteer,
   ToolEvent,
 } from "../react/types";
 
+export type { QueuedSteer } from "../react/types";
+
 /** Session-scoped transcript + stream state for one conversation thread. */
 export type ThreadSession = {
   messages: UIMessage[];
@@ -22,6 +25,8 @@ export type ThreadSession = {
   hasMoreHistory: boolean;
   historyPage: number;
   lastUserText: string | null;
+  /** Steers submitted mid-turn, waiting to run (oldest first). */
+  queuedSteers: QueuedSteer[];
 };
 
 /** Map key for the classic single-thread chat (no explicit thread id). */
@@ -43,6 +48,7 @@ export function createThreadSession(): ThreadSession {
     hasMoreHistory: false,
     historyPage: 0,
     lastUserText: null,
+    queuedSteers: [],
   };
 }
 
@@ -50,6 +56,19 @@ export function isSessionRunning(session: ThreadSession): boolean {
   return session.status === "submitted" || session.status === "streaming";
 }
 
+/** Append a steer to the queue (oldest first). Returns a new array. */
+export function enqueueSteer(
+  queue: QueuedSteer[],
+  steer: QueuedSteer,
+): QueuedSteer[] {
+  return [...queue, steer];
+}
+
+/** Remove the steer with `id` from the queue. Returns a new array. */
+export function removeSteer(queue: QueuedSteer[], id: string): QueuedSteer[] {
+  return queue.filter((steer) => steer.id !== id);
+}
+
 /**
  * Settle any tool-progress pills still marked `running` to `done`. A cancelled
  * or interrupted turn stops delivering the `tool-result` / `tool-error` chunks