@runtypelabs/persona 3.17.0 → 3.19.0

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,
@@ -200,6 +215,10 @@ export type {
 export { createDropdownMenu } from "./utils/dropdown";
 export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";
 
+// Icon utility exports
+export { renderLucideIcon } from "./utils/icons";
+export type { IconName } from "./utils/icons";
+
 // Button utility exports
 export { createIconButton, createLabelButton, createToggleGroup, createComboButton } from "./utils/buttons";
 export type {

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/runtime/init.ts

@@ -1,6 +1,6 @@
 import { createAgentExperience, AgentWidgetController } from "../ui";
 import { AgentWidgetConfig as _AgentWidgetConfig, AgentWidgetInitOptions, AgentWidgetEvent as _AgentWidgetEvent } from "../types";
-import { isDockedMountMode } from "../utils/dock";
+import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
 import { createWidgetHostLayout } from "./host-layout";
 
 const ensureTarget = (target: string | HTMLElement): HTMLElement => {
@@ -183,8 +183,10 @@ export const initAgentWidget = (
       } as _AgentWidgetConfig;
       const previousDocked = isDockedMountMode(config);
       const nextDocked = isDockedMountMode(mergedConfig);
+      const previousComposerBar = isComposerBarMountMode(config);
+      const nextComposerBar = isComposerBarMountMode(mergedConfig);
 
-      if (previousDocked !== nextDocked) {
+      if (previousDocked !== nextDocked || previousComposerBar !== nextComposerBar) {
         rebuildLayout(mergedConfig);
         return;
       }

package/src/runtime/persist-state.test.ts

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "../ui";
+import { createLocalStorageAdapter } from "../utils/storage";
+import type { AgentWidgetStorageAdapter } from "../types";
+
+const DEFAULT_KEY = "persona-state";
+
+const baseConfig = () => ({
+  apiUrl: "https://api.example.com/chat",
+  launcher: { enabled: false } as const,
+});
+
+const inject = (controller: ReturnType<typeof createAgentExperience>) =>
+  controller.injectAssistantMessage({ content: "hello world" });
+
+describe("persistState gates storage adapter", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    try {
+      window.localStorage.clear();
+    } catch {
+      /* jsdom edge cases */
+    }
+  });
+
+  it("persistState: false skips the default localStorage adapter", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+    });
+
+    inject(controller);
+
+    expect(window.localStorage.getItem(DEFAULT_KEY)).toBeNull();
+    controller.destroy();
+  });
+
+  it("persistState: false ignores any user-supplied storageAdapter (strict semantic)", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const customAdapter: AgentWidgetStorageAdapter = {
+      load: vi.fn(() => null),
+      save: vi.fn(),
+      clear: vi.fn(),
+    };
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+      storageAdapter: customAdapter,
+    });
+
+    inject(controller);
+
+    expect(customAdapter.load).not.toHaveBeenCalled();
+    expect(customAdapter.save).not.toHaveBeenCalled();
+    controller.destroy();
+  });
+
+  it("default config (persistState undefined) writes to the default localStorage key", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, baseConfig());
+
+    inject(controller);
+
+    const stored = window.localStorage.getItem(DEFAULT_KEY);
+    expect(stored).not.toBeNull();
+    const parsed = JSON.parse(stored!);
+    expect(parsed.messages).toBeInstanceOf(Array);
+    expect(parsed.messages.length).toBeGreaterThan(0);
+    controller.destroy();
+  });
+
+  it("persistState: true keeps using the default localStorage adapter", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: true,
+    });
+
+    inject(controller);
+
+    expect(window.localStorage.getItem(DEFAULT_KEY)).not.toBeNull();
+    controller.destroy();
+  });
+
+  it("two widgets with different storageAdapter keys keep their messages isolated", () => {
+    const mountA = document.createElement("div");
+    const mountB = document.createElement("div");
+    document.body.appendChild(mountA);
+    document.body.appendChild(mountB);
+
+    const controllerA = createAgentExperience(mountA, {
+      ...baseConfig(),
+      storageAdapter: createLocalStorageAdapter("persona-state-test-a"),
+    });
+    const controllerB = createAgentExperience(mountB, {
+      ...baseConfig(),
+      storageAdapter: createLocalStorageAdapter("persona-state-test-b"),
+    });
+
+    controllerA.injectAssistantMessage({ content: "message in A" });
+    controllerB.injectAssistantMessage({ content: "message in B" });
+
+    const storedA = JSON.parse(window.localStorage.getItem("persona-state-test-a")!);
+    const storedB = JSON.parse(window.localStorage.getItem("persona-state-test-b")!);
+
+    const aHasA = storedA.messages.some((m: { content?: string }) => m.content === "message in A");
+    const aHasB = storedA.messages.some((m: { content?: string }) => m.content === "message in B");
+    const bHasA = storedB.messages.some((m: { content?: string }) => m.content === "message in A");
+    const bHasB = storedB.messages.some((m: { content?: string }) => m.content === "message in B");
+
+    expect(aHasA).toBe(true);
+    expect(aHasB).toBe(false);
+    expect(bHasB).toBe(true);
+    expect(bHasA).toBe(false);
+    expect(window.localStorage.getItem(DEFAULT_KEY)).toBeNull();
+
+    controllerA.destroy();
+    controllerB.destroy();
+  });
+
+  it("persistState: false does not read from localStorage on init", () => {
+    // Pre-seed the default key with a stored message.
+    window.localStorage.setItem(
+      DEFAULT_KEY,
+      JSON.stringify({ messages: [{ id: "stale", role: "assistant", content: "stale" }] })
+    );
+
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+    });
+
+    expect(controller.getMessages()).toEqual([]);
+    controller.destroy();
+  });
+});

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