@runtypelabs/persona 3.16.0 → 3.18.0

package/src/ui.ts

@@ -41,6 +41,11 @@ import {
   resolveFollowStateFromWheel
 } from "./utils/auto-follow";
 import { statusCopy, DEFAULT_OVERLAY_Z_INDEX, PORTALED_OVERLAY_Z_INDEX } from "./utils/constants";
+import {
+  detachAllPlugins,
+  ensurePluginActive,
+  resolveStreamAnimationPlugin,
+} from "./utils/stream-animation";
 import { syncOverlayHostStacking } from "./utils/overlay-host-stacking";
 import { acquireScrollLock } from "./utils/scroll-lock";
 import { isDockedMountMode, resolveDockConfig } from "./utils/dock";
@@ -54,6 +59,20 @@ import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } fr
 import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
+import {
+  buildStructuredAnswers,
+  ensureAskUserQuestionSheet,
+  getCurrentIndex,
+  getQuestionCount,
+  getSelectedLabels,
+  isAskUserQuestionMessage,
+  isGroupedSheet,
+  navigateToPage,
+  parseAskUserQuestionPayload,
+  readAnswersFromSheet,
+  removeAskUserQuestionSheet,
+  setCurrentAnswer,
+} from "./components/ask-user-question-bubble";
 import { formatElapsedMs } from "./utils/formatting";
 import { createApprovalBubble } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
@@ -323,6 +342,10 @@ type Controller = {
   upsertArtifact: (manual: PersonaArtifactManualUpsert) => PersonaArtifactRecord | null;
   selectArtifact: (id: string) => void;
   clearArtifacts: () => void;
+  /** Read current artifacts (useful on init to rebuild host-side tab state after hydration). */
+  getArtifacts: () => PersonaArtifactRecord[];
+  /** Read the currently selected artifact id (paired with `getArtifacts`). */
+  getSelectedArtifactId: () => string | null;
   /**
    * Focus the chat input. Returns true if focus succeeded, false if panel is closed
    * (launcher mode) or textarea is unavailable.
@@ -512,6 +535,13 @@ export const createAgentExperience = (
         if (processedState.messages?.length) {
           config = { ...config, initialMessages: processedState.messages };
         }
+        if (processedState.artifacts?.length) {
+          config = {
+            ...config,
+            initialArtifacts: processedState.artifacts,
+            initialSelectedArtifactId: processedState.selectedArtifactId ?? null
+          };
+        }
       }
     } catch (error) {
       if (typeof console !== "undefined") {
@@ -701,6 +731,7 @@ export const createAgentExperience = (
     leftActions,
     rightActions
   } = panelElements;
+  let setSendButtonMode = panelElements.setSendButtonMode;
 
   // Use mutable references for mic button so we can update them dynamically
   let micButton: HTMLButtonElement | null = panelElements.micButton;
@@ -1402,6 +1433,385 @@ export const createAgentExperience = (
     target.click();
   });
 
+  // --- ask_user_question sheet interaction ---
+  // Event delegation for the answer-pill sheet that mounts in the composer
+  // overlay. Handles pill pick (single), multi-select toggle + submit, free-
+  // text pill expansion + submit, and dismissal. Selection becomes a regular
+  // user message via session.sendMessage so the agent resumes on the next turn.
+  const askUserOverlay = panelElements.composerOverlay;
+
+  const submitAskUserAnswer = (
+    sheet: HTMLElement,
+    text: string,
+    meta: {
+      source: "pick" | "multi" | "free-text" | "submit-all";
+      values?: string[];
+      structured?: Record<string, string | string[]>;
+    }
+  ): void => {
+    const trimmed = text.trim();
+    if (!trimmed || !sessionRef.current) return;
+    const toolCallId = sheet.getAttribute("data-tool-call-id") ?? "";
+    const isFreeText = meta.source === "free-text";
+
+    // Dispatch before removing the sheet so listeners can still query DOM state.
+    mount.dispatchEvent(
+      new CustomEvent("persona:askUserQuestion:answered", {
+        detail: {
+          toolUseId: toolCallId,
+          answer: trimmed,
+          answers: meta.structured,
+          values: meta.values ?? (meta.source === "multi" ? trimmed.split(", ") : [trimmed]),
+          isFreeText,
+          source: meta.source,
+        },
+        bubbles: true,
+        composed: true,
+      })
+    );
+
+    removeAskUserQuestionSheet(askUserOverlay, toolCallId);
+
+    // Branch: LOCAL-tool pause (step_await) resumes via /resume with structured
+    // toolOutputs; legacy path sends as a plain user message.
+    const sourceMessage = sessionRef.current
+      .getMessages()
+      .find((m) => m.toolCall?.id === toolCallId);
+    if (sourceMessage?.agentMetadata?.awaitingLocalTool) {
+      sessionRef.current.resolveAskUserQuestion(sourceMessage, meta.structured ?? trimmed);
+    } else {
+      sessionRef.current.sendMessage(trimmed);
+    }
+  };
+
+  /**
+   * Persist in-progress grouped-question answers + page index back to the
+   * source message so a refresh restores the user's spot.
+   */
+  const persistGroupedProgress = (sheet: HTMLElement): void => {
+    const session = sessionRef.current;
+    if (!session) return;
+    const toolCallId = sheet.getAttribute("data-tool-call-id") ?? "";
+    const sourceMessage = session.getMessages().find((m) => m.toolCall?.id === toolCallId);
+    if (!sourceMessage) return;
+    session.persistAskUserQuestionProgress(sourceMessage, {
+      answers: buildStructuredAnswers(sheet, sourceMessage),
+      currentIndex: getCurrentIndex(sheet),
+    });
+  };
+
+  /**
+   * Build a one-line summary string for the legacy `answer` field on the
+   * answered event when submit-all fires from a grouped sheet.
+   */
+  const stringifyStructured = (answers: Record<string, string | string[]>): string => {
+    return Object.entries(answers)
+      .map(([q, v]) => `${q}: ${Array.isArray(v) ? v.join(", ") : v}`)
+      .join(" | ");
+  };
+
+  /**
+   * If `groupedAutoAdvance` is enabled (default) and we're not on the final
+   * page, advance one step. The final page never auto-submits — users always
+   * confirm with an explicit Submit-all click so they can review.
+   */
+  const maybeAutoAdvance = (sheet: HTMLElement): void => {
+    if (config.features?.askUserQuestion?.groupedAutoAdvance === false) return;
+    const idx = getCurrentIndex(sheet);
+    const count = getQuestionCount(sheet);
+    if (idx >= count - 1) return;
+    const sourceMessage = sessionRef.current
+      ?.getMessages()
+      .find((m) => m.toolCall?.id === sheet.getAttribute("data-tool-call-id"));
+    if (!sourceMessage) return;
+    navigateToPage(sheet, sourceMessage, config, idx + 1);
+    persistGroupedProgress(sheet);
+  };
+
+  askUserOverlay.addEventListener("click", (event) => {
+    const target = event.target as HTMLElement;
+    const trigger = target.closest<HTMLElement>("[data-ask-user-action]");
+    if (!trigger) return;
+    const sheet = trigger.closest<HTMLElement>("[data-persona-ask-sheet-for]");
+    if (!sheet) return;
+
+    const action = trigger.getAttribute("data-ask-user-action");
+    event.preventDefault();
+    event.stopPropagation();
+
+    if (action === "dismiss") {
+      const toolCallId = sheet.getAttribute("data-tool-call-id") ?? "";
+      mount.dispatchEvent(
+        new CustomEvent("persona:askUserQuestion:dismissed", {
+          detail: { toolUseId: toolCallId },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      removeAskUserQuestionSheet(askUserOverlay, toolCallId);
+
+      // Best-effort: if this sheet corresponds to a LOCAL-awaiting tool,
+      // unblock the paused execution with a sentinel answer so the server
+      // doesn't sit in waiting_for_local forever. Fire-and-forget — errors
+      // are surfaced to the onError callback. Flip the answered flag first
+      // so a racing render pass doesn't re-mount the sheet mid-dismissal.
+      const sourceMessage = sessionRef.current
+        ?.getMessages()
+        .find((m) => m.toolCall?.id === toolCallId);
+      if (sourceMessage?.agentMetadata?.awaitingLocalTool) {
+        sessionRef.current?.markAskUserQuestionResolved(sourceMessage);
+        sessionRef.current?.resolveAskUserQuestion(sourceMessage, "(dismissed)");
+      }
+      return;
+    }
+
+    if (action === "pick") {
+      const label = trigger.getAttribute("data-option-label");
+      if (!label) return;
+      const multiSelect = sheet.getAttribute("data-multi-select") === "true";
+      const grouped = isGroupedSheet(sheet);
+
+      if (grouped && multiSelect) {
+        const stored = readAnswersFromSheet(sheet)[getCurrentIndex(sheet)];
+        const set = new Set<string>(Array.isArray(stored) ? stored : []);
+        if (set.has(label)) set.delete(label);
+        else set.add(label);
+        setCurrentAnswer(sheet, Array.from(set));
+        persistGroupedProgress(sheet);
+        return;
+      }
+
+      if (grouped) {
+        setCurrentAnswer(sheet, label);
+        persistGroupedProgress(sheet);
+        maybeAutoAdvance(sheet);
+        return;
+      }
+
+      // 1-question modes — preserve original UX.
+      if (multiSelect) {
+        const pressed = trigger.getAttribute("aria-pressed") === "true";
+        trigger.setAttribute("aria-pressed", pressed ? "false" : "true");
+        trigger.classList.toggle("persona-ask-pill-selected", !pressed);
+        const submitBtn = sheet.querySelector<HTMLButtonElement>(
+          '[data-ask-user-action="submit-multi"]'
+        );
+        if (submitBtn) {
+          submitBtn.disabled = getSelectedLabels(sheet).length === 0;
+        }
+        return;
+      }
+      submitAskUserAnswer(sheet, label, { source: "pick", values: [label] });
+      return;
+    }
+
+    if (action === "submit-multi") {
+      const labels = getSelectedLabels(sheet);
+      if (labels.length === 0) return;
+      submitAskUserAnswer(sheet, labels.join(", "), {
+        source: "multi",
+        values: labels,
+      });
+      return;
+    }
+
+    if (action === "open-free-text") {
+      const row = sheet.querySelector<HTMLElement>('[data-ask-free-text-row="true"]');
+      if (row) {
+        row.classList.remove("persona-hidden");
+        const input = row.querySelector<HTMLInputElement>('[data-ask-free-text-input="true"]');
+        input?.focus();
+      }
+      return;
+    }
+
+    if (action === "focus-free-text") {
+      // Rows-layout Other row: input lives inside the row container itself.
+      // Native click on the input already focuses it; this branch handles
+      // clicks on the badge or row chrome AND digit-shortcut activations.
+      const input = sheet.querySelector<HTMLInputElement>('[data-ask-free-text-input="true"]');
+      input?.focus();
+      return;
+    }
+
+    if (action === "submit-free-text") {
+      const input = sheet.querySelector<HTMLInputElement>('[data-ask-free-text-input="true"]');
+      const text = input?.value ?? "";
+      if (!text.trim()) return;
+      if (isGroupedSheet(sheet)) {
+        setCurrentAnswer(sheet, text.trim());
+        persistGroupedProgress(sheet);
+        maybeAutoAdvance(sheet);
+        return;
+      }
+      submitAskUserAnswer(sheet, text, { source: "free-text" });
+      return;
+    }
+
+    if (action === "next" || action === "back") {
+      if (!sessionRef.current) return;
+      const toolCallId = sheet.getAttribute("data-tool-call-id") ?? "";
+      const sourceMessage = sessionRef.current
+        .getMessages()
+        .find((m) => m.toolCall?.id === toolCallId);
+      if (!sourceMessage) return;
+      // Flush any unsubmitted free-text input as the current answer.
+      const freeInput = sheet.querySelector<HTMLInputElement>('[data-ask-free-text-input="true"]');
+      const pending = freeInput?.value?.trim() ?? "";
+      if (pending) {
+        const stored = readAnswersFromSheet(sheet)[getCurrentIndex(sheet)];
+        if (typeof stored !== "string" || stored !== pending) {
+          setCurrentAnswer(sheet, pending);
+        }
+      }
+      const direction = action === "next" ? 1 : -1;
+      const nextIdx = getCurrentIndex(sheet) + direction;
+      navigateToPage(sheet, sourceMessage, config, nextIdx);
+      persistGroupedProgress(sheet);
+      return;
+    }
+
+    if (action === "submit-all") {
+      if (!sessionRef.current) return;
+      const toolCallId = sheet.getAttribute("data-tool-call-id") ?? "";
+      const sourceMessage = sessionRef.current
+        .getMessages()
+        .find((m) => m.toolCall?.id === toolCallId);
+      if (!sourceMessage) return;
+      // Flush any pending free-text on the final page first.
+      const freeInput = sheet.querySelector<HTMLInputElement>('[data-ask-free-text-input="true"]');
+      const pending = freeInput?.value?.trim() ?? "";
+      if (pending) setCurrentAnswer(sheet, pending);
+
+      const structured = buildStructuredAnswers(sheet, sourceMessage);
+      // Persist final answers to message metadata BEFORE resolving so the
+      // answered-state review card (which reads `agentMetadata
+      // .askUserQuestionAnswers`) shows the user's actual picks instead of
+      // "(skipped)" placeholders. Without this, any answer set only via the
+      // pending-flush above (or via paths that bypassed the per-pick persist
+      // hook) would be missing from the transcript review even though it
+      // landed in the structured payload sent to the agent.
+      sessionRef.current.persistAskUserQuestionProgress(sourceMessage, {
+        answers: structured,
+        currentIndex: getCurrentIndex(sheet),
+      });
+      const summary = stringifyStructured(structured);
+      submitAskUserAnswer(sheet, summary || "(submitted)", {
+        source: "submit-all",
+        structured,
+      });
+      return;
+    }
+
+    if (action === "skip") {
+      if (!sessionRef.current) return;
+      const toolCallId = sheet.getAttribute("data-tool-call-id") ?? "";
+      const sourceMessage = sessionRef.current
+        .getMessages()
+        .find((m) => m.toolCall?.id === toolCallId);
+      if (!sourceMessage) return;
+
+      const grouped = isGroupedSheet(sheet);
+      const idx = getCurrentIndex(sheet);
+      const count = getQuestionCount(sheet);
+      const isFinal = idx >= count - 1;
+
+      // Single-question payloads behave like dismiss.
+      if (!grouped) {
+        mount.dispatchEvent(
+          new CustomEvent("persona:askUserQuestion:dismissed", {
+            detail: { toolUseId: toolCallId },
+            bubbles: true,
+            composed: true,
+          })
+        );
+        removeAskUserQuestionSheet(askUserOverlay, toolCallId);
+        if (sourceMessage.agentMetadata?.awaitingLocalTool) {
+          sessionRef.current.markAskUserQuestionResolved(sourceMessage);
+          sessionRef.current.resolveAskUserQuestion(sourceMessage, "(dismissed)");
+        }
+        return;
+      }
+
+      // Drop the current question's answer (if any) so it's absent from the
+      // resolved Record. setCurrentAnswer with an empty string deletes the
+      // index from the in-memory map.
+      setCurrentAnswer(sheet, "");
+      // Also clear any unsubmitted free-text on this page.
+      const freeInput = sheet.querySelector<HTMLInputElement>('[data-ask-free-text-input="true"]');
+      if (freeInput) freeInput.value = "";
+
+      if (isFinal) {
+        // Submit with whatever has been recorded so far.
+        const structured = buildStructuredAnswers(sheet, sourceMessage);
+        const summary = stringifyStructured(structured);
+        submitAskUserAnswer(sheet, summary || "(skipped)", {
+          source: "submit-all",
+          structured,
+        });
+        return;
+      }
+
+      // Intermediate page: advance one step without recording.
+      navigateToPage(sheet, sourceMessage, config, idx + 1);
+      persistGroupedProgress(sheet);
+      return;
+    }
+  });
+
+  // Enter on the free-text input → submit. Stays on the overlay because the
+  // event target IS the input, which lives inside the overlay subtree.
+  askUserOverlay.addEventListener("keydown", (event) => {
+    if (event.key !== "Enter") return;
+    const target = event.target as HTMLElement;
+    const input = target as HTMLInputElement;
+    if (!input.matches?.('[data-ask-free-text-input="true"]')) return;
+    const sheet = input.closest<HTMLElement>("[data-persona-ask-sheet-for]");
+    if (!sheet) return;
+    event.preventDefault();
+    const text = input.value;
+    if (!text.trim()) return;
+    if (isGroupedSheet(sheet)) {
+      setCurrentAnswer(sheet, text.trim());
+      persistGroupedProgress(sheet);
+      maybeAutoAdvance(sheet);
+      return;
+    }
+    submitAskUserAnswer(sheet, text, { source: "free-text" });
+  });
+
+  // Digit 1–9 → pick option N on the current rows-layout single-select page.
+  // Listens on `document` so the shortcut fires regardless of where focus
+  // currently sits (host page body, panel chrome, anywhere). The handler
+  // gates strictly: only fires when an active sheet is mounted in our
+  // overlay, and bails when focus is on any input/textarea/contenteditable
+  // (covers the free-text input, the chat composer, and any host-page input).
+  const handleAskUserDigitKey = (event: KeyboardEvent): void => {
+    if (!/^[1-9]$/.test(event.key)) return;
+    if (event.metaKey || event.ctrlKey || event.altKey) return;
+    const target = event.target as HTMLElement | null;
+    if (
+      target?.tagName === "INPUT" ||
+      target?.tagName === "TEXTAREA" ||
+      target?.isContentEditable
+    ) {
+      return;
+    }
+    const sheet = askUserOverlay.querySelector<HTMLElement>("[data-persona-ask-sheet-for]");
+    if (!sheet) return;
+    if (sheet.getAttribute("data-ask-layout") !== "rows") return;
+    if (sheet.getAttribute("data-multi-select") === "true") return;
+    const n = Number(event.key);
+    const pills = sheet.querySelectorAll<HTMLElement>(
+      '[data-ask-pill-list="true"] [data-ask-user-action="pick"], [data-ask-pill-list="true"] [data-ask-user-action="focus-free-text"]'
+    );
+    const target_pill = pills[n - 1];
+    if (!target_pill) return;
+    event.preventDefault();
+    target_pill.click();
+  };
+  document.addEventListener("keydown", handleAskUserDigitKey);
+
   let artifactSplitRoot: HTMLElement | null = null;
   let artifactResizeHandle: HTMLElement | null = null;
   let artifactResizeUnbind: (() => void) | null = null;
@@ -1671,6 +2081,16 @@ export const createAgentExperience = (
     const panelShadow = resolvePanelChrome(panelPartial?.shadow, defaultPanelShadow);
     const panelBorderRadius = resolvePanelChrome(panelPartial?.borderRadius, defaultPanelBorderRadius);
 
+    // Clearing body.style.cssText below wipes the inline `flex: 1 1 0%` /
+    // `min-height: 0` / `overflow-y: auto` that make the messages area a
+    // scroll container. Between the reset and the mode-specific reapply,
+    // the body's clientHeight == scrollHeight momentarily, so the browser
+    // clamps scrollTop to 0 — and a synchronous restore at the end of this
+    // function runs before layout has reflowed, so the write is also
+    // clamped. Defer the restore to the next frame, once the reapplied
+    // styles have produced a scrollable container again.
+    const prevBodyScrollTop = body.scrollTop;
+
     // Reset all inline styles first to handle mode toggling
     // This ensures styles don't persist when switching between modes
     mount.style.cssText = '';
@@ -1679,6 +2099,18 @@ export const createAgentExperience = (
     container.style.cssText = '';
     body.style.cssText = '';
     footer.style.cssText = '';
+
+    const restoreBodyScrollTop = (): void => {
+      if (prevBodyScrollTop <= 0) return;
+      const ownerWindow = body.ownerDocument.defaultView ?? window;
+      ownerWindow.requestAnimationFrame(() => {
+        if (body.scrollTop === prevBodyScrollTop) return;
+        // If scrollHeight collapsed (content actually shrank), don't fight it
+        const maxScrollTop = body.scrollHeight - body.clientHeight;
+        if (maxScrollTop <= 0) return;
+        body.scrollTop = Math.min(prevBodyScrollTop, maxScrollTop);
+      });
+    };
     
     // Mobile fullscreen: fill entire viewport with no radius/shadow/margins
     if (shouldGoFullscreen) {
@@ -1742,6 +2174,7 @@ export const createAgentExperience = (
       footer.style.flexShrink = '0';
 
       wasMobileFullscreen = true;
+      restoreBodyScrollTop();
       return; // Skip remaining mode logic
     }
 
@@ -1926,6 +2359,8 @@ export const createAgentExperience = (
         : '';
       wrapper.style.cssText += maxHeightStyles + paddingStyles + zIndexStyles;
     }
+
+    restoreBodyScrollTop();
   };
   applyFullHeightStyles();
   // Apply theme variables after applyFullHeightStyles since it resets mount.style.cssText
@@ -1934,6 +2369,10 @@ export const createAgentExperience = (
   applyArtifactPaneAppearance(mount, config);
 
   const destroyCallbacks: Array<() => void> = [];
+  // Clean up the document-level digit-key shortcut listener registered earlier.
+  destroyCallbacks.push(() => {
+    document.removeEventListener("keydown", handleAskUserDigitKey);
+  });
 
   let teardownHostStacking: (() => void) | null = null;
   let releaseScrollLock: (() => void) | null = null;
@@ -2003,11 +2442,32 @@ export const createAgentExperience = (
     }
   });
 
+  // Activate the stream-animation plugin for this widget instance. Plugins
+  // with `styles` inject their CSS into the widget root once; plugins with
+  // `onAttach` (e.g., glyph-cycle's MutationObserver for real glyph tick
+  // loops) can register long-lived DOM listeners here. Detach callbacks are
+  // deferred to widget destroy.
+  const streamAnimationConfig = config.features?.streamAnimation;
+  if (streamAnimationConfig?.type && streamAnimationConfig.type !== "none") {
+    const plugin = resolveStreamAnimationPlugin(
+      streamAnimationConfig.type,
+      streamAnimationConfig.plugins
+    );
+    if (plugin) {
+      ensurePluginActive(plugin, mount);
+      destroyCallbacks.push(() => detachAllPlugins(mount));
+    }
+  }
+
   const suggestionsManager = createSuggestions(suggestions);
   let closeHandler: (() => void) | null = null;
   let session: AgentWidgetSession;
   let isStreaming = false;
   const messageCache = createMessageCache();
+  // Tracks the last fingerprint we rendered a plugin-rendered ask_user_question
+  // bubble for, per message id. Lets us skip unnecessary rebuilds across
+  // re-renders so user state inside the plugin (typed text, focus) survives.
+  const lastAskBubbleFingerprint = new Map<string, string>();
   let configVersion = 0;
   const autoFollow = createFollowStateController();
   let lastScrollTop = 0;
@@ -2091,7 +2551,9 @@ export const createAgentExperience = (
 
     const payload = {
       messages,
-      metadata: persistentMetadata
+      metadata: persistentMetadata,
+      artifacts: lastArtifactsState.artifacts,
+      selectedArtifactId: lastArtifactsState.selectedId
     };
     try {
       const result = storageAdapter.save(payload);
@@ -2350,15 +2812,64 @@ export const createAgentExperience = (
 
     // Track active message IDs for cache pruning
     const activeMessageIds = new Set<string>();
+    // Track ask_user_question tool-call ids whose bubbles were rendered this
+    // pass — used to prune stale sheets from the composer overlay afterward.
+    const liveAskToolIds = new Set<string>();
+
+    // Plugins that render `ask_user_question` typically attach DOM listeners
+    // directly to their buttons. The wrapper cache uses `cloneNode(true)` and
+    // idiomorph inserts new nodes via `document.importNode` — both strip
+    // listeners. For plugin-handled ask messages we therefore append an empty
+    // stub during the morph pass and hydrate the live plugin bubble into the
+    // morphed wrapper afterward (see post-morph loop below). The stub carries
+    // `data-preserve-runtime` so subsequent passes leave the live wrapper
+    // (with its listener-bearing bubble) untouched.
+    const hasAskPlugin = plugins.some((p) => p.renderAskUserQuestion);
+    type AskPluginHydrate = {
+      messageId: string;
+      fingerprint: string;
+      bubble: HTMLElement | null;
+    };
+    const askPluginHydrate: AskPluginHydrate[] = [];
 
     messages.forEach((message) => {
       activeMessageIds.add(message.id);
 
-      // Fingerprint cache: skip re-rendering unchanged messages
-      const fingerprint = computeMessageFingerprint(message, configVersion);
-      const cachedWrapper = getCachedWrapper(messageCache, message.id, fingerprint);
+      const askWithPlugin = hasAskPlugin && isAskUserQuestionMessage(message);
+
+      // Fingerprint cache: skip re-rendering unchanged messages. Append the
+      // ask-user-question answered/answers state so flipping `askUserQuestionAnswered`
+      // (or accumulating answers) busts both the wrapper cache and the plugin's
+      // `lastAskBubbleFingerprint` check, forcing a re-render of the review UX.
+      const askMeta = isAskUserQuestionMessage(message)
+        ? `:${message.agentMetadata?.askUserQuestionAnswered ? "a" : "u"}:${
+            message.agentMetadata?.askUserQuestionAnswers
+              ? Object.keys(message.agentMetadata.askUserQuestionAnswers).length
+              : 0
+          }`
+        : "";
+      const fingerprint = computeMessageFingerprint(message, configVersion) + askMeta;
+      const cachedWrapper = askWithPlugin
+        ? null
+        : getCachedWrapper(messageCache, message.id, fingerprint);
       if (cachedWrapper) {
         tempContainer.appendChild(cachedWrapper.cloneNode(true));
+        // Keep the overlay sheet alive only while the server is actively
+        // waiting on the user (awaitingLocalTool === true). Before step_await
+        // fires, or after the answer resumes the flow, omit from
+        // liveAskToolIds so the prune loop below removes any stale DOM sheet.
+        // Guards against lingering skeleton sheets from tool_start events
+        // that never get a matching step_await (e.g. LLM-hallucinated trailing
+        // ask_user_question calls at end-of-turn).
+        if (
+          isAskUserQuestionMessage(message) &&
+          message.toolCall?.id &&
+          message.agentMetadata?.awaitingLocalTool === true &&
+          !message.agentMetadata?.askUserQuestionAnswered
+        ) {
+          liveAskToolIds.add(message.toolCall.id);
+          ensureAskUserQuestionSheet(message, config, panelElements.composerOverlay);
+        }
         return;
       }
 
@@ -2384,7 +2895,111 @@ export const createAgentExperience = (
       // Get message layout config
       const messageLayoutConfig = config.layout?.messages;
 
-      if (matchingPlugin) {
+      // ask_user_question has two rendering modes while waiting for an answer:
+      //   1. Plugin `renderAskUserQuestion` — returns an inline transcript
+      //      element with its own UI; the composer-overlay sheet is suppressed.
+      //   2. Built-in composer-overlay answer-pill sheet — no transcript stub.
+      // Plugins win when they return a non-null element; otherwise fall
+      // through to the built-in overlay.
+      //
+      // Once answered, the original tool message is suppressed entirely from
+      // the transcript. `session.resolveAskUserQuestion` injects one assistant
+      // bubble per question and one user bubble per answer (skipped questions
+      // become an italic `*Skipped*` user bubble), so the transcript reads
+      // like a normal Q→A conversation. Plugins do not render the answered
+      // state.
+      if (
+        isAskUserQuestionMessage(message) &&
+        message.agentMetadata?.askUserQuestionAnswered === true
+      ) {
+        // Drop any previously-mounted plugin bubble so the morph pass
+        // removes the now-stale interactive sheet.
+        lastAskBubbleFingerprint.delete(message.id);
+        const existing = container.querySelector<HTMLElement>(`#wrapper-${message.id}`);
+        existing?.removeAttribute("data-preserve-runtime");
+        return;
+      }
+
+      if (
+        isAskUserQuestionMessage(message) &&
+        config.features?.askUserQuestion?.enabled !== false
+      ) {
+        const askPlugin = plugins.find((p) => typeof p.renderAskUserQuestion === "function");
+        if (askPlugin && sessionRef.current) {
+          const lastFp = lastAskBubbleFingerprint.get(message.id);
+          // Whether to actually call the plugin renderer this pass. We do it
+          // on first sight of this message, or when its fingerprint changed
+          // (e.g. payload streamed in more options). Otherwise we rely on the
+          // already-mounted bubble in `container`.
+          const needsRebuild = lastFp !== fingerprint;
+
+          let pluginBubble: HTMLElement | null = null;
+          if (needsRebuild) {
+            const { payload, complete } = parseAskUserQuestionPayload(message);
+            const messageId = message.id;
+            const liveMessage = (): AgentWidgetMessage | undefined =>
+              sessionRef.current?.getMessages().find((m) => m.id === messageId);
+            pluginBubble = askPlugin.renderAskUserQuestion!({
+              message,
+              payload,
+              complete,
+              resolve: (answer) => {
+                const live = liveMessage();
+                if (live) sessionRef.current?.resolveAskUserQuestion(live, answer);
+              },
+              dismiss: () => {
+                const live = liveMessage();
+                if (live?.agentMetadata?.awaitingLocalTool) {
+                  sessionRef.current?.markAskUserQuestionResolved(live);
+                  sessionRef.current?.resolveAskUserQuestion(live, "(dismissed)");
+                }
+              },
+              config,
+            });
+          }
+
+          // If the plugin opted out (returned null on a fresh build) AND we
+          // have no previously-mounted bubble for this message, fall back to
+          // the built-in overlay sheet. If we already have a mounted bubble
+          // and the plugin didn't run this pass (cached), keep using it.
+          const previouslyMounted = lastFp != null;
+          if (needsRebuild && pluginBubble === null && !previouslyMounted) {
+            if (
+              message.agentMetadata?.awaitingLocalTool === true &&
+              !message.agentMetadata?.askUserQuestionAnswered
+            ) {
+              liveAskToolIds.add(message.toolCall!.id);
+              ensureAskUserQuestionSheet(message, config, panelElements.composerOverlay);
+            }
+            return;
+          }
+
+          // Append a stub wrapper for the morph pass; hydrate the real bubble
+          // into it post-morph so its event listeners survive.
+          const stub = document.createElement("div");
+          stub.className = "persona-flex";
+          stub.id = `wrapper-${message.id}`;
+          stub.setAttribute("data-wrapper-id", message.id);
+          stub.setAttribute("data-ask-plugin-stub", "true");
+          stub.setAttribute("data-preserve-runtime", "true");
+          tempContainer.appendChild(stub);
+          askPluginHydrate.push({
+            messageId: message.id,
+            fingerprint,
+            bubble: pluginBubble,
+          });
+          return;
+        } else {
+          if (
+            message.agentMetadata?.awaitingLocalTool === true &&
+            !message.agentMetadata?.askUserQuestionAnswered
+          ) {
+            liveAskToolIds.add(message.toolCall!.id);
+            ensureAskUserQuestionSheet(message, config, panelElements.composerOverlay);
+          }
+          return;
+        }
+      } else if (matchingPlugin) {
         if (message.variant === "reasoning" && message.reasoning && matchingPlugin.renderReasoning) {
           if (!showReasoning) return;
           bubble = matchingPlugin.renderReasoning({
@@ -2562,6 +3177,20 @@ export const createAgentExperience = (
       tempContainer.appendChild(wrapper);
     });
 
+    // Prune any ask_user_question sheets whose source message is no longer in
+    // the message list (e.g. after clearChat or a splice).
+    if (panelElements.composerOverlay) {
+      const sheets = panelElements.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(panelElements.composerOverlay, id);
+        }
+      });
+    }
+
     if (config.features?.toolCallDisplay?.grouped) {
       const toolGroups: AgentWidgetMessage[][] = [];
       let currentGroup: AgentWidgetMessage[] = [];
@@ -2791,6 +3420,35 @@ export const createAgentExperience = (
 
     // Use idiomorph to morph the container contents
     morphMessages(container, tempContainer);
+
+    // Hydrate plugin-rendered ask-question bubbles into their stub wrappers.
+    // Idiomorph imports new nodes via `document.importNode`, which strips
+    // listeners — so we built only an empty stub during morph and now inject
+    // the real, listener-bearing bubble directly into the live DOM.
+    if (askPluginHydrate.length > 0) {
+      for (const { messageId, fingerprint, bubble } of askPluginHydrate) {
+        const wrapper = container.querySelector(`#wrapper-${messageId}`);
+        if (!wrapper) continue;
+        if (bubble === null) {
+          // No fresh bubble built this pass — either the plugin opted out
+          // and a previously-mounted bubble already lives here (preserved by
+          // `data-preserve-runtime`), or we skipped the rebuild because the
+          // fingerprint matched. Either way, leave the live wrapper alone.
+          continue;
+        }
+        wrapper.replaceChildren(bubble);
+        wrapper.setAttribute("data-bubble-fp", fingerprint);
+        lastAskBubbleFingerprint.set(messageId, fingerprint);
+      }
+    }
+
+    // Drop fingerprints for messages that are no longer present so a future
+    // re-appearance triggers a fresh plugin render.
+    if (lastAskBubbleFingerprint.size > 0) {
+      for (const id of lastAskBubbleFingerprint.keys()) {
+        if (!activeMessageIds.has(id)) lastAskBubbleFingerprint.delete(id);
+      }
+    }
   };
 
   // Alias for clarity - the implementation handles flicker prevention via typing indicator logic
@@ -2921,9 +3579,10 @@ export const createAgentExperience = (
   };
 
   const setComposerDisabled = (disabled: boolean) => {
-    // Keep textarea always enabled so users can type while streaming
-    // Only disable submit controls to prevent sending during streaming
-    sendButton.disabled = disabled;
+    // The send button stays enabled while streaming — it doubles as a stop
+    // button. Ancillary controls (mic, suggestions, opt-in targets) still
+    // disable so the user can't race a send against an in-flight stream.
+    setSendButtonMode(disabled ? "stop" : "send");
     if (micButton) {
       micButton.disabled = disabled;
     }
@@ -2974,9 +3633,10 @@ export const createAgentExperience = (
       }
     }
 
-    // Only update send button text if NOT using icon mode
+    // Only update send button text if NOT using icon mode. Skip while
+    // streaming so we don't stomp on the "Stop" label.
     const useIcon = config.sendButton?.useIcon ?? false;
-    if (!useIcon) {
+    if (!useIcon && !session?.isStreaming()) {
       sendButton.textContent = config.copy?.sendButtonLabel ?? "Send";
     }
 
@@ -3115,6 +3775,7 @@ export const createAgentExperience = (
     onArtifactsState(state) {
       lastArtifactsState = state;
       syncArtifactPane();
+      persistState();
     }
   });
 
@@ -3167,6 +3828,12 @@ export const createAgentExperience = (
         if (state.messages?.length) {
           session.hydrateMessages(state.messages);
         }
+        if (state.artifacts?.length) {
+          session.hydrateArtifacts(
+            state.artifacts,
+            state.selectedArtifactId ?? null
+          );
+        }
       })
       .catch((error) => {
         if (typeof console !== "undefined") {
@@ -3178,6 +3845,15 @@ export const createAgentExperience = (
 
   const handleSubmit = (event: Event) => {
     event.preventDefault();
+
+    // While a response is streaming, the submit button acts as a stop button.
+    // Abort the in-flight stream and leave textarea contents / attachments
+    // intact so the user can edit and resend without retyping.
+    if (session.isStreaming()) {
+      session.cancel();
+      return;
+    }
+
     const value = textarea.value.trim();
     const hasAttachments = attachmentManager?.hasAttachments() ?? false;
 
@@ -3914,16 +4590,26 @@ export const createAgentExperience = (
   }
 
   lastScrollTop = body.scrollTop;
+  let lastScrollHeight = body.scrollHeight;
 
   const handleScroll = () => {
     const scrollTop = body.scrollTop;
+    // When content mutates (e.g. stream-animation plugins re-rendering text),
+    // scrollHeight can shrink and force the browser to clamp scrollTop downward.
+    // That emits a scroll event with a negative delta that would otherwise be
+    // misread as the user scrolling up, pausing auto-follow and flashing the
+    // scroll-to-bottom button. Treat those as non-user events.
+    const currentScrollHeight = body.scrollHeight;
+    const scrollHeightShrank = currentScrollHeight < lastScrollHeight;
+    lastScrollHeight = currentScrollHeight;
+
     const { action, nextLastScrollTop } = resolveFollowStateFromScroll({
       following: autoFollow.isFollowing(),
       currentScrollTop: scrollTop,
       lastScrollTop,
       nearBottom: isElementNearBottom(body, BOTTOM_THRESHOLD),
       userScrollThreshold: USER_SCROLL_THRESHOLD,
-      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll,
+      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll || scrollHeightShrank,
       pauseOnUpwardScroll: true,
       pauseWhenAwayFromBottom: false,
       resumeRequiresDownwardScroll: true
@@ -3999,6 +4685,9 @@ export const createAgentExperience = (
       messageCache.clear();
       resumeAutoScroll();
 
+      // Drop any open ask_user_question sheets — their source messages are gone.
+      removeAskUserQuestionSheet(panelElements.composerOverlay);
+
       // Always clear the default localStorage key
       try {
         localStorage.removeItem(DEFAULT_CHAT_HISTORY_STORAGE_KEY);
@@ -5674,6 +6363,12 @@ export const createAgentExperience = (
       if (!artifactsSidebarEnabled(config)) return;
       session.clearArtifacts();
     },
+    getArtifacts(): PersonaArtifactRecord[] {
+      return session?.getArtifacts() ?? [];
+    },
+    getSelectedArtifactId(): string | null {
+      return session?.getSelectedArtifactId() ?? null;
+    },
     focusInput(): boolean {
       if (launcherEnabled && !open) return false;
       if (!textarea) return false;