@runtypelabs/persona 4.25.0 → 4.26.0

package/src/types.ts

@@ -4766,6 +4766,45 @@ export type AgentWidgetVoiceRecognitionConfig = {
        * @default 30000
        */
       attachIdleMs?: number;
+      /**
+       * Full-duplex (speech-to-speech, e.g. GPT-Live) calls: run the turns the
+       * voice model hands off to the agent through this widget's normal chat
+       * pipeline. The spoken request becomes the user message, and the answer
+       * renders as a regular assistant message (streaming, tool and approval
+       * UI, WebMCP page tools, persistence) that the voice model then reads
+       * aloud. Only takes effect when the server supports it (it confirms in
+       * `session_config`); otherwise the agent turn runs on the server and its
+       * spoken reply is transcribed, as before. Set `false` to always keep the
+       * agent turn on the server.
+       * @default true
+       */
+      clientDelegation?: boolean;
+      /**
+       * Full-duplex calls: extra context for the voice model (for example the
+       * page the visitor is on), sent after the chat history as of call start.
+       * The frame goes out once, when the visitor finishes their first
+       * utterance (or at the first agent hand-off). A function is
+       * called at call start and may be async. This text is capped at 4000 characters and the whole frame
+       * (history included) at 8000. Sent only to servers that accept call
+       * context (they announce it in `session_config`).
+       */
+      callContext?: string | (() => string | Promise<string>);
+      /**
+       * Full-duplex calls with client delegation: how long a tool approval
+       * that a spoken request raised may wait before it is declined as
+       * expired (and the voice model says so). Server-side approval gates
+       * keep their own timeout too. Hanging up never declines it: the
+       * approval card in the chat stays usable. Capped at 540000 (9 minutes),
+       * under the server's 10-minute delegation deadline.
+       * @default 300000
+       */
+      approvalTimeoutMs?: number;
+      /**
+       * Speech-to-speech calls: the one-line notice shown in the composer
+       * status area when the call starts. `false` hides it.
+       * @default "You're talking to an AI assistant. Voice is processed by OpenAI."
+       */
+      disclosureText?: string | false;
       /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
       pauseDuration?: number;
       /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -5024,6 +5063,13 @@ export interface VoicePlaybackEngine {
   onFinished(callback: () => void): void;
   /** Release all audio resources. */
   destroy(): Promise<void> | void;
+  /**
+   * Optional. Speech-to-speech calls stream reply audio with no end-of-stream
+   * marker, so an engine that holds audio below a prebuffer waterline must, while
+   * continuous, release that held tail on its own (e.g. after a short input gap)
+   * instead of waiting for {@link markStreamEnd}. Engines without a prebuffer can omit it.
+   */
+  setContinuousMode?(enabled: boolean): void;
 }
 
 /**
@@ -5077,6 +5123,14 @@ export type VoiceConfig = {
     prewarmMode?: 'request' | 'attach';
     /** See `voiceRecognition.provider.runtype.attachIdleMs`. @default 30000 */
     attachIdleMs?: number;
+    /** See `voiceRecognition.provider.runtype.clientDelegation`. @default true */
+    clientDelegation?: boolean;
+    /** See `voiceRecognition.provider.runtype.callContext`. */
+    callContext?: string | (() => string | Promise<string>);
+    /** See `voiceRecognition.provider.runtype.approvalTimeoutMs`. @default 300000 (capped at 540000) */
+    approvalTimeoutMs?: number;
+    /** See `voiceRecognition.provider.runtype.disclosureText`. */
+    disclosureText?: string | false;
     /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
     pauseDuration?: number;
     /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -5114,13 +5168,24 @@ export interface VoiceProvider {
    * Register a callback for incremental transcript updates during a voice turn.
    * `isFinal=false` is a live interim update (user partials, or assistant deltas
    * on providers that stream them); `isFinal=true` finalizes that role's text.
-   * On the realtime `runtype` path, interim updates fire for the `user` only and
-   * the `assistant` arrives as a single final. Providers with overlapping turns
-   * must include the same turnId on user and assistant finals; without IDs,
-   * providers must discard cancelled output before emitting the next user final.
+   * On the classic realtime `runtype` path, interim updates fire for the `user`
+   * only and the `assistant` arrives as a single final; without a turnId the
+   * session assumes strictly alternating turns, and providers must discard
+   * cancelled output before emitting the next user final.
+   *
+   * When `metadata.turnId` is present (full-duplex / speech-to-speech, e.g.
+   * GPT-Live), the session reconciles by `(turnId, role)`: each pair owns one
+   * bubble that later updates replace in place, turns may overlap or arrive in
+   * any order, and no empty assistant placeholder is injected. User and
+   * assistant may share a turnId (a late user bubble then renders above its
+   * reply) or use distinct ones. `metadata.startMs` (call-relative ms when the
+   * utterance began) orders a new bubble among the call's other keyed bubbles;
+   * without it bubbles order by first arrival. After a stop, keyed providers
+   * must drop the cancelled reply's output until the server acknowledges the
+   * cancel: the session renders every reply it receives.
    */
   onTranscript?(
-    callback: (role: 'user' | 'assistant', text: string, isFinal: boolean, metadata?: { turnId?: string }) => void,
+    callback: (role: 'user' | 'assistant', text: string, isFinal: boolean, metadata?: VoiceTranscriptMetadata) => void,
   ): void;
 
   /** Register a callback for per-turn latency metrics (realtime path). */
@@ -5156,6 +5221,117 @@ export interface VoiceProvider {
    * repeatedly; throttle as needed.
    */
   prewarm?(): void;
+
+  /**
+   * Called by the session once after construction with the chat-side surface
+   * a full-duplex provider uses to hand agent turns to the chat pipeline
+   * ({@link VoiceSessionBridge}). Providers without client delegation omit it.
+   */
+  setSessionBridge?(bridge: VoiceSessionBridge): void;
+  /** The AI-disclosure notice for the live call, if one should show (speech-to-speech). */
+  getDisclosure?(): string | null;
+}
+
+/** Metadata on a {@link VoiceProvider.onTranscript} update. */
+export type VoiceTranscriptMetadata = {
+  /** Groups updates that belong to one utterance bubble (full duplex). */
+  turnId?: string;
+  /** Call-relative ms when the utterance began; orders late bubbles. */
+  startMs?: number;
+  /** Call-relative ms of the latest audio this update covers. */
+  endMs?: number;
+  /**
+   * The bubble only captions speech (see `AgentWidgetMessage.voiceCaption`).
+   * The chat pipeline owns the conversation, as with client delegation.
+   */
+  caption?: boolean;
+};
+
+/** An agent turn a full-duplex voice model handed to the widget. */
+export type VoiceDelegationRequest = {
+  /** The voice model's delegation id (`delegation_started.delegationId`). */
+  delegationId: string;
+  /** What the visitor asked, as the voice model heard it. */
+  userText: string;
+  /**
+   * The user transcript utterances `userText` joins, oldest first (the last
+   * is the one it came from). May be empty.
+   */
+  userUtteranceIds: string[];
+  /** The voice model's view of the conversation it delegated from. */
+  messages: Array<{ role: string; content: unknown }>;
+};
+
+/**
+ * How a delegated turn ended, or that it waits on an approval (contract
+ * Amendment 5). `pending_approval` is the only non-terminal status. Open:
+ * a receiver treats an unknown terminal status as `failed`.
+ * - `completed`: the work ran.
+ * - `denied`: the visitor said no (Deny tap, or a spoken decline).
+ * - `timeout`: the approval lapsed (`approvalTimeoutMs`, or the server's own timeout).
+ * - `cancelled`: replaced by a newer request, or abandoned by the system.
+ * - `failed`: an error.
+ */
+export type VoiceDelegationStatus =
+  | 'completed'
+  | 'pending_approval'
+  | 'denied'
+  | 'timeout'
+  | 'cancelled'
+  | 'failed'
+  | (string & {});
+
+/** The terminal result of a turn that parked on approvals. */
+export type VoiceDelegationFollowUp = {
+  status: VoiceDelegationStatus;
+  /** What to read aloud (Markdown allowed). May be empty: nothing more to say. */
+  text: string;
+};
+
+/** The delegated turn's answer, sent back for the voice model to read aloud. */
+export type VoiceDelegationResult = {
+  /** `pending_approval` when `followUp` is set; otherwise terminal. */
+  status: VoiceDelegationStatus;
+  /** The assistant text (Markdown allowed). */
+  text: string;
+  /**
+   * Set when the turn parked on approvals (`text` then asks for the decision).
+   * Resolves with the terminal result once the visitor decides (or the
+   * approval is replaced, declined by voice, or unanswered for
+   * `approvalTimeoutMs`) and the resumed turn finishes; `null` only when
+   * `signal` aborts first (hang-up, or the server cancelled the delegation).
+   */
+  followUp?: (options: {
+    signal: AbortSignal;
+    approvalTimeoutMs?: number;
+    /** `false`: run only the approval bookkeeping (expiry, supersede); nothing will be read back. @default true */
+    readBack?: boolean;
+    /** The resumed turn stopped on another approval: ask for it too (`text` is its approval script). */
+    onUpdate?: (text: string) => void;
+  }) => Promise<VoiceDelegationFollowUp | null>;
+};
+
+/**
+ * Chat-side surface the session hands a full-duplex provider: the visible
+ * history (for the call-start context) and a way to run a delegated turn
+ * through the normal chat pipeline.
+ */
+export interface VoiceSessionBridge {
+  /** Visible user/assistant messages, oldest first. */
+  getHistory(): Array<{ role: 'user' | 'assistant'; content: string }>;
+  /**
+   * Submit the turn as the visitor's message (reusing its transcript bubble)
+   * and resolve with the assistant's final answer once the turn settles.
+   * Waits for any chat turn already in flight first. Never rejects.
+   */
+  runDelegatedTurn(request: VoiceDelegationRequest): Promise<VoiceDelegationResult>;
+  /**
+   * The server dropped this delegation's result (cancelled it, or refused a
+   * late result): its chat answer is no longer spoken, so browser TTS may read it.
+   * `expired`: the server's deadline passed, so its pending approvals are
+   * declined too, as the approval TTL would.
+   */
+  dropDelegation?(delegationId: string, expired?: boolean): void;
 }
 
 /**
@@ -8038,6 +8214,11 @@ export type AgentWidgetToolCall = {
   startedAt?: number;
   completedAt?: number;
   durationMs?: number;
+  /**
+   * The call paused for an approval that was granted, and the agent re-ran it
+   * as a new tool call: that later call carries the result, this one has none.
+   */
+  superseded?: boolean;
 };
 
 /**
@@ -8060,6 +8241,8 @@ export type AgentWidgetApproval = {
    */
   reason?: string;
   parameters?: unknown;
+  /** The paused tool call this approval gates (`approval_start.toolCallId`). */
+  toolCallId?: string;
   resolvedAt?: number;
 };
 
@@ -8162,6 +8345,13 @@ export type AgentWidgetMessage = {
    * }
    */
   voiceProcessing?: boolean;
+  /**
+   * Display-only caption of full-duplex voice speech, such as the voice
+   * model's own words, or something the visitor said that wasn't submitted
+   * as a chat turn. It renders in the transcript but is never sent to the
+   * model as conversation.
+   */
+  voiceCaption?: boolean;
   /**
    * Raw structured payload for this message (e.g., JSON action response).
    * Populated automatically when structured parsers run.
@@ -8291,6 +8481,9 @@ export type InjectMessageOptions = {
    */
   voiceProcessing?: boolean;
 
+  /** See {@link AgentWidgetMessage.voiceCaption}. */
+  voiceCaption?: boolean;
+
   /**
    * Raw structured payload (typically a JSON string) representing the
    * full directive that produced this message: e.g. `{ "text": "...",

package/src/ui-ask-user-sheet.ts

@@ -0,0 +1,382 @@
+/**
+ * Event handlers for the `ask_user_question` answer sheet that mounts in the
+ * composer overlay: pill pick (single), multi-select toggle + submit, free-text
+ * expansion + submit, grouped-question paging, skip, and dismissal. A selection
+ * becomes a regular user message (or a LOCAL-tool resume) so the agent
+ * continues on the next turn.
+ *
+ * Lives in the lazy `ui-extras` chunk: `ui.ts` warms it when a sheet mounts
+ * and routes overlay events here once loaded.
+ */
+import type { AgentWidgetConfig } from "./types";
+import type { AgentWidgetSession } from "./session";
+import {
+  buildStructuredAnswers,
+  getCurrentIndex,
+  getQuestionCount,
+  getSelectedLabels,
+  isGroupedSheet,
+  navigateToPage,
+  readAnswersFromSheet,
+  removeAskUserQuestionSheet,
+  setCurrentAnswer,
+} from "./components/ask-user-question-bubble";
+
+export type AskUserSheetContext = {
+  mount: HTMLElement;
+  overlay: HTMLElement;
+  sessionRef: { current: AgentWidgetSession | null };
+  /** Read live: `controller.update()` replaces the config. */
+  config: () => AgentWidgetConfig;
+};
+
+export type AskUserSheetHandlers = {
+  click: (event: MouseEvent) => void;
+  keydown: (event: KeyboardEvent) => void;
+};
+
+export const createAskUserSheetHandlers = (ctx: AskUserSheetContext): AskUserSheetHandlers => {
+  const { mount, overlay: askUserOverlay, sessionRef } = ctx;
+
+  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 (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 (ctx.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, ctx.config(), idx + 1);
+    persistGroupedProgress(sheet);
+  };
+
+  const click = (event: MouseEvent): void => {
+    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, ctx.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, ctx.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.
+  const keydown = (event: KeyboardEvent): void => {
+    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" });
+  };
+
+  return { click, keydown };
+};

package/src/ui-extras-eager.ts

@@ -0,0 +1,10 @@
+/**
+ * Eager `ui-extras` registration for the bundled (ESM / CJS) builds and tests,
+ * so the features behind it respond synchronously. Like
+ * `markdown-parsers-eager.ts`, this module must NOT be reachable from
+ * `index-global.ts`: the IIFE/CDN build fetches the `ui-extras.js` chunk.
+ */
+import * as uiExtras from "./ui-extras-entry";
+import { provideUiExtras } from "./ui-extras-loader";
+
+provideUiExtras(uiExtras);

package/src/ui-extras-entry.ts

@@ -0,0 +1,9 @@
+/**
+ * Entry for the lazy `ui-extras` chunk: `ui.ts` glue for opt-in or
+ * interaction-only features, kept out of the IIFE/CDN core bundle. See
+ * `ui-extras-loader.ts`.
+ */
+export { createAskUserSheetHandlers } from "./ui-ask-user-sheet";
+// Context-mention orchestrator (opt-in `contextMentions.enabled`). Callers pass
+// core's loaders / icon registry via `deps` so this chunk's copies stay unused.
+export { createContextMentionOrchestrator } from "./utils/context-mention-orchestrator";