@runtypelabs/persona 3.16.0 → 3.18.0

package/src/components/composer-builder.ts

@@ -22,6 +22,13 @@ export interface ComposerElements {
   actionsRow: HTMLElement;
   leftActions: HTMLElement;
   rightActions: HTMLElement;
+  /**
+   * Swap the send button between its idle ("send") appearance and its
+   * streaming ("stop") appearance. In icon mode this swaps the SVG; in text
+   * mode it swaps the button label. Tooltip text is updated when a tooltip
+   * element is present.
+   */
+  setSendButtonMode: (mode: "send" | "stop") => void;
 }
 
 /**
@@ -122,7 +129,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   const useIcon = sendButtonConfig.useIcon ?? false;
   const iconText = sendButtonConfig.iconText ?? "↑";
   const iconName = sendButtonConfig.iconName;
+  const stopIconName = sendButtonConfig.stopIconName ?? "square";
   const tooltipText = sendButtonConfig.tooltipText ?? "Send message";
+  const stopTooltipText = sendButtonConfig.stopTooltipText ?? "Stop generating";
+  const sendLabel = config?.copy?.sendButtonLabel ?? "Send";
+  const stopLabel = config?.copy?.stopButtonLabel ?? "Stop";
   const showTooltip = sendButtonConfig.showTooltip ?? false;
   const buttonSize = sendButtonConfig.size ?? "40px";
   const backgroundColor = sendButtonConfig.backgroundColor;
@@ -141,6 +152,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   sendButton.type = "submit";
   sendButton.setAttribute("data-persona-composer-submit", "");
 
+  // Icons for both modes are pre-rendered so setSendButtonMode can swap them
+  // without having to re-render on every streaming state change.
+  let sendIcon: SVGElement | null = null;
+  let stopIcon: SVGElement | null = null;
+
   if (useIcon) {
     // Icon mode: circular button
     sendButton.style.width = buttonSize;
@@ -160,13 +176,14 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
       sendButton.style.color = "var(--persona-button-primary-fg, #ffffff)";
     }
 
+    const iconSize = parseFloat(buttonSize) || 24;
+    const iconColor = textColor?.trim() || "currentColor";
+
     // Use Lucide icon if iconName is provided, otherwise fall back to iconText
     if (iconName) {
-      const iconSize = parseFloat(buttonSize) || 24;
-      const iconColor = textColor?.trim() || "currentColor";
-      const iconSvg = renderLucideIcon(iconName, iconSize, iconColor, 2);
-      if (iconSvg) {
-        sendButton.appendChild(iconSvg);
+      sendIcon = renderLucideIcon(iconName, iconSize, iconColor, 2);
+      if (sendIcon) {
+        sendButton.appendChild(sendIcon);
       } else {
         sendButton.textContent = iconText;
       }
@@ -174,6 +191,9 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
       sendButton.textContent = iconText;
     }
 
+    // Pre-render the stop icon so mode swaps are cheap; it starts detached.
+    stopIcon = renderLucideIcon(stopIconName, iconSize, iconColor, 2);
+
     if (backgroundColor) {
       sendButton.style.backgroundColor = backgroundColor;
     } else {
@@ -181,7 +201,7 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     }
   } else {
     // Text mode: existing behavior
-    sendButton.textContent = config?.copy?.sendButtonLabel ?? "Send";
+    sendButton.textContent = sendLabel;
     if (textColor) {
       sendButton.style.color = textColor;
     } else {
@@ -215,14 +235,44 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   }
 
   // Add tooltip if enabled
+  let sendTooltip: HTMLElement | null = null;
   if (showTooltip && tooltipText) {
-    const tooltip = createElement("div", "persona-send-button-tooltip");
-    tooltip.textContent = tooltipText;
-    sendButtonWrapper.appendChild(tooltip);
+    sendTooltip = createElement("div", "persona-send-button-tooltip");
+    sendTooltip.textContent = tooltipText;
+    sendButtonWrapper.appendChild(sendTooltip);
   }
 
+  sendButton.setAttribute("aria-label", tooltipText);
+
   sendButtonWrapper.appendChild(sendButton);
 
+  let currentMode: "send" | "stop" = "send";
+  const setSendButtonMode = (mode: "send" | "stop") => {
+    if (mode === currentMode) return;
+    currentMode = mode;
+    const label = mode === "stop" ? stopTooltipText : tooltipText;
+    sendButton.setAttribute("aria-label", label);
+    if (sendTooltip) {
+      sendTooltip.textContent = label;
+    }
+
+    if (useIcon) {
+      // Only swap icons if both were rendered successfully; otherwise the
+      // button is using textContent fallback and there's nothing to swap.
+      if (sendIcon && stopIcon) {
+        const next = mode === "stop" ? stopIcon : sendIcon;
+        const prev = mode === "stop" ? sendIcon : stopIcon;
+        if (prev.parentNode === sendButton) {
+          sendButton.replaceChild(next, prev);
+        } else {
+          sendButton.appendChild(next);
+        }
+      }
+    } else {
+      sendButton.textContent = mode === "stop" ? stopLabel : sendLabel;
+    }
+  };
+
   // Voice recognition mic button
   const voiceRecognitionConfig = config?.voiceRecognition ?? {};
   const voiceRecognitionEnabled = voiceRecognitionConfig.enabled === true;
@@ -515,7 +565,8 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     // Actions row layout elements
     actionsRow,
     leftActions,
-    rightActions
+    rightActions,
+    setSendButtonMode
   };
 };
 

package/src/components/message-bubble.test.ts

@@ -1,7 +1,12 @@
 // @vitest-environment jsdom
 import { describe, it, expect } from "vitest";
-import { createStandardBubble, isSafeImageSrc } from "./message-bubble";
-import type { AgentWidgetMessage } from "../types";
+import {
+  createStandardBubble,
+  isSafeImageSrc,
+  resolveStopReasonNoticeText,
+  getDefaultStopReasonNoticeCopy,
+} from "./message-bubble";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "../types";
 
 const makeMessage = (overrides: Partial<AgentWidgetMessage> = {}): AgentWidgetMessage => ({
   id: "msg-1",
@@ -95,3 +100,177 @@ describe("createStandardBubble", () => {
     expect(previewImages[0]?.getAttribute("alt")).toBe("Safe image");
   });
 });
+
+describe("resolveStopReasonNoticeText", () => {
+  it("returns null for natural completions", () => {
+    expect(resolveStopReasonNoticeText("end_turn")).toBeNull();
+  });
+
+  it("returns null for unknown reasons", () => {
+    expect(resolveStopReasonNoticeText("unknown")).toBeNull();
+  });
+
+  it("returns null when stopReason is undefined", () => {
+    expect(resolveStopReasonNoticeText(undefined)).toBeNull();
+  });
+
+  it("returns the default copy for actionable reasons", () => {
+    expect(resolveStopReasonNoticeText("max_tool_calls")).toBe(
+      getDefaultStopReasonNoticeCopy("max_tool_calls")
+    );
+    expect(resolveStopReasonNoticeText("length")).toBe(
+      getDefaultStopReasonNoticeCopy("length")
+    );
+    expect(resolveStopReasonNoticeText("content_filter")).toBe(
+      getDefaultStopReasonNoticeCopy("content_filter")
+    );
+    expect(resolveStopReasonNoticeText("error")).toBe(
+      getDefaultStopReasonNoticeCopy("error")
+    );
+  });
+
+  it("applies overrides on a per-key basis", () => {
+    expect(
+      resolveStopReasonNoticeText("max_tool_calls", {
+        ["max_tool_calls" as const]: "Custom override.",
+      })
+    ).toBe("Custom override.");
+  });
+
+  it("falls back to defaults for keys not overridden", () => {
+    expect(
+      resolveStopReasonNoticeText("length", {
+        ["max_tool_calls" as const]: "Custom.",
+      })
+    ).toBe(getDefaultStopReasonNoticeCopy("length"));
+  });
+
+  it("suppresses the notice when override is an empty string", () => {
+    expect(
+      resolveStopReasonNoticeText("max_tool_calls", {
+        ["max_tool_calls" as const]: "",
+      })
+    ).toBeNull();
+  });
+});
+
+describe("createStandardBubble — stopReason notice", () => {
+  const renderWithStopReason = (
+    overrides: Partial<AgentWidgetMessage>,
+    widgetConfig?: Partial<AgentWidgetConfig>
+  ) =>
+    createStandardBubble(
+      makeMessage(overrides),
+      ({ text }) => text,
+      undefined,
+      undefined,
+      undefined,
+      { widgetConfig: widgetConfig as AgentWidgetConfig | undefined }
+    );
+
+  it("renders no notice for end_turn (natural completion)", () => {
+    const bubble = renderWithStopReason({
+      content: "All done.",
+      stopReason: "end_turn",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders no notice when stopReason is absent (backcompat)", () => {
+    const bubble = renderWithStopReason({ content: "Hello." });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders no notice for unknown reasons", () => {
+    const bubble = renderWithStopReason({
+      content: "Hello.",
+      stopReason: "unknown",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders the default notice for max_tool_calls", () => {
+    const bubble = renderWithStopReason({
+      content: "Used a tool.",
+      stopReason: "max_tool_calls",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice).not.toBeNull();
+    expect(notice?.getAttribute("data-stop-reason")).toBe("max_tool_calls");
+    expect(notice?.textContent).toBe(getDefaultStopReasonNoticeCopy("max_tool_calls"));
+  });
+
+  it("renders the default notice for length", () => {
+    const bubble = renderWithStopReason({
+      content: "Long answer cut off.",
+      stopReason: "length",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("length");
+    expect(notice?.textContent).toBe(getDefaultStopReasonNoticeCopy("length"));
+  });
+
+  it("renders the default notice for content_filter", () => {
+    const bubble = renderWithStopReason({
+      content: "Filtered.",
+      stopReason: "content_filter",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("content_filter");
+  });
+
+  it("renders the default notice for error", () => {
+    const bubble = renderWithStopReason({
+      content: "Provider blew up.",
+      stopReason: "error",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("error");
+  });
+
+  it("applies copy overrides from widgetConfig.copy.stopReasonNotice", () => {
+    const bubble = renderWithStopReason(
+      { content: "x", stopReason: "max_tool_calls" },
+      { copy: { stopReasonNotice: { ["max_tool_calls" as const]: "Custom copy." } } }
+    );
+    expect(bubble.querySelector(".persona-message-stop-reason")?.textContent).toBe(
+      "Custom copy."
+    );
+  });
+
+  it("hides the empty content div when content is empty + max_tool_calls", () => {
+    // Regression: the empty-bubble symptom the upstream Runtype fix targets.
+    // With no content and max_tool_calls, the notice carries the bubble alone;
+    // the empty content div must be hidden so we don't render whitespace
+    // above the notice.
+    const bubble = renderWithStopReason({
+      content: "",
+      stopReason: "max_tool_calls",
+    });
+    const contentDiv = bubble.querySelector(".persona-message-content") as HTMLElement | null;
+    expect(contentDiv).not.toBeNull();
+    expect(contentDiv!.style.display).toBe("none");
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice).not.toBeNull();
+    expect(notice?.getAttribute("data-stop-reason")).toBe("max_tool_calls");
+  });
+
+  it("does not render notice while message is still streaming", () => {
+    const bubble = renderWithStopReason({
+      content: "partial",
+      stopReason: "max_tool_calls",
+      streaming: true,
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("does not render notice on user messages", () => {
+    const bubble = renderWithStopReason({
+      role: "user",
+      content: "user msg",
+      // stopReason on a user message is nonsense, but guard against it
+      stopReason: "max_tool_calls",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+});

package/src/components/message-bubble.ts

@@ -7,10 +7,85 @@ import {
   AgentWidgetMessageActionsConfig,
   AgentWidgetMessageFeedback,
   LoadingIndicatorRenderContext,
-  ImageContentPart
+  ImageContentPart,
+  StopReasonKind
 } from "../types";
 import { createIconButton } from "../utils/buttons";
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "../utils/content";
+import {
+  applyStreamBuffer,
+  createSkeletonPlaceholder,
+  createStreamCaret,
+  resolveStreamAnimation,
+  resolveStreamAnimationPlugin,
+  wrapStreamAnimation,
+} from "../utils/stream-animation";
+
+/**
+ * Default copy for the inline notice rendered when a turn ends with a
+ * non-natural stop reason. Deployers override per-reason via
+ * `config.copy.stopReasonNotice`. Returns `null` for natural completions
+ * (`end_turn`) and uninformative reasons (`unknown`) — those never render
+ * an affordance.
+ */
+export const getDefaultStopReasonNoticeCopy = (
+  stopReason: StopReasonKind
+): string | null => {
+  switch (stopReason) {
+    case "max_tool_calls":
+      return "Stopped after calling a tool. Send a follow-up to continue.";
+    case "length":
+      return "Response cut off as max tokens reached. Ask for more to continue.";
+    case "content_filter":
+      return "The provider filtered this response.";
+    case "error":
+      return "Something went wrong generating this response.";
+    case "end_turn":
+    case "unknown":
+    default:
+      return null;
+  }
+};
+
+/**
+ * Resolve the notice text for a stop reason, applying user overrides on
+ * top of the built-in defaults. Returns `null` when the reason does not
+ * warrant a notice or when the resolved string is empty (deployers can
+ * suppress per-reason by setting an empty override).
+ */
+export const resolveStopReasonNoticeText = (
+  stopReason: StopReasonKind | undefined,
+  overrides?: Partial<Record<StopReasonKind, string>>
+): string | null => {
+  if (!stopReason) return null;
+  const fallback = getDefaultStopReasonNoticeCopy(stopReason);
+  // Reasons without a default (end_turn, unknown) never render — overrides
+  // for those keys are intentionally ignored.
+  if (fallback === null) return null;
+  const override = overrides?.[stopReason];
+  const text = override !== undefined ? override : fallback;
+  if (!text) return null;
+  return text;
+};
+
+/**
+ * Build the inline notice element rendered on assistant bubbles whose
+ * turn ended with `max_tool_calls`, `length`, `content_filter`, or `error`.
+ */
+const createStopReasonNotice = (
+  stopReason: StopReasonKind,
+  text: string
+): HTMLElement => {
+  const notice = createElement(
+    "div",
+    "persona-message-stop-reason persona-text-xs persona-mt-2 persona-italic"
+  );
+  notice.setAttribute("data-stop-reason", stopReason);
+  notice.setAttribute("role", "note");
+  notice.style.opacity = "0.75";
+  notice.textContent = text;
+  return notice;
+};
 
 /** Validate that an image src URL uses a safe scheme (blocks javascript: and SVG data URIs). */
 export const isSafeImageSrc = (src: string): boolean => {
@@ -507,24 +582,107 @@ export const createStandardBubble = (
     imageParts.length > 0 && messageContentText === IMAGE_ONLY_MESSAGE_FALLBACK_TEXT;
   const shouldHideTextUntilPreviewFails = isImageOnlyFallbackMessage;
 
+  const streamAnimation = resolveStreamAnimation(
+    options?.widgetConfig?.features?.streamAnimation
+  );
+  const streamPluginOverrides =
+    options?.widgetConfig?.features?.streamAnimation?.plugins;
+  const streamPlugin =
+    message.role === "assistant" && streamAnimation.type !== "none"
+      ? resolveStreamAnimationPlugin(streamAnimation.type, streamPluginOverrides)
+      : null;
+  // Stay in "streaming-animated" mode while the plugin reports in-flight
+  // work for this message — e.g. glyph-cycle's tick loops still walking
+  // through the tail after the last token arrived. Without this, the final
+  // non-animated render rips out the cycling spans mid-animation.
+  const pluginStillAnimating =
+    message.role === "assistant" &&
+    streamPlugin?.isAnimating?.(message) === true;
+  const streamAnimationActive =
+    message.role === "assistant" &&
+    streamPlugin !== null &&
+    (Boolean(message.streaming) || pluginStillAnimating);
+
+  if (streamAnimationActive && streamPlugin?.bubbleClass) {
+    bubble.classList.add(streamPlugin.bubbleClass);
+  }
+
   // Add message content
   const contentDiv = document.createElement("div");
   contentDiv.classList.add("persona-message-content");
+
+  if (streamAnimationActive && streamPlugin) {
+    if (streamPlugin.containerClass) {
+      contentDiv.classList.add(streamPlugin.containerClass);
+    }
+    contentDiv.style.setProperty("--persona-stream-step", `${streamAnimation.speed}ms`);
+    contentDiv.style.setProperty("--persona-stream-duration", `${streamAnimation.duration}ms`);
+  }
+
+  const bufferedContent = streamAnimationActive
+    ? applyStreamBuffer(
+        message.content ?? "",
+        streamAnimation.buffer,
+        streamPlugin,
+        message,
+        Boolean(message.streaming)
+      )
+    : (message.content ?? "");
+
   const transformedContent = transform({
-    text: message.content,
+    text: bufferedContent,
     message,
     streaming: Boolean(message.streaming),
     raw: message.rawContent
   });
+
+  let animatedContent = transformedContent;
+  if (streamAnimationActive && streamPlugin?.wrap === "char") {
+    animatedContent = wrapStreamAnimation(transformedContent, "char", message.id, {
+      skipTags: streamPlugin.skipTags,
+    });
+  } else if (streamAnimationActive && streamPlugin?.wrap === "word") {
+    animatedContent = wrapStreamAnimation(transformedContent, "word", message.id, {
+      skipTags: streamPlugin.skipTags,
+    });
+  }
+
   let textContentDiv: HTMLElement | null = null;
 
   if (shouldHideTextUntilPreviewFails) {
     textContentDiv = document.createElement("div");
-    textContentDiv.innerHTML = transformedContent;
+    textContentDiv.innerHTML = animatedContent;
     textContentDiv.style.display = "none";
     contentDiv.appendChild(textContentDiv);
   } else {
-    contentDiv.innerHTML = transformedContent;
+    contentDiv.innerHTML = animatedContent;
+  }
+
+  if (
+    streamAnimationActive &&
+    streamPlugin?.useCaret &&
+    !shouldHideTextUntilPreviewFails &&
+    messageContentText
+  ) {
+    const caret = createStreamCaret();
+    // Caret must sit on the same line as the final char. Markdown wraps text
+    // in block elements (<p>, <li>, <pre>), so appending to contentDiv would
+    // drop the caret onto a fresh line. Tuck it after the last char/word span,
+    // or fall back to the last block when no spans exist yet.
+    const spans = contentDiv.querySelectorAll(
+      ".persona-stream-char, .persona-stream-word"
+    );
+    const lastSpan = spans[spans.length - 1];
+    if (lastSpan?.parentNode) {
+      lastSpan.parentNode.insertBefore(caret, lastSpan.nextSibling);
+    } else {
+      const lastChild = contentDiv.lastElementChild;
+      if (lastChild) {
+        lastChild.appendChild(caret);
+      } else {
+        contentDiv.appendChild(caret);
+      }
+    }
   }
 
   // Add inline timestamp if configured
@@ -561,19 +719,56 @@ export const createStandardBubble = (
     bubble.appendChild(timestamp);
   }
 
-  // Add typing indicator if this is a streaming assistant message
+  // Resolve the stop-reason notice (if any). Only assistant messages can
+  // carry a stop reason worth surfacing.
+  const stopReasonNoticeText =
+    message.role === "assistant"
+      ? resolveStopReasonNoticeText(
+          message.stopReason,
+          options?.widgetConfig?.copy?.stopReasonNotice
+        )
+      : null;
+
+  // Add typing indicator (or skeleton placeholder) for streaming assistant
+  // messages. Check the buffered content — a plugin's `bufferContent` may
+  // hold back the first N chars (e.g. glyph-cycle waits for 50 chars), during
+  // which the bubble would otherwise appear empty.
+  //
+  // When the `"line"` buffer strategy is paired with the skeleton placeholder,
+  // the skeleton trails below any already-revealed content to hint that more
+  // lines are on the way. It disappears on stream completion.
   if (message.streaming && message.role === "assistant") {
-    if (!message.content || !message.content.trim()) {
-      // Use custom renderer if provided, otherwise default
-      const indicator = renderLoadingIndicatorWithFallback(
-        'inline',
-        options?.loadingIndicatorRenderer,
-        options?.widgetConfig
-      );
-      if (indicator) {
-        bubble.appendChild(indicator);
+    const hasVisibleContent = Boolean(bufferedContent && bufferedContent.trim());
+    const skeletonEnabled = streamAnimation.placeholder === "skeleton";
+    const trailSkeleton =
+      skeletonEnabled && streamAnimation.buffer === "line" && hasVisibleContent;
+    if (!hasVisibleContent) {
+      if (skeletonEnabled) {
+        bubble.appendChild(createSkeletonPlaceholder());
+      } else {
+        const indicator = renderLoadingIndicatorWithFallback(
+          'inline',
+          options?.loadingIndicatorRenderer,
+          options?.widgetConfig
+        );
+        if (indicator) {
+          bubble.appendChild(indicator);
+        }
       }
+    } else if (trailSkeleton) {
+      bubble.appendChild(createSkeletonPlaceholder());
+    }
+  }
+
+  // Append the stop-reason notice for non-natural completions. When the
+  // assistant produced no text (the `max_tool_calls` empty-bubble symptom),
+  // hide the empty content div so the notice carries the entire bubble
+  // instead of trailing under a blank space.
+  if (stopReasonNoticeText && message.stopReason && !message.streaming) {
+    if (!messageContentText) {
+      contentDiv.style.display = "none";
     }
+    bubble.appendChild(createStopReasonNotice(message.stopReason, stopReasonNoticeText));
   }
 
   // Add message actions for assistant messages (only when not streaming and has content)

package/src/components/messages.ts

@@ -4,6 +4,11 @@ import { MessageTransform, MessageActionCallbacks } from "./message-bubble";
 import { createStandardBubble } from "./message-bubble";
 import { createReasoningBubble } from "./reasoning-bubble";
 import { createToolBubble } from "./tool-bubble";
+import {
+  ensureAskUserQuestionSheet,
+  isAskUserQuestionMessage,
+  removeAskUserQuestionSheet,
+} from "./ask-user-question-bubble";
 
 export const renderMessages = (
   container: HTMLElement,
@@ -12,16 +17,29 @@ export const renderMessages = (
   showReasoning: boolean,
   showToolCalls: boolean,
   config?: AgentWidgetConfig,
-  actionCallbacks?: MessageActionCallbacks
+  actionCallbacks?: MessageActionCallbacks,
+  composerOverlay?: HTMLElement | null
 ) => {
   container.innerHTML = "";
   const fragment = createFragment();
 
+  // Track which ask_user_question tool-call ids are currently in the message
+  // list, so we can prune stale sheets from the overlay afterward.
+  const liveAskToolIds = new Set<string>();
+
   messages.forEach((message) => {
     let bubble: HTMLElement;
     if (message.variant === "reasoning" && message.reasoning) {
       if (!showReasoning) return;
       bubble = createReasoningBubble(message, config);
+    } else if (isAskUserQuestionMessage(message)) {
+      // No transcript bubble — the overlay sheet is the only question UI.
+      if (config?.features?.askUserQuestion?.enabled === false) return;
+      if (!message.agentMetadata?.askUserQuestionAnswered) {
+        if (message.toolCall?.id) liveAskToolIds.add(message.toolCall.id);
+        ensureAskUserQuestionSheet(message, config, composerOverlay ?? null);
+      }
+      return;
     } else if (message.variant === "tool" && message.toolCall) {
       if (!showToolCalls) return;
       bubble = createToolBubble(message, config);
@@ -45,6 +63,20 @@ export const renderMessages = (
 
   container.appendChild(fragment);
   container.scrollTop = container.scrollHeight;
+
+  // Clean up any orphaned ask_user_question sheets whose source message is no
+  // longer in the list (e.g. after clearChat or a message splice).
+  if (composerOverlay) {
+    const sheets = composerOverlay.querySelectorAll<HTMLElement>(
+      '[data-persona-ask-sheet-for]'
+    );
+    sheets.forEach((sheet) => {
+      const id = sheet.getAttribute('data-persona-ask-sheet-for');
+      if (id && !liveAskToolIds.has(id)) {
+        removeAskUserQuestionSheet(composerOverlay, id);
+      }
+    });
+  }
 };