@runtypelabs/persona 3.16.0 → 3.18.0

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;
@@ -110,6 +116,8 @@ export interface PanelElements {
   actionsRow: HTMLElement;
   leftActions: HTMLElement;
   rightActions: HTMLElement;
+  /** Swap the send button between its send and stop appearances. */
+  setSendButtonMode: (mode: "send" | "stop") => void;
 }
 
 export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelElements => {
@@ -136,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"
@@ -191,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 {
@@ -199,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,
@@ -230,7 +269,8 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     // Actions row layout elements
     actionsRow: composerElements.actionsRow,
     leftActions: composerElements.leftActions,
-    rightActions: composerElements.rightActions
+    rightActions: composerElements.rightActions,
+    setSendButtonMode: composerElements.setSendButtonMode
   };
 };
 

package/src/defaults.ts

@@ -137,6 +137,19 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       expandable: true,
       loadingAnimation: "none",
     },
+    streamAnimation: {
+      type: "none",
+      placeholder: "none",
+      speed: 120,
+      duration: 1800,
+    },
+    askUserQuestion: {
+      enabled: true,
+      slideInMs: 180,
+      freeTextLabel: "Other…",
+      freeTextPlaceholder: "Type your answer…",
+      submitLabel: "Send",
+    },
   },
   suggestionChips: [
     "What can you help me with?",
@@ -251,6 +264,10 @@ export function mergeWithDefaults(
       const ca = config.features?.artifacts;
       const dsb = DEFAULT_WIDGET_CONFIG.features?.scrollToBottom;
       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
@@ -269,11 +286,31 @@ export function mergeWithDefaults(
               ...dsb,
               ...csb,
             };
+      const mergedStreamAnimation =
+        dsa === undefined && csa === undefined
+          ? undefined
+          : {
+              ...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-global.ts

@@ -0,0 +1,31 @@
+/**
+ * IIFE entry point — bundled for `<script>` tag consumers.
+ *
+ * This file re-exports everything from the main entry AND side-imports all
+ * built-in subpath animations so they register automatically. Script-tag
+ * users who include the global build don't need extra script tags or
+ * registration calls — setting `features.streamAnimation.type` to any
+ * built-in name just works.
+ *
+ * npm consumers continue to import from the main entry (`import ... from
+ * "@runtypelabs/persona"`) — those animations stay in their subpath
+ * modules so bundlers can tree-shake them.
+ */
+
+// Re-export the full public API.
+export * from "./index";
+
+// Side-import the remaining subpath animations so they're available to
+// script-tag consumers without an explicit import. (`letter-rise` and
+// `word-fade` are core built-ins and register automatically.)
+import "./animations/wipe";
+import "./animations/glyph-cycle";
+
+// Expose plugin-registration helpers on the global so custom animations
+// can be registered from inline `<script>` blocks or third-party CDN scripts.
+export {
+  registerStreamAnimationPlugin,
+  unregisterStreamAnimationPlugin,
+  listRegisteredStreamAnimations,
+} from "./utils/stream-animation";
+export type { StreamAnimationPlugin, StreamAnimationContext } from "./types";

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,
@@ -178,6 +193,24 @@ export type { AgentWidgetInitHandle };
 export type { AgentWidgetPlugin } from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
+// Stream animation plugin API — lets consumers register custom animations
+// that match the built-in surface (typewriter, pop-bubble) and subpath
+// modules (letter-rise, word-fade, wipe, glyph-cycle).
+export {
+  registerStreamAnimationPlugin,
+  unregisterStreamAnimationPlugin,
+  listRegisteredStreamAnimations,
+} from "./utils/stream-animation";
+export type {
+  StreamAnimationPlugin,
+  StreamAnimationContext,
+  AgentWidgetStreamAnimationBuffer,
+  AgentWidgetStreamAnimationBuiltinType,
+  AgentWidgetStreamAnimationType,
+  AgentWidgetStreamAnimationFeature,
+  AgentWidgetStreamAnimationPlaceholder,
+} from "./types";
+
 // Dropdown utility exports
 export { createDropdownMenu } from "./utils/dropdown";
 export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";

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

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { AgentWidgetSession, AgentWidgetSessionStatus } from './session';
 import { AgentWidgetMessage } from './types';
 
@@ -245,3 +245,278 @@ describe('AgentWidgetSession - Message Injection', () => {
     });
   });
 });
+
+describe('AgentWidgetSession - cancel()', () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it('aborts the in-flight dispatch and flips streaming/status back to idle', async () => {
+    let capturedSignal: AbortSignal | null = null;
+    // Fetch returns a promise that only settles when the AbortSignal fires —
+    // modeling a dispatch that's still receiving SSE tokens.
+    global.fetch = vi.fn().mockImplementation((_url: string, options: any) => {
+      capturedSignal = options.signal as AbortSignal;
+      return new Promise((_resolve, reject) => {
+        options.signal?.addEventListener('abort', () => {
+          const err = new Error('aborted');
+          err.name = 'AbortError';
+          reject(err);
+        });
+      });
+    });
+
+    let streaming = false;
+    let status: AgentWidgetSessionStatus = 'idle';
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: (s) => { status = s; },
+        onStreamingChanged: (s) => { streaming = s; }
+      }
+    );
+
+    // Kick off the dispatch but don't await — we want it in-flight when we cancel.
+    const dispatchPromise = session.sendMessage('Hello');
+    // Let the session set up the AbortController and call fetch.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(streaming).toBe(true);
+    expect(session.isStreaming()).toBe(true);
+    expect(capturedSignal).not.toBeNull();
+    expect(capturedSignal!.aborted).toBe(false);
+
+    session.cancel();
+
+    expect(session.isStreaming()).toBe(false);
+    expect(streaming).toBe(false);
+    expect(status).toBe('idle');
+    expect(capturedSignal!.aborted).toBe(true);
+
+    // Drain the dispatch promise so the test doesn't leak a rejection.
+    await dispatchPromise;
+  });
+
+  it('is a no-op when not streaming', () => {
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {}
+      }
+    );
+
+    expect(session.isStreaming()).toBe(false);
+    expect(() => session.cancel()).not.toThrow();
+    expect(session.isStreaming()).toBe(false);
+    expect(session.getStatus()).toBe('idle');
+  });
+
+  it('stops in-progress audio playback (TTS + voice provider) on cancel', () => {
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {}
+      }
+    );
+
+    const stopSpeakingSpy = vi.spyOn(session, 'stopSpeaking');
+    const stopVoicePlaybackSpy = vi.spyOn(session, 'stopVoicePlayback');
+
+    session.cancel();
+
+    expect(stopSpeakingSpy).toHaveBeenCalledTimes(1);
+    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/);
+  });
+});