@dbx-tools/ui-mastra 0.9.128 → 0.9.131

package/src/support/export.ts

@@ -67,6 +67,7 @@ export interface ExportBrand {
 export interface EmbedResolver {
   chart(id: string): Promise<Chart | undefined>;
   statement(id: string): Promise<StatementData | undefined>;
+  visualization(id: string): Promise<StatementData | undefined>;
 }
 
 /** Options accepted by {@link exportChat}. */
@@ -185,14 +186,15 @@ function printViaHiddenIframe(html: string, downloadName: string): void {
 
 /** One slice of a message: prose, a chart embed, or a data embed. */
 type Segment =
-  { kind: "text"; text: string } | { kind: "chart"; id: string } | { kind: "data"; id: string };
+  | { kind: "text"; text: string }
+  | { kind: "chart"; id: string }
+  | { kind: "data"; id: string }
+  | { kind: "visualization"; id: string };
 
 /**
- * Split message text into prose / chart / data segments at
- * `[chart:<uuid>]` / `[data:<uuid>]` marker positions. Mirrors the live
- * `MarkdownWithEmbeds` splitter so an export matches what's on screen:
- * non-UUID (fabricated) ids and unknown marker types collapse away so no
- * literal `[type:...]` leaks into the output.
+ * Split message text into prose, chart, and data segments. A native Genie
+ * visualization exports as its backing table because the interactive AppKit
+ * chart has no serializable ECharts spec.
  */
 function splitSegments(text: string): Segment[] {
   const segments: Segment[] = [];
@@ -201,8 +203,12 @@ function splitSegments(text: string): Segment[] {
     if (marker.start > last) {
       segments.push({ kind: "text", text: text.slice(last, marker.start) });
     }
-    if (markers.isUuid(marker.id) && (marker.type === "chart" || marker.type === "data")) {
-      segments.push({ kind: marker.type, id: marker.id });
+    if (markers.isUuid(marker.id) && marker.type === "chart") {
+      segments.push({ kind: "chart", id: marker.id });
+    } else if (markers.isUuid(marker.id) && marker.type === "data") {
+      segments.push({ kind: "data", id: marker.id });
+    } else if (markers.isUuid(marker.id) && marker.type === "visualization") {
+      segments.push({ kind: "visualization", id: marker.id });
     }
     last = marker.end;
   }
@@ -281,7 +287,7 @@ async function messageBodyHtml(message: UIMessage, resolver: EmbedResolver): Pro
       if (svg) parts.push(`<div class="embed embed-chart">${svg}</div>`);
       continue;
     }
-    const table = await dataTableHtml(resolver, seg.id);
+    const table = await dataTableHtml(resolver, seg.id, seg.kind === "visualization");
     if (table) parts.push(table);
   }
   return parts.join("\n");
@@ -332,8 +338,12 @@ async function chartSvg(resolver: EmbedResolver, id: string): Promise<string | n
 }
 
 /** Resolve a data id and render its rows to an HTML table. `null` on miss. */
-async function dataTableHtml(resolver: EmbedResolver, id: string): Promise<string | null> {
-  const data = await safeStatement(resolver, id);
+async function dataTableHtml(
+  resolver: EmbedResolver,
+  id: string,
+  visualization = false,
+): Promise<string | null> {
+  const data = await safeStatement(resolver, id, visualization);
   if (!data || data.rows.length === 0) return null;
   const head = data.columns.map((c) => `<th>${escapeHtml(stringUtils.toLabel(c))}</th>`).join("");
   const body = data.rows
@@ -383,7 +393,7 @@ async function messageBodyMarkdown(message: UIMessage, resolver: EmbedResolver):
       if (chart?.result) parts.push(`> **Chart:** ${chartTitle(chart)}`);
       continue;
     }
-    const table = await dataTableMarkdown(resolver, seg.id);
+    const table = await dataTableMarkdown(resolver, seg.id, seg.kind === "visualization");
     if (table) parts.push(table);
   }
   return parts.join("\n\n");
@@ -400,8 +410,12 @@ function chartTitle(chart: Chart): string {
 }
 
 /** Render statement rows to a GFM table. `null` on miss / empty. */
-async function dataTableMarkdown(resolver: EmbedResolver, id: string): Promise<string | null> {
-  const data = await safeStatement(resolver, id);
+async function dataTableMarkdown(
+  resolver: EmbedResolver,
+  id: string,
+  visualization = false,
+): Promise<string | null> {
+  const data = await safeStatement(resolver, id, visualization);
   if (!data || data.rows.length === 0) return null;
   const header = `| ${data.columns.map((c) => mdCell(stringUtils.toLabel(c))).join(" | ")} |`;
   const sep = `| ${data.columns.map(() => "---").join(" | ")} |`;
@@ -427,9 +441,10 @@ async function safeChart(resolver: EmbedResolver, id: string): Promise<Chart | u
 async function safeStatement(
   resolver: EmbedResolver,
   id: string,
+  visualization = false,
 ): Promise<StatementData | undefined> {
   try {
-    return await resolver.statement(id);
+    return await (visualization ? resolver.visualization(id) : resolver.statement(id));
   } catch {
     return undefined;
   }

package/src/support/genie-client.ts

@@ -0,0 +1,220 @@
+import { routes, wire, type MastraClientConfig } from "@dbx-tools/shared-mastra";
+import type {
+  ListAgentSuspendedRunsResponse,
+  ListMemoryThreadMessagesResponse,
+  ListMemoryThreadsResponse,
+} from "@mastra/client-js";
+import { validateUIMessages, type UIMessage, type UIMessageChunk } from "ai";
+import { MastraPluginClient, type MastraStreamResponse } from "./mastra-client.ts";
+
+/**
+ * {@link MastraPluginClient} that talks to one Genie space directly through
+ * the Mastra plugin's `/genie/:alias` routes instead of an agent and Mastra
+ * Memory. Genie owns all state: its conversations are the threads (the
+ * conversation id is the thread id), its messages are the history, and each
+ * turn streams the same AI SDK chunks as an agent's `ask_genie` call, so the
+ * Mastra chat renders it unchanged.
+ *
+ * A brand-new thread has no Genie conversation until its first turn; the
+ * stream announces the conversation id, which {@link MastraStreamResponse.threadId}
+ * reports so the chat adopts it.
+ */
+export class GenieChatClient extends MastraPluginClient {
+  /** Genie space alias every route is scoped to. */
+  readonly alias: string;
+  override readonly backgroundTurns = false;
+  override readonly feedbackEnabled = false;
+  override readonly threadRename = false;
+  override readonly attachments = false;
+  /** Thread ids known to be Genie conversations (listed, loaded, or announced). */
+  readonly #conversations = new Set<string>();
+  /** Transcript message id to Genie message id, for regenerate cleanup. */
+  readonly #genieMessageIds = new Map<string, string>();
+
+  constructor(config: MastraClientConfig, alias: string) {
+    super(config);
+    this.alias = alias;
+  }
+
+  #url(...parts: string[]): string {
+    return `${this.basePath}${routes.genieRoutePath(this.alias, ...parts)}`;
+  }
+
+  async #delete(url: string, signal?: AbortSignal): Promise<void> {
+    const res = await fetch(url, {
+      method: "DELETE",
+      credentials: "include",
+      ...(signal ? { signal } : {}),
+    });
+    if (!res.ok && res.status !== 404) throw new Error(`HTTP ${res.status}`);
+  }
+
+  /** Stream one Genie turn, continuing the thread's conversation when it has one. */
+  override async streamAgent(params: {
+    messages: UIMessage[];
+    runId: string;
+    threadId?: string;
+    signal?: AbortSignal;
+  }): Promise<MastraStreamResponse> {
+    const userMessage = [...params.messages].reverse().find((message) => message.role === "user");
+    const question = (userMessage?.parts ?? [])
+      .map((part) => (part.type === "text" ? part.text : ""))
+      .join("")
+      .trim();
+    const conversationId =
+      params.threadId && this.#conversations.has(params.threadId) ? params.threadId : undefined;
+    const response = await this.uiStream({
+      path: this.#url(routes.MASTRA_ROUTES.chat),
+      chatId: params.threadId ?? params.runId,
+      messages: userMessage ? [userMessage] : [],
+      body: { question, ...(conversationId ? { conversationId } : {}) },
+      routing: {},
+      signal: params.signal,
+    });
+    let resolved: string | undefined;
+    const stream = response.stream.pipeThrough(
+      new TransformStream<UIMessageChunk, UIMessageChunk>({
+        transform: (chunk, controller) => {
+          if (chunk.type === wire.GENIE_CONVERSATION_PART_TYPE) {
+            const data = wire.GenieConversationPartDataSchema.safeParse(chunk.data);
+            if (data.success) {
+              resolved = data.data.conversationId;
+              this.#conversations.add(resolved);
+              if (userMessage && data.data.messageId) {
+                this.#genieMessageIds.set(userMessage.id, data.data.messageId);
+              }
+            }
+          }
+          controller.enqueue(chunk);
+        },
+      }),
+    );
+    return { headers: response.headers, stream, threadId: () => resolved };
+  }
+
+  /** Genie turns are request-scoped; there is no background run to observe. */
+  override async observeAgentStream(): Promise<MastraStreamResponse> {
+    throw new Error("Direct Genie chat has no background runs");
+  }
+
+  /** Genie turns stop when their stream is aborted. */
+  override async abortAgentRun(): Promise<boolean> {
+    return false;
+  }
+
+  /** Genie has no approval-gated tools. */
+  override async suspendedRuns(): Promise<ListAgentSuspendedRunsResponse> {
+    return { runs: [], total: 0 };
+  }
+
+  /** Starter questions for this client's Genie space. */
+  override async suggestions(_agentId?: string, signal?: AbortSignal): Promise<string[]> {
+    const payload = await this.getJson(
+      this.#url(routes.MASTRA_ROUTES.suggestions),
+      wire.MastraSuggestionsResponseSchema,
+      signal,
+    );
+    return payload.questions;
+  }
+
+  /** List the caller's Genie conversations as chat threads. */
+  override async threads(
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ListMemoryThreadsResponse> {
+    const payload = await this.getJson(
+      this.#url(routes.MASTRA_ROUTES.threads),
+      wire.GenieThreadsResponseSchema,
+      options.signal,
+    );
+    for (const thread of payload.threads) this.#conversations.add(thread.id);
+    const threads = payload.threads.map((thread) => ({
+      id: thread.id,
+      ...(thread.title ? { title: thread.title } : {}),
+      resourceId: "",
+      createdAt: thread.createdAt,
+      updatedAt: thread.createdAt,
+      metadata: {},
+    }));
+    return {
+      threads,
+      total: threads.length,
+      page: 0,
+      perPage: threads.length,
+      hasMore: false,
+    } satisfies ListMemoryThreadsResponse;
+  }
+
+  /**
+   * Load a Genie conversation's full transcript. Genie returns the whole
+   * conversation at once, so only the first page carries messages.
+   */
+  override async history(options: {
+    threadId: string;
+    page?: number;
+    signal?: AbortSignal;
+  }): Promise<ListMemoryThreadMessagesResponse> {
+    const page = options.page ?? 0;
+    let messages: UIMessage[] = [];
+    if (page === 0) {
+      const payload = await this.getJson(
+        this.#url(routes.MASTRA_ROUTES.threads, options.threadId, routes.MASTRA_ROUTES.messages),
+        wire.GenieThreadMessagesResponseSchema,
+        options.signal,
+      );
+      messages = await validateUIMessages({ messages: payload.messages });
+      this.#conversations.add(options.threadId);
+      // History ids already address their Genie message; the delete route
+      // resolves a question id to the message that owns it.
+      for (const message of messages) this.#genieMessageIds.set(message.id, message.id);
+    }
+    return {
+      messages: [],
+      uiMessages: [...messages].reverse(),
+      total: messages.length,
+      page,
+      perPage: messages.length,
+      hasMore: false,
+    } satisfies ListMemoryThreadMessagesResponse;
+  }
+
+  /** Delete the Genie conversation behind a thread. */
+  override async removeThread(
+    threadId: string,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<void> {
+    if (!this.#conversations.has(threadId)) return;
+    await this.#delete(this.#url(routes.MASTRA_ROUTES.threads, threadId), options.signal);
+    this.#conversations.delete(threadId);
+  }
+
+  /** Clearing a Genie thread deletes its conversation; the next turn starts a new one. */
+  override async clearHistory(options: { threadId: string; signal?: AbortSignal }): Promise<void> {
+    await this.removeThread(options.threadId, options);
+  }
+
+  /** Genie conversations cannot be renamed. */
+  override async renameThread(): Promise<void> {
+    throw new Error("Genie conversations cannot be renamed");
+  }
+
+  /** Delete the Genie messages behind the given transcript messages. */
+  override async deleteMessages(
+    threadId: string,
+    messageIds: string[],
+    options: { signal?: AbortSignal } = {},
+  ): Promise<void> {
+    if (!this.#conversations.has(threadId)) return;
+    const genieIds = new Set(
+      messageIds.flatMap((id) => {
+        const genieId = this.#genieMessageIds.get(id);
+        return genieId ? [genieId] : [];
+      }),
+    );
+    for (const genieId of genieIds) {
+      await this.#delete(
+        this.#url(routes.MASTRA_ROUTES.threads, threadId, routes.MASTRA_ROUTES.messages, genieId),
+        options.signal,
+      );
+    }
+  }
+}

package/src/support/index.ts

@@ -8,10 +8,12 @@ export * as chartTheme from "./chart-theme.ts";
 export * as clipboard from "./clipboard.ts";
 export * as download from "./download.ts";
 export * as exportModule from "./export.ts";
+export * as genieClient from "./genie-client.ts";
 export * as mastraClient from "./mastra-client.ts";
 export * as modelSelection from "./model-selection.ts";
 export * as requestContext from "./request-context.ts";
 export * as threadLabels from "./thread-labels.ts";
+export * as threadPersistence from "./thread-persistence.ts";
 export * as threadSessions from "./thread-sessions.ts";
 export * as threadTabs from "./thread-tabs.ts";
 export * as toolEvents from "./tool-events.ts";
@@ -20,7 +22,8 @@ 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 { MastraChatRequestError, MastraPluginClient, useMastraConfig, useMastraClient, useMastraMlflowExperiment, useMastraModels, useMastraDefaultModel, useMastraSuggestions, useMastraThreads, useChartFetch, useStatementFetch } from "./mastra-client.ts";
+export { GenieChatClient } from "./genie-client.ts";
+export { MastraChatRequestError, MastraPluginClient, useMastraConfig, useMastraClient, useMastraMlflowExperiment, useMastraModels, useMastraDefaultModel, useMastraSuggestions, useMastraThreads, useChartFetch, useStatementFetch, useVisualizationFetch } 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";

package/src/support/mastra-client.ts

@@ -31,6 +31,12 @@ type NativeAgentClient = ReturnType<MastraClient["getAgent"]>;
 export interface MastraStreamResponse {
   headers: Headers;
   stream: ReadableStream<UIMessageChunk>;
+  /**
+   * Thread id the server assigned to this turn, read after the stream drains.
+   * Set by backends whose threads are server-minted (a Genie conversation);
+   * the chat adopts it in place of the client-minted id it streamed under.
+   */
+  threadId?: () => string | undefined;
 }
 
 /** Terminal HTTP failure returned before a chat stream was established. */
@@ -56,7 +62,8 @@ export type MastraMemoryThread = ListMemoryThreadsResponse["threads"][number];
  *   - Native Mastra memory history and thread management, plus the model
  *     catalogue (`models`),
  *     Genie starter prompts (`suggestions`), MLflow feedback logging
- *     (`feedback`), and inline embed resolution (`chart` / `statement`)
+ *     (`feedback`), and inline embed resolution (`chart`, `statement`,
+ *     `visualization`)
  *     over the plugin's own routes - all derived from `basePath` +
  *     {@link routes.MASTRA_ROUTES}.
  *
@@ -89,6 +96,10 @@ export class MastraPluginClient extends MastraClient {
   readonly chatAlwaysAvailable: boolean;
   /** Whether turns continue server-side after the initiating stream disconnects. */
   readonly backgroundTurns: boolean;
+  /** Whether {@link renameThread} is supported by this client's thread store. */
+  readonly threadRename: boolean = true;
+  /** Whether a chat may attach files to a turn. */
+  readonly attachments: boolean = true;
 
   constructor(config: MastraClientConfig) {
     super({
@@ -124,7 +135,7 @@ export class MastraPluginClient extends MastraClient {
     return headers;
   }
 
-  async #uiStream(options: {
+  protected async uiStream(options: {
     path: string;
     chatId: string;
     messages: UIMessage[];
@@ -219,7 +230,7 @@ export class MastraPluginClient extends MastraClient {
     requestContext?: MastraRequestContextSnapshot;
     signal?: AbortSignal;
   }): Promise<MastraStreamResponse> {
-    return this.#uiStream({
+    return this.uiStream({
       path: `${this.basePath}${routes.MASTRA_ROUTES.chat}/${encodeURIComponent(params.agentId)}`,
       chatId: params.threadId ?? params.runId,
       messages: params.messages,
@@ -320,7 +331,7 @@ export class MastraPluginClient extends MastraClient {
       signal?: AbortSignal;
     },
   ): Promise<MastraStreamResponse> {
-    return this.#uiStream({
+    return this.uiStream({
       path: `${this.basePath}${routes.MASTRA_ROUTES.chat}/${encodeURIComponent(agentId)}`,
       chatId: params.threadId ?? params.runId,
       messages: [],
@@ -345,7 +356,7 @@ export class MastraPluginClient extends MastraClient {
    * chat-capable models for a picker.
    */
   async models(signal?: AbortSignal): Promise<ServingEndpointSummary[]> {
-    const payload = await this.#getJson(
+    const payload = await this.getJson(
       `${this.basePath}${routes.MASTRA_ROUTES.models}`,
       wire.ServingEndpointsResponseSchema,
       signal,
@@ -369,7 +380,7 @@ export class MastraPluginClient extends MastraClient {
 
   /** Fetch the complete resolved default-model descriptor for an agent. */
   async defaultModelDetails(agentId?: string, signal?: AbortSignal): Promise<DefaultModelResponse> {
-    const payload = await this.#getJson(
+    const payload = await this.getJson(
       this.#agentScoped(routes.MASTRA_ROUTES.defaultModel, agentId),
       wire.DefaultModelResponseSchema,
       signal,
@@ -383,7 +394,7 @@ export class MastraPluginClient extends MastraClient {
    * Genie space (or it defines none).
    */
   async suggestions(agentId?: string, signal?: AbortSignal): Promise<string[]> {
-    const payload = await this.#getJson(
+    const payload = await this.getJson(
       this.#agentScoped(routes.MASTRA_ROUTES.suggestions, agentId),
       wire.MastraSuggestionsResponseSchema,
       signal,
@@ -513,7 +524,7 @@ export class MastraPluginClient extends MastraClient {
    * `CAN_MANAGE`; inability to determine access resolves to `null`.
    */
   async mlflowExperiment(signal?: AbortSignal): Promise<MastraMlflowExperimentResponse> {
-    return this.#getJson(
+    return this.getJson(
       `${this.basePath}${routes.MASTRA_ROUTES.mlflowExperiment}`,
       feedback.MastraMlflowExperimentResponseSchema,
       signal,
@@ -541,6 +552,11 @@ export class MastraPluginClient extends MastraClient {
     return this.#embed("data", id, wire.StatementDataSchema.parse, signal);
   }
 
+  /** Resolve AppKit UI visualization data for a direct Genie statement. */
+  visualization(id: string, signal?: AbortSignal): Promise<StatementData | undefined> {
+    return this.#embed("visualization", id, wire.StatementDataSchema.parse, signal);
+  }
+
   /**
    * Compose an agent-scoped URL: `${basePath}${segment}` for the
    * default agent (the mount that does not require an `:agentId`), or
@@ -566,7 +582,7 @@ export class MastraPluginClient extends MastraClient {
   }
 
   /** GET + JSON-parse + schema-validate against a route that always 200s. */
-  async #getJson<T>(
+  protected async getJson<T>(
     url: string,
     schema: { parse: (raw: unknown) => T },
     signal?: AbortSignal,
@@ -848,13 +864,16 @@ export const useMastraDefaultModel = (
  * Pass `enabled: false` to skip the fetch (e.g. when the caller
  * supplies its own explicit suggestion list), in which case
  * `questions` stays empty. Any fetch error degrades silently to no
- * suggestions - they're a non-critical enhancement.
+ * suggestions - they're a non-critical enhancement. `clientOverride`
+ * replaces the plugin's default client (e.g. a direct Genie client).
  */
 export const useMastraSuggestions = (
   agentId?: string,
   enabled = true,
+  clientOverride?: MastraPluginClient,
 ): { questions: string[]; loading: boolean } => {
-  const client = useMastraClient();
+  const defaultClient = useMastraClient();
+  const client = clientOverride ?? defaultClient;
   const [questions, setQuestions] = useState<string[]>([]);
   const [loading, setLoading] = useState(enabled);
 
@@ -898,17 +917,20 @@ export const useMastraSuggestions = (
  * hidden), in which case `threads` stays empty. A failed fetch degrades
  * to an empty list - the conversation list is a non-critical
  * enhancement layered over the always-available default thread.
+ * `clientOverride` replaces the plugin's default client.
  */
 export const useMastraThreads = (
   agentId?: string,
   enabled = true,
+  clientOverride?: MastraPluginClient,
 ): {
   threads: MastraMemoryThread[];
   loading: boolean;
   error: Error | null;
   refresh: () => void;
 } => {
-  const client = useMastraClient();
+  const defaultClient = useMastraClient();
+  const client = clientOverride ?? defaultClient;
   const [threads, setThreads] = useState<MastraMemoryThread[]>([]);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
@@ -952,7 +974,7 @@ export const useMastraThreads = (
 /**
  * Hook state for {@link useByIdFetch}. Generic over the
  * resource's payload shape; consumers read `data` / `loading` /
- * `error` exactly as the chart and statement slots do. A 404 on
+ * `error` exactly as the embed slots do. A 404 on
  * the server resolves as `data === undefined` with `error ===
  * null` so the slot renders nothing (matches "expired /
  * unknown id" semantics across all by-id resources).
@@ -1049,7 +1071,7 @@ function readFetchCache<T>(key: string | undefined): T | undefined {
 
 /**
  * React hook for any resource the Mastra plugin exposes as
- * `/<resource>/:id`. Powers both the chart and statement slots
+ * `/<resource>/:id`. Powers the chart, statement, and visualization slots
  * in the chat UI; the slot-specific hooks below are thin
  * adapters that pick the right cache `key`, `fetcher`, and
  * terminal check.
@@ -1182,3 +1204,16 @@ export const useStatementFetch = (
   const fetcher = useCallback(() => client.statement(statementId as string), [client, statementId]);
   return useByIdFetch<StatementData>(key, fetcher, statementIsTerminal);
 };
+
+/** Fetch a direct Genie statement through the OBO-only visualization resolver. */
+export const useVisualizationFetch = (
+  statementId: string | undefined,
+): ByIdFetchState<StatementData> => {
+  const client = useMastraClient();
+  const key = statementId ? `visualization:${statementId}` : undefined;
+  const fetcher = useCallback(
+    () => client.visualization(statementId as string),
+    [client, statementId],
+  );
+  return useByIdFetch<StatementData>(key, fetcher, statementIsTerminal);
+};

package/src/support/thread-persistence.ts

@@ -0,0 +1,9 @@
+/** Build the browser storage key for one Mastra agent's selected thread. */
+export function threadStorageKey(
+  basePath: string,
+  agentId: string,
+  resourceScope?: string,
+): string {
+  const prefix = `dbx-mastra-thread:${basePath}:${agentId}`;
+  return resourceScope ? `${prefix}:${encodeURIComponent(resourceScope)}` : prefix;
+}

package/src/support/thread-sessions.ts

@@ -67,6 +67,25 @@ export function isSessionRunning(session: ThreadSession): boolean {
   return session.status === "submitted" || session.status === "streaming";
 }
 
+/** Return the newest user message in a transcript or turn. */
+export function lastUserMessage(messages: readonly UIMessage[]): UIMessage | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message?.role === "user") return message;
+  }
+  return undefined;
+}
+
+/** Build a replacement turn that retains the interrupted user request. */
+export function interruptedTurnMessages(
+  messages: UIMessage[],
+  nextMessage: UIMessage,
+): UIMessage[] {
+  const interrupted = lastUserMessage(messages);
+  if (!interrupted || interrupted.id === nextMessage.id) return [nextMessage];
+  return [interrupted, nextMessage];
+}
+
 /** Append a steer to the queue (oldest first). Returns a new array. */
 export function enqueueSteer<T extends QueuedSteer>(queue: T[], steer: T): T[] {
   return [...queue, steer];