@runtypelabs/persona 3.31.1 → 3.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.31.1",
+  "version": "3.33.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/ask-user-question-tool.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  ASK_USER_QUESTION_CLIENT_TOOL,
+  ASK_USER_QUESTION_PARAMETERS_SCHEMA,
+  builtInClientToolsForDispatch,
+} from "./ask-user-question-tool";
+import {
+  ASK_USER_QUESTION_MAX,
+  ASK_USER_QUESTION_TOOL_NAME,
+} from "./components/ask-user-question-bubble";
+import { AgentWidgetClient } from "./client";
+import { computeClientToolsFingerprint } from "./webmcp-bridge";
+import type { AgentWidgetConfig } from "./types";
+
+describe("ASK_USER_QUESTION_CLIENT_TOOL definition", () => {
+  it("matches the renderer's tool name and origin/annotation contract", () => {
+    expect(ASK_USER_QUESTION_CLIENT_TOOL.name).toBe(ASK_USER_QUESTION_TOOL_NAME);
+    // `'sdk'` keeps the bare name on the wire (the server only prefixes
+    // `origin: 'webmcp'` tools) so the step_await routes to the answer sheet,
+    // not the WebMCP bridge. `'local'` is NOT a valid server-side origin.
+    expect(ASK_USER_QUESTION_CLIENT_TOOL.origin).toBe("sdk");
+    expect(ASK_USER_QUESTION_CLIENT_TOOL.annotations?.readOnlyHint).toBe(true);
+  });
+
+  it("bounds questions to the renderer cap and options to 2-4", () => {
+    const questions = ASK_USER_QUESTION_PARAMETERS_SCHEMA.properties.questions;
+    expect(questions.minItems).toBe(1);
+    expect(questions.maxItems).toBe(ASK_USER_QUESTION_MAX);
+    const options = questions.items.properties.options;
+    expect(options.minItems).toBe(2);
+    expect(options.maxItems).toBe(4);
+    expect(questions.items.required).toEqual(["question", "options"]);
+  });
+});
+
+describe("builtInClientToolsForDispatch", () => {
+  it("returns nothing by default (expose is opt-in)", () => {
+    expect(builtInClientToolsForDispatch(undefined)).toEqual([]);
+    expect(builtInClientToolsForDispatch({} as AgentWidgetConfig)).toEqual([]);
+    expect(
+      builtInClientToolsForDispatch({
+        features: { askUserQuestion: {} },
+      } as AgentWidgetConfig)
+    ).toEqual([]);
+  });
+
+  it("returns the tool when expose is true", () => {
+    expect(
+      builtInClientToolsForDispatch({
+        features: { askUserQuestion: { expose: true } },
+      } as AgentWidgetConfig)
+    ).toEqual([ASK_USER_QUESTION_CLIENT_TOOL]);
+  });
+
+  it("ignores expose when the answer sheet is disabled", () => {
+    // Offering the agent a question tool the widget can't render an answer
+    // UI for would park the execution on a generic tool bubble forever.
+    expect(
+      builtInClientToolsForDispatch({
+        features: { askUserQuestion: { expose: true, enabled: false } },
+      } as AgentWidgetConfig)
+    ).toEqual([]);
+  });
+});
+
+describe("AgentWidgetClient - built-in ask_user_question exposure", () => {
+  const captureDispatchBody = () => {
+    const captured: { body: string | null } = { body: null };
+    global.fetch = vi
+      .fn()
+      .mockImplementation(async (_url: string, options: { body: string }) => {
+        captured.body = options.body;
+        const encoder = new TextEncoder();
+        const stream = new ReadableStream({
+          start(controller) {
+            controller.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+            controller.close();
+          },
+        });
+        return new Response(stream, {
+          headers: { "Content-Type": "text/event-stream" },
+        });
+      });
+    return captured;
+  };
+
+  const userMessage = () => ({
+    id: "u1",
+    role: "user" as const,
+    content: "hi",
+    createdAt: new Date().toISOString(),
+  });
+
+  it("ships ask_user_question on clientTools when expose is on (no WebMCP)", async () => {
+    const captured = captureDispatchBody();
+    const client = new AgentWidgetClient({
+      apiUrl: "http://localhost:8000",
+      features: { askUserQuestion: { expose: true } },
+    });
+    await client.dispatch({ messages: [userMessage()] }, () => undefined);
+    const parsed = JSON.parse(captured.body!);
+    expect(parsed.clientTools).toEqual([ASK_USER_QUESTION_CLIENT_TOOL]);
+  });
+
+  it("omits clientTools entirely when expose is off and no WebMCP tools exist", async () => {
+    const captured = captureDispatchBody();
+    const client = new AgentWidgetClient({
+      apiUrl: "http://localhost:8000",
+    });
+    await client.dispatch({ messages: [userMessage()] }, () => undefined);
+    const parsed = JSON.parse(captured.body!);
+    expect(parsed.clientTools).toBeUndefined();
+  });
+
+  it("leads the WebMCP snapshot when both are present", async () => {
+    const captured = captureDispatchBody();
+    const client = new AgentWidgetClient({
+      apiUrl: "http://localhost:8000",
+      features: { askUserQuestion: { expose: true } },
+    });
+    (
+      client as unknown as {
+        webMcpBridge: { snapshotForDispatch: () => unknown[] } | null;
+      }
+    ).webMcpBridge = {
+      snapshotForDispatch: () => [
+        { name: "search", description: "s", origin: "webmcp" },
+      ],
+    };
+    await client.dispatch({ messages: [userMessage()] }, () => undefined);
+    const parsed = JSON.parse(captured.body!);
+    expect(parsed.clientTools).toEqual([
+      ASK_USER_QUESTION_CLIENT_TOOL,
+      { name: "search", description: "s", origin: "webmcp" },
+    ]);
+  });
+
+  it("changes the clientTools fingerprint when toggled (diff-only resend)", () => {
+    // In client-token mode the widget only resends the full clientTools[]
+    // when the fingerprint changes — toggling expose must change it so the
+    // server actually learns about (or forgets) the built-in tool.
+    const webMcpOnly = [{ name: "search", description: "s" }];
+    const withBuiltIn = [ASK_USER_QUESTION_CLIENT_TOOL, ...webMcpOnly];
+    expect(computeClientToolsFingerprint(withBuiltIn)).not.toBe(
+      computeClientToolsFingerprint(webMcpOnly)
+    );
+  });
+});

package/src/ask-user-question-tool.ts

@@ -0,0 +1,138 @@
+/**
+ * Built-in `ask_user_question` client tool.
+ *
+ * The widget can advertise this tool to the agent on every dispatch via
+ * `clientTools[]` (set `features.askUserQuestion.expose: true`) — the same
+ * wire surface WebMCP page tools ride. The server registers it as a LOCAL
+ * tool under its bare name (`origin: 'sdk'` tools are not `webmcp:`-prefixed),
+ * so when the model calls it the execution pauses with a `step_await`
+ * (`awaitReason: "local_tool_required"`), the widget's answer-pill sheet
+ * renders, and `session.resolveAskUserQuestion()` resumes the execution with
+ * the structured answers.
+ *
+ * This replaces the previous integrator burden of hand-declaring the tool in
+ * a flow's `runtimeTools` and keeping that schema in sync with the renderer.
+ * Flows that already declare `ask_user_question` server-side should leave
+ * `expose` off — the model would otherwise see the tool twice.
+ */
+
+import {
+  ASK_USER_QUESTION_MAX,
+  ASK_USER_QUESTION_TOOL_NAME,
+} from "./components/ask-user-question-bubble";
+import {
+  SUGGEST_REPLIES_CLIENT_TOOL,
+  shouldExposeSuggestReplies,
+} from "./suggest-replies-tool";
+import type { AgentWidgetConfig, ClientToolDefinition } from "./types";
+
+/**
+ * JSON Schema for the tool's parameters. Mirrors {@link AskUserQuestionPayload}
+ * — the shape `parseAskUserQuestionPayload` hydrates the answer sheet from —
+ * so the schema the model is held to and the schema the renderer expects can
+ * never drift.
+ */
+export const ASK_USER_QUESTION_PARAMETERS_SCHEMA = {
+  type: "object",
+  properties: {
+    questions: {
+      type: "array",
+      minItems: 1,
+      maxItems: ASK_USER_QUESTION_MAX,
+      description: "Questions to ask the user. Prefer a single question.",
+      items: {
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description: "The complete question, ending with a question mark.",
+          },
+          header: {
+            type: "string",
+            maxLength: 12,
+            description: 'Short topic label, e.g. "Auth method".',
+          },
+          options: {
+            type: "array",
+            minItems: 2,
+            maxItems: 4,
+            description:
+              '2-4 distinct choices. Do NOT add an "Other" option — free text is automatic.',
+            items: {
+              type: "object",
+              properties: {
+                label: {
+                  type: "string",
+                  description: "Concise choice text (1-5 words).",
+                },
+                description: {
+                  type: "string",
+                  description: "What the option means or implies.",
+                },
+              },
+              required: ["label"],
+              additionalProperties: false,
+            },
+          },
+          multiSelect: {
+            type: "boolean",
+            description: "Allow selecting multiple options. Default false.",
+          },
+          allowFreeText: {
+            type: "boolean",
+            description: "Show a free-text input. Default true.",
+          },
+        },
+        required: ["question", "options"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["questions"],
+  additionalProperties: false,
+} as const;
+
+/**
+ * The `ClientToolDefinition` shipped on `dispatch.clientTools[]` when
+ * `features.askUserQuestion.expose` is on. Exported so integrators who prefer
+ * declaring the tool server-side (a flow's `runtimeTools`) can reuse the same
+ * description and schema instead of hand-writing them.
+ */
+export const ASK_USER_QUESTION_CLIENT_TOOL: ClientToolDefinition = {
+  name: ASK_USER_QUESTION_TOOL_NAME,
+  description:
+    "Ask the user multiple-choice questions and wait for their answers. Use " +
+    "only when blocked on a decision that is the user's to make — a " +
+    "preference, a choice between valid approaches, or information you " +
+    "cannot infer. Each question offers 2-4 options plus an automatic " +
+    "free-text input. The result maps each question to its answer (an array " +
+    "when multiSelect); a question absent from the result was skipped.",
+  parametersSchema: ASK_USER_QUESTION_PARAMETERS_SCHEMA,
+  origin: "sdk",
+  annotations: { readOnlyHint: true },
+};
+
+/**
+ * Built-in client tools to append to a dispatch's `clientTools[]` for the
+ * given widget config: `ask_user_question` and `suggest_replies`; future
+ * built-in local tools join here.
+ *
+ * Each tool is gated on BOTH of its feature flags: `expose` opts the tool
+ * into the agent's catalog, and `enabled !== false` guarantees the widget can
+ * actually render UI (and, for fire-and-forget tools, auto-resume) for it —
+ * exposing a tool with its feature disabled would park the execution on a
+ * generic tool bubble with no way to advance.
+ */
+export const builtInClientToolsForDispatch = (
+  config: AgentWidgetConfig | undefined,
+): ClientToolDefinition[] => {
+  const tools: ClientToolDefinition[] = [];
+  const ask = config?.features?.askUserQuestion;
+  if (ask?.expose === true && ask.enabled !== false) {
+    tools.push(ASK_USER_QUESTION_CLIENT_TOOL);
+  }
+  if (shouldExposeSuggestReplies(config)) {
+    tools.push(SUGGEST_REPLIES_CLIENT_TOOL);
+  }
+  return tools;
+};

package/src/client.ts

@@ -24,6 +24,7 @@ import {
   WebMcpConfirmHandler
 } from "./types";
 import { WebMcpBridge, computeClientToolsFingerprint, isWebMcpToolName } from "./webmcp-bridge";
+import { builtInClientToolsForDispatch } from "./ask-user-question-tool";
 import {
   extractTextFromJson,
   createPlainTextParser,
@@ -201,6 +202,28 @@ export class AgentWidgetClient {
       config.webmcp?.enabled === true ? new WebMcpBridge(config.webmcp) : null;
   }
 
+  /**
+   * Refresh config in place WITHOUT tearing down the live connection or the
+   * WebMCP bridge. `AgentWidgetSession.updateConfig` calls this when only
+   * connection-irrelevant fields changed (theme, copy, layout, suggestions, …),
+   * so a UI update that lands mid-turn — e.g. a `webmcp:*` tool restyling the
+   * widget while the agent's turn is still streaming — doesn't abandon the
+   * in-flight stream/resume. Connection or request-shaping changes (apiUrl,
+   * clientToken, webmcp, headers, parser, …) take the full client rebuild path
+   * in the session instead, which is the only place the bridge is recreated.
+   *
+   * Only the live-read `config` is refreshed (e.g. `iterationDisplay`); the
+   * constructor-derived request-shaping fields (apiUrl, headers, parser,
+   * contextProviders, middleware, …) are left untouched because the session
+   * routes any change to those down the full-rebuild path instead — so they are
+   * guaranteed unchanged here. The `webMcpBridge` instance and its
+   * installed-polyfill memo are deliberately preserved, which keeps any
+   * in-flight resolve alive.
+   */
+  public updateConfig(next: AgentWidgetConfig): void {
+    this.config = next;
+  }
+
   /**
    * Set callback for capturing raw SSE events
    */
@@ -1035,11 +1058,18 @@ export class AgentWidgetClient {
       }
     };
 
-    // WebMCP: snapshot the page tool registry per turn and ship as
-    // `clientTools[]`. The server merges these under the `webmcp:` namespace.
-    const webMcpSnapshot = await this.webMcpBridge?.snapshotForDispatch();
-    if (webMcpSnapshot && webMcpSnapshot.length > 0) {
-      payload.clientTools = webMcpSnapshot;
+    // Client tools: built-in widget tools (ask_user_question, when exposed)
+    // plus the per-turn WebMCP page-registry snapshot. Name collisions are
+    // impossible — WebMCP entries are `webmcp:`-prefixed server-side while
+    // `sdk`-origin built-ins keep bare names. Both kinds ride the same
+    // diff-only fingerprint path in client-token mode. Kept to a single await
+    // so dispatch microtask timing is unchanged.
+    const clientTools = [
+      ...builtInClientToolsForDispatch(this.config),
+      ...((await this.webMcpBridge?.snapshotForDispatch()) ?? []),
+    ];
+    if (clientTools.length > 0) {
+      payload.clientTools = clientTools;
     }
 
     // Add context from providers
@@ -1096,10 +1126,14 @@ export class AgentWidgetClient {
       ...(this.config.flowId && { flowId: this.config.flowId })
     };
 
-    // WebMCP: same per-turn snapshot as buildAgentPayload (flow-dispatch path).
-    const webMcpSnapshot = await this.webMcpBridge?.snapshotForDispatch();
-    if (webMcpSnapshot && webMcpSnapshot.length > 0) {
-      payload.clientTools = webMcpSnapshot;
+    // Client tools: same built-in + WebMCP merge as buildAgentPayload
+    // (flow-dispatch path).
+    const clientTools = [
+      ...builtInClientToolsForDispatch(this.config),
+      ...((await this.webMcpBridge?.snapshotForDispatch()) ?? []),
+    ];
+    if (clientTools.length > 0) {
+      payload.clientTools = clientTools;
     }
 
     if (this.contextProviders.length) {

package/src/components/messages.ts

@@ -9,6 +9,7 @@ import {
   isAskUserQuestionMessage,
   removeAskUserQuestionSheet,
 } from "./ask-user-question-bubble";
+import { isSuggestRepliesMessage } from "../suggest-replies-tool";
 
 export const renderMessages = (
   container: HTMLElement,
@@ -40,6 +41,15 @@ export const renderMessages = (
         ensureAskUserQuestionSheet(message, config, composerOverlay ?? null);
       }
       return;
+    } else if (
+      isSuggestRepliesMessage(message) &&
+      config?.features?.suggestReplies?.enabled !== false
+    ) {
+      // No transcript bubble — the chips above the composer are the only UI.
+      // When the feature is disabled the message falls through to the generic
+      // tool bubble below (and is never auto-resumed), making the parked
+      // execution visible instead of silently swallowed.
+      return;
     } else if (message.variant === "tool" && message.toolCall) {
       if (!showToolCalls) return;
       bubble = createToolBubble(message, config);

package/src/components/suggestions.ts

@@ -9,29 +9,50 @@ export interface SuggestionButtons {
     session: AgentWidgetSession,
     textarea: HTMLTextAreaElement,
     messages?: AgentWidgetMessage[],
-    config?: AgentWidgetSuggestionChipsConfig
+    config?: AgentWidgetSuggestionChipsConfig,
+    opts?: SuggestionRenderOptions
   ) => void;
 }
 
+export interface SuggestionRenderOptions {
+  /**
+   * Chips pushed by the agent's `suggest_replies` tool rather than the
+   * static `suggestionChips` config. Skips the before-first-user-message
+   * gate (the caller already applied the latest-turn visibility rule) and
+   * dispatches `persona:suggestReplies:*` DOM events.
+   */
+  agentPushed?: boolean;
+}
+
 export const createSuggestions = (container: HTMLElement): SuggestionButtons => {
   const suggestionButtons: HTMLButtonElement[] = [];
+  // render() runs on every message change; only announce agent-pushed chips
+  // when the visible set actually changes, not on each re-render pass.
+  let lastAgentShownKey: string | null = null;
 
   const render = (
     chips: string[] | undefined,
     session: AgentWidgetSession,
     textarea: HTMLTextAreaElement,
     messages?: AgentWidgetMessage[],
-    chipsConfig?: AgentWidgetSuggestionChipsConfig
+    chipsConfig?: AgentWidgetSuggestionChipsConfig,
+    opts?: SuggestionRenderOptions
   ) => {
     container.innerHTML = "";
     suggestionButtons.length = 0;
+    const agentPushed = opts?.agentPushed === true;
+    if (!agentPushed) lastAgentShownKey = null;
     if (!chips || !chips.length) return;
 
-    // Hide suggestions after the first user message is sent
+    // Hide config suggestions after the first user message is sent.
+    // Agent-pushed chips skip this gate — their visibility is the caller's
+    // latest-turn rule (last suggest_replies call with no user message after).
     // Use provided messages or get from session
-    const messagesToCheck = messages ?? (session ? session.getMessages() : []);
-    const hasUserMessage = messagesToCheck.some((msg) => msg.role === "user");
-    if (hasUserMessage) return;
+    if (!agentPushed) {
+      const messagesToCheck = messages ?? (session ? session.getMessages() : []);
+      const hasUserMessage = messagesToCheck.some((msg) => msg.role === "user");
+      if (hasUserMessage) return;
+    }
 
     const fragment = document.createDocumentFragment();
     const streaming = session ? session.isStreaming() : false;
@@ -79,12 +100,34 @@ export const createSuggestions = (container: HTMLElement): SuggestionButtons =>
       btn.addEventListener("click", () => {
         if (!session || session.isStreaming()) return;
         textarea.value = "";
+        if (agentPushed) {
+          container.dispatchEvent(
+            new CustomEvent("persona:suggestReplies:selected", {
+              detail: { suggestion: chip },
+              bubbles: true,
+              composed: true,
+            })
+          );
+        }
         session.sendMessage(chip);
       });
       fragment.appendChild(btn);
       suggestionButtons.push(btn);
     });
     container.appendChild(fragment);
+    if (agentPushed) {
+      const shownKey = JSON.stringify(chips);
+      if (shownKey !== lastAgentShownKey) {
+        lastAgentShownKey = shownKey;
+        container.dispatchEvent(
+          new CustomEvent("persona:suggestReplies:shown", {
+            detail: { suggestions: [...chips] },
+            bubbles: true,
+            composed: true,
+          })
+        );
+      }
+    }
   };
 
   return {

package/src/index-core.ts

@@ -134,6 +134,21 @@ export {
   parseAskUserQuestionPayload
 } from "./components/ask-user-question-bubble";
 
+export {
+  ASK_USER_QUESTION_CLIENT_TOOL,
+  ASK_USER_QUESTION_PARAMETERS_SCHEMA,
+  builtInClientToolsForDispatch
+} from "./ask-user-question-tool";
+
+export {
+  SUGGEST_REPLIES_TOOL_NAME,
+  SUGGEST_REPLIES_CLIENT_TOOL,
+  SUGGEST_REPLIES_PARAMETERS_SCHEMA,
+  isSuggestRepliesMessage,
+  parseSuggestRepliesPayload,
+  latestAgentSuggestions
+} from "./suggest-replies-tool";
+
 export { initAgentWidgetFn as initAgentWidget };
 export {
   createWidgetHostLayout,