@runtypelabs/persona 3.17.0 → 3.18.0

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);
+      }
+    });
+  }
 };
 
 

package/src/components/panel.ts

@@ -81,6 +81,12 @@ export interface PanelElements {
   container: HTMLElement;
   body: HTMLElement;
   messagesWrapper: HTMLElement;
+  /**
+   * Absolute-positioned slot above the composer footer. Interactive sheets
+   * (e.g. the answer-pill sheet for the ask_user_question tool) mount here
+   * so they slide in without reflowing the chat transcript.
+   */
+  composerOverlay: HTMLElement;
   suggestions: HTMLElement;
   textarea: HTMLTextAreaElement;
   sendButton: HTMLButtonElement;
@@ -138,10 +144,17 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   body.id = "persona-scroll-container";
   body.setAttribute("data-persona-theme-zone", "messages");
   
-  const introCardClasses = isDockedMountMode(config)
-    ? "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
-    : "persona-rounded-2xl persona-bg-persona-surface persona-p-6 persona-shadow-sm";
-  const introCard = createElement("div", introCardClasses);
+  const introCard = createElement(
+    "div",
+    "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
+  );
+  // Box-shadow flows through the themable `components.introCard.shadow` token
+  // (--persona-intro-card-shadow). Docked mode keeps a flat look by default;
+  // floating mode falls back to the legacy `persona-shadow-sm` value when no
+  // token is set.
+  introCard.style.boxShadow = isDockedMountMode(config)
+    ? "none"
+    : "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))";
   const introTitle = createElement(
     "h2",
     "persona-text-lg persona-font-semibold persona-text-persona-primary"
@@ -193,6 +206,26 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   
   container.append(body);
   
+  // Composer overlay slot: sits between body and footer, absolutely positioned
+  // above the composer so sheets (e.g. the ask_user_question answer-pill sheet)
+  // can slide up without reflowing the chat transcript above. Uses inline
+  // styles for left/right/bottom because widget.css is hand-authored and
+  // doesn't ship `.persona-left-0` / `.persona-right-0` rules — without
+  // them the overlay shrink-wraps to content and collapses the sheet width.
+  const composerOverlay = createElement(
+    "div",
+    "persona-composer-overlay persona-pointer-events-none"
+  );
+  composerOverlay.setAttribute("data-persona-composer-overlay", "");
+  composerOverlay.style.position = "absolute";
+  composerOverlay.style.left = "0";
+  composerOverlay.style.right = "0";
+  composerOverlay.style.bottom = "0";
+  // Above .persona-scroll-to-bottom-indicator (z-index 10, sibling in the
+  // container) so suggestion chips and the ask-user-question sheet are not
+  // covered by the "jump to latest" button.
+  composerOverlay.style.zIndex = "20";
+
   if (showFooter) {
     container.append(composerElements.footer);
   } else {
@@ -201,10 +234,14 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     container.append(composerElements.footer);
   }
 
+  // Append overlay last so it stacks above the footer / body content.
+  container.append(composerOverlay);
+
   return {
     container,
     body,
     messagesWrapper,
+    composerOverlay,
     suggestions: composerElements.suggestions,
     textarea: composerElements.textarea,
     sendButton: composerElements.sendButton,

package/src/defaults.ts

@@ -143,6 +143,13 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       speed: 120,
       duration: 1800,
     },
+    askUserQuestion: {
+      enabled: true,
+      slideInMs: 180,
+      freeTextLabel: "Other…",
+      freeTextPlaceholder: "Type your answer…",
+      submitLabel: "Send",
+    },
   },
   suggestionChips: [
     "What can you help me with?",
@@ -259,6 +266,8 @@ export function mergeWithDefaults(
       const csb = config.features?.scrollToBottom;
       const dsa = DEFAULT_WIDGET_CONFIG.features?.streamAnimation;
       const csa = config.features?.streamAnimation;
+      const dau = DEFAULT_WIDGET_CONFIG.features?.askUserQuestion;
+      const cau = config.features?.askUserQuestion;
       const mergedArtifacts =
         da === undefined && ca === undefined
           ? undefined
@@ -284,12 +293,24 @@ export function mergeWithDefaults(
               ...dsa,
               ...csa,
             };
+      const mergedAskUserQuestion =
+        dau === undefined && cau === undefined
+          ? undefined
+          : {
+              ...dau,
+              ...cau,
+              styles: {
+                ...dau?.styles,
+                ...cau?.styles,
+              },
+            };
       return {
         ...DEFAULT_WIDGET_CONFIG.features,
         ...config.features,
         ...(mergedScrollToBottom !== undefined ? { scrollToBottom: mergedScrollToBottom } : {}),
         ...(mergedArtifacts !== undefined ? { artifacts: mergedArtifacts } : {}),
         ...(mergedStreamAnimation !== undefined ? { streamAnimation: mergedStreamAnimation } : {}),
+        ...(mergedAskUserQuestion !== undefined ? { askUserQuestion: mergedAskUserQuestion } : {}),
       };
     })(),
     suggestionChips: config.suggestionChips ?? DEFAULT_WIDGET_CONFIG.suggestionChips,

package/src/index.ts

@@ -86,9 +86,24 @@ export type {
   EventStreamToolbarRenderContext,
   EventStreamPayloadRenderContext,
   // Controller event map
-  AgentWidgetControllerEventMap
+  AgentWidgetControllerEventMap,
+  // Ask-user-question (built-in answer-pill sheet) types
+  AskUserQuestionPayload,
+  AskUserQuestionPrompt,
+  AskUserQuestionOption,
+  AgentWidgetAskUserQuestionFeature,
+  AgentWidgetAskUserQuestionStyles
 } from "./types";
 
+export {
+  ASK_USER_QUESTION_TOOL_NAME,
+  createAskUserQuestionBubble,
+  ensureAskUserQuestionSheet,
+  removeAskUserQuestionSheet,
+  isAskUserQuestionMessage,
+  parseAskUserQuestionPayload
+} from "./components/ask-user-question-bubble";
+
 export { initAgentWidgetFn as initAgentWidget };
 export {
   createWidgetHostLayout,

package/src/plugins/types.ts

@@ -1,6 +1,7 @@
 import {
   AgentWidgetMessage,
   AgentWidgetConfig,
+  AskUserQuestionPayload,
   LoadingIndicatorRenderContext,
   IdleIndicatorRenderContext,
   EventStreamViewRenderContext,
@@ -107,6 +108,62 @@ export interface AgentWidgetPlugin {
     config: AgentWidgetConfig;
   }) => HTMLElement | null;
 
+  /**
+   * Custom renderer for `ask_user_question` tool calls.
+   *
+   * When a plugin returns an `HTMLElement`, it is inserted into the transcript
+   * in place of the default (which is no transcript bubble — the built-in
+   * renders a sheet over the composer). The built-in composer-overlay sheet
+   * is suppressed so the plugin's UI fully owns the interaction.
+   *
+   * Return `null` to fall through to the built-in overlay sheet.
+   *
+   * The context gives you a pre-parsed `payload` (may be partial while the
+   * tool call is still streaming — check `complete`) and two callbacks:
+   * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
+   * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
+   *
+   * @example
+   * ```typescript
+   * renderAskUserQuestion: ({ payload, resolve, dismiss }) => {
+   *   const prompt = payload.questions?.[0];
+   *   if (!prompt) return null;
+   *   const root = document.createElement("div");
+   *   root.textContent = prompt.question ?? "";
+   *   (prompt.options ?? []).forEach((option) => {
+   *     const btn = document.createElement("button");
+   *     btn.textContent = option.label;
+   *     btn.addEventListener("click", () => resolve(option.label));
+   *     root.appendChild(btn);
+   *   });
+   *   return root;
+   * }
+   * ```
+   */
+  renderAskUserQuestion?: (context: {
+    message: AgentWidgetMessage;
+    /**
+     * Parsed `{ questions: [...] }` payload. May be partial while the tool
+     * call is still streaming; see `complete`. `null` when no payload has
+     * arrived yet.
+     */
+    payload: Partial<AskUserQuestionPayload> | null;
+    /** `true` once the tool-call args have fully streamed in. */
+    complete: boolean;
+    /**
+     * Resume the paused LOCAL tool with the user's answer. Posts to the
+     * resume endpoint, pipes the SSE stream back into the session, and
+     * appends a user-visible answer bubble to the transcript.
+     */
+    resolve: (answer: string) => void;
+    /**
+     * Cancel the question. Resumes with the sentinel `"(dismissed)"` so the
+     * server doesn't sit in `waiting_for_local` forever. Idempotent.
+     */
+    dismiss: () => void;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | null;
+
   /**
    * Custom renderer for approval bubbles
    * Return null to use default renderer

package/src/session.test.ts

@@ -337,3 +337,186 @@ describe('AgentWidgetSession - cancel()', () => {
     expect(stopVoicePlaybackSpy).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('AgentWidgetSession.resolveAskUserQuestion', () => {
+  const makeAwaitingMessage = (): AgentWidgetMessage => ({
+    id: 'tool-msg-1',
+    role: 'assistant',
+    content: '',
+    createdAt: new Date().toISOString(),
+    variant: 'tool',
+    streaming: false,
+    toolCall: {
+      id: 'runtime_ask_user_question_1',
+      name: 'ask_user_question',
+      status: 'complete',
+      args: { questions: [{ question: 'Who?', options: [{ label: 'A' }] }] },
+      chunks: [],
+    },
+    agentMetadata: {
+      executionId: 'exec_abc',
+      awaitingLocalTool: true,
+    },
+  });
+
+  it('POSTs to /resume, appends a user bubble, and pipes the SSE stream through connectStream', async () => {
+    let capturedUrl: string | undefined;
+    let capturedBody: Record<string, unknown> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
+      capturedUrl = url;
+      capturedBody = JSON.parse(init.body as string);
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+          controller.close();
+        },
+      });
+      return { ok: true, body: stream };
+    });
+
+    const seen: AgentWidgetMessage[] = [];
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://localhost:43111/api/chat/dispatch' },
+      {
+        onMessagesChanged: (msgs) => { seen.splice(0, seen.length, ...msgs); },
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    const connectSpy = vi.spyOn(session, 'connectStream').mockResolvedValue(undefined);
+    await session.resolveAskUserQuestion(makeAwaitingMessage(), 'Hobbyists');
+
+    expect(capturedUrl).toBe('http://localhost:43111/api/chat/dispatch/resume');
+    expect(capturedBody).toEqual({
+      executionId: 'exec_abc',
+      toolOutputs: { ["ask_user_question"]: 'Hobbyists' },
+      streamResponse: true,
+    });
+
+    const userBubble = seen.find((m) => m.role === 'user' && m.content === 'Hobbyists');
+    expect(userBubble).toBeDefined();
+
+    expect(connectSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('flips askUserQuestionAnswered on the tool message before the POST fires', async () => {
+    const awaiting = makeAwaitingMessage();
+
+    const fetchMock = vi.fn().mockImplementation(async () => {
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+          controller.close();
+        },
+      });
+      return { ok: true, body: stream };
+    });
+    global.fetch = fetchMock;
+
+    let latest: AgentWidgetMessage[] = [];
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:43111/api/chat/dispatch',
+        initialMessages: [awaiting],
+      },
+      {
+        onMessagesChanged: (msgs) => { latest = msgs; },
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    vi.spyOn(session, 'connectStream').mockResolvedValue(undefined);
+
+    // Capture the flag state at the exact moment fetch is called — this is
+    // the "before the POST fires" assertion. The flag must be flipped BEFORE
+    // any network I/O so the subsequent stream-driven renders skip the sheet.
+    let flagAtFetch: { awaiting?: boolean; answered?: boolean } | undefined;
+    fetchMock.mockImplementationOnce(async () => {
+      const toolMsg = session.getMessages().find((m) => m.id === awaiting.id);
+      flagAtFetch = {
+        awaiting: toolMsg?.agentMetadata?.awaitingLocalTool,
+        answered: toolMsg?.agentMetadata?.askUserQuestionAnswered,
+      };
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+          controller.close();
+        },
+      });
+      return { ok: true, body: stream };
+    });
+
+    await session.resolveAskUserQuestion(awaiting, 'Hobbyists');
+
+    expect(flagAtFetch).toEqual({ awaiting: false, answered: true });
+
+    const finalToolMsg = latest.find((m) => m.id === awaiting.id);
+    expect(finalToolMsg?.agentMetadata?.askUserQuestionAnswered).toBe(true);
+    expect(finalToolMsg?.agentMetadata?.awaitingLocalTool).toBe(false);
+    expect(finalToolMsg?.agentMetadata?.executionId).toBe('exec_abc');
+  });
+
+  it('leaves the answered flag flipped even when resume fails', async () => {
+    const awaiting = makeAwaitingMessage();
+    global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 500, json: async () => ({ error: 'boom' }) });
+
+    const errors: Error[] = [];
+    let latest: AgentWidgetMessage[] = [];
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:43111/api/chat/dispatch',
+        initialMessages: [awaiting],
+      },
+      {
+        onMessagesChanged: (msgs) => { latest = msgs; },
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onError: (e) => errors.push(e),
+      }
+    );
+
+    await session.resolveAskUserQuestion(awaiting, 'Hobbyists');
+
+    expect(errors.length).toBe(1);
+    const finalToolMsg = latest.find((m) => m.id === awaiting.id);
+    expect(finalToolMsg?.agentMetadata?.askUserQuestionAnswered).toBe(true);
+  });
+
+  it('markAskUserQuestionResolved is idempotent and a no-op when the message is not in state', () => {
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://localhost:8000' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+    // No throw when the tool message isn't tracked in session state
+    expect(() => session.markAskUserQuestionResolved(makeAwaitingMessage())).not.toThrow();
+  });
+
+  it('surfaces errors through onError when the message is missing executionId', async () => {
+    const errors: Error[] = [];
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://localhost:8000' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onError: (e) => errors.push(e),
+      }
+    );
+
+    const bad = makeAwaitingMessage();
+    bad.agentMetadata = { ...bad.agentMetadata, executionId: undefined };
+
+    await session.resolveAskUserQuestion(bad, 'x');
+    expect(errors.length).toBe(1);
+    expect(errors[0].message).toMatch(/executionId/);
+  });
+});