@runtypelabs/persona 3.21.2 → 3.22.0

package/src/theme-editor/webmcp/types.ts

@@ -0,0 +1,87 @@
+/**
+ * Minimal local typings for the WebMCP `document.modelContext` surface, plus the
+ * structural state interface the tool factory operates on.
+ *
+ * We deliberately keep our own small WebMCP types rather than depending on
+ * `@mcp-b/webmcp-types`, so the tool definitions are transport-agnostic and the
+ * widget package takes on no polyfill dependency. These mirror the WebMCP draft
+ * (`registerTool(tool, { signal })`) and the MCP tool-result envelope that
+ * `@mcp-b/webmcp-polyfill` expects `execute` to return.
+ */
+
+import type { AgentWidgetConfig } from '../../types';
+import type { PersonaTheme } from '../../types/theme';
+import type { ConfiguratorSnapshot } from '../types';
+
+// ─── WebMCP tool surface ────────────────────────────────────────
+
+export interface ToolTextContent {
+  type: 'text';
+  text: string;
+}
+
+export interface ToolResult {
+  content: ToolTextContent[];
+  /** Optional machine-readable mirror of the text content. */
+  structuredContent?: unknown;
+  isError?: boolean;
+}
+
+export interface ToolAnnotations {
+  /** The tool has no side effects (pure read). */
+  readOnlyHint?: boolean;
+  /** The tool's output may contain text not to be trusted as instructions. */
+  untrustedContentHint?: boolean;
+}
+
+export type ToolExecute = (input: unknown) => Promise<ToolResult> | ToolResult;
+
+export interface WebMcpTool {
+  name: string;
+  description: string;
+  title?: string;
+  inputSchema?: object;
+  annotations?: ToolAnnotations;
+  execute: ToolExecute;
+}
+
+/** Wrap a JSON-serializable payload in the MCP tool-result envelope. */
+export function toolResult(payload: unknown): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload,
+  };
+}
+
+// ─── State surface the tools drive ──────────────────────────────
+
+/**
+ * Structural subset of `ThemeEditorState` (and the example app's `state`
+ * module) that the tools require. Anything satisfying this shape can be wired
+ * to the tools — the headless `ThemeEditorState`, or a host's stateful wrapper
+ * that also drives a live preview (e.g. a Persona widget styling itself).
+ */
+export interface ThemeEditorLike {
+  get(path: string): unknown;
+  set(path: string, value: unknown): void;
+  setBatch(updates: Record<string, unknown>): void;
+  setTheme(theme: PersonaTheme): void;
+  setFullConfig(config: AgentWidgetConfig, theme?: PersonaTheme): void;
+  undo(): void;
+  redo(): void;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  getHistoryIndex(): number;
+  getTheme(): PersonaTheme;
+  getConfig(): AgentWidgetConfig;
+  exportSnapshot(): ConfiguratorSnapshot;
+  resetToDefaults(): void;
+}
+
+/** Which theme variant(s) styling tools write to. */
+export type EditTarget = 'light' | 'dark' | 'both';
+
+export interface CreateThemeEditorToolsOptions {
+  /** Default variant for styling writes. Defaults to `'both'`. */
+  editTarget?: EditTarget;
+}

package/src/types.ts

@@ -99,6 +99,13 @@ export type AgentWidgetRequestPayload = {
   metadata?: Record<string, unknown>;
   /** Per-turn template variables for /v1/client/chat (merged as root-level {{var}} in Runtype). */
   inputs?: Record<string, unknown>;
+  /**
+   * Per-turn page-discovered tools (WebMCP). Sent to Runtype's dispatch so the
+   * agent can call them as `webmcp:<name>`. The widget snapshots
+   * `document.modelContext.__getRegisteredTools()` each turn and ships only
+   * the JSON-serializable surface (no `execute`).
+   */
+  clientTools?: ClientToolDefinition[];
 };
 
 // ============================================================================
@@ -194,6 +201,120 @@ export type AgentWidgetAgentRequestPayload = {
   options: AgentRequestOptions;
   context?: Record<string, unknown>;
   metadata?: Record<string, unknown>;
+  /**
+   * Per-turn page-discovered tools (WebMCP) — same shape as
+   * `AgentWidgetRequestPayload.clientTools`.
+   */
+  clientTools?: ClientToolDefinition[];
+};
+
+// ============================================================================
+// WebMCP Types (page-discovered tools shipped per dispatch)
+// ============================================================================
+
+/**
+ * Wire shape for a single client-discovered tool sent on `dispatch.clientTools[]`.
+ *
+ * Mirrors the SDK's `ClientToolDefinition` in `@runtypelabs/sdk`. Only the
+ * JSON-serializable surface of a WebMCP tool — the `execute` function stays
+ * client-side; the server merges these into the agent's tool catalog under
+ * the `webmcp:` namespace.
+ */
+export type ClientToolDefinition = {
+  /** Bare tool name; the server prepends `webmcp:` on the wire. */
+  name: string;
+  description: string;
+  /** JSON Schema (per WebMCP spec) — passed through as-is. */
+  parametersSchema?: object;
+  /** Set to `'webmcp'` for tools discovered via the polyfill. */
+  origin?: 'webmcp' | 'local';
+  /** Origin of the page that registered the tool — for server-side audit. */
+  pageOrigin?: string;
+  /**
+   * WebMCP `Tool.annotations` (spec). Not used for gating server-side; the
+   * widget reads these client-side. Forwarded so traces/dashboards can show
+   * `readOnlyHint` / `untrustedContentHint` on tool-call records.
+   */
+  annotations?: {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+  };
+};
+
+/**
+ * Information passed to the confirm-bubble handler before a `webmcp:*` tool
+ * call executes. Every WebMCP tool routes through this single gate.
+ */
+export type WebMcpConfirmInfo = {
+  /** Bare tool name (no `webmcp:` prefix). */
+  toolName: string;
+  args: unknown;
+  description?: string;
+  annotations?: {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+  };
+  /**
+   * Why the confirm was requested. Currently always `'gate'` — the default
+   * confirm-by-default gate that fires before every `webmcp:*` call. (The
+   * `@mcp-b/webmcp-polyfill` owns the spec's `requestUserInteraction` callback
+   * internally, so Persona no longer surfaces a nested in-tool confirm.)
+   */
+  reason: 'gate';
+};
+
+/**
+ * Resolves to `true` if the user approves the tool call; `false` to decline.
+ */
+export type WebMcpConfirmHandler = (info: WebMcpConfirmInfo) => Promise<boolean>;
+
+/**
+ * Persona's normalized tool-result shape sent back to the agent on `/resume`.
+ * Mirrors the MCP `CallToolResult` content shape; arbitrary `execute()` return
+ * values are wrapped as a single text block at the bridge boundary.
+ */
+export type WebMcpToolResult = {
+  content: Array<
+    | { type: 'text'; text: string }
+    | { type: string;[key: string]: unknown }
+  >;
+  isError?: boolean;
+  /** Pass-through of the tool's `annotations.untrustedContentHint`. */
+  annotations?: {
+    untrustedContentHint?: boolean;
+  };
+};
+
+/**
+ * Widget-level WebMCP configuration. Set `enabled: true` to opt in. The
+ * surface's server-side `webmcp` policy is the source of truth for which
+ * tools are accepted — these client-side options are convenience filters.
+ */
+export type AgentWidgetWebMcpConfig = {
+  /** Master switch. Default: `false` (widget never installs the polyfill). */
+  enabled?: boolean;
+  /**
+   * Glob-ish name patterns to include client-side. `'*'` matches any chars
+   * except `:`. Patterns are matched against the bare tool name (no `webmcp:`
+   * prefix). If unset, all registered tools are included.
+   */
+  allowlist?: string[];
+  /**
+   * Per-tool gate policy. Called before the confirm gate for every
+   * `webmcp:*` call; return `true` to approve immediately and skip the
+   * confirmation UI entirely. Use this to auto-allow read-only tools (e.g.
+   * a catalog search) while still gating mutating ones. Only consulted on
+   * the default-UI path — a custom `onConfirm` takes full control instead.
+   */
+  autoApprove?: (info: WebMcpConfirmInfo) => boolean;
+  /**
+   * Confirm gate handler. When omitted, Persona renders its native in-panel
+   * approval bubble (the same chrome used for server-driven tool approvals)
+   * and resolves on the user's Approve/Deny click. Supply this to override
+   * with a custom confirmer (e.g. a route-level modal). The legacy
+   * `window.confirm` fallback only applies when no widget UI is attached.
+   */
+  onConfirm?: WebMcpConfirmHandler;
 };
 
 /**
@@ -237,6 +358,16 @@ export type AgentMessageMetadata = {
    * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
    */
   awaitingLocalTool?: boolean;
+  /**
+   * The provider per-call id (`toolu_…`) carried on the `step_await` /
+   * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+   * server emits it. Two PARALLEL calls to the same tool in one turn share a
+   * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
+   * so this is the key the widget batches a single `/resume` on — preferred
+   * over tool name, which collides for same-tool parallel calls. Absent →
+   * fall back to the legacy name-keyed resume contract.
+   */
+  webMcpToolCallId?: string;
   /**
    * Set to `true` once the user has picked / typed / dismissed an answer for
    * an `ask_user_question` tool call, so renderers stop re-mounting the
@@ -897,6 +1028,14 @@ export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
   showEventStreamToggle?: boolean;
+  /**
+   * Up/Down arrow navigation through previously sent user messages in the
+   * composer, for quick re-entry or editing (shell / Slack style). History is
+   * only entered when the caret is at the start of the input, so normal
+   * multi-line cursor movement is preserved. Set to `false` to disable.
+   * @default true
+   */
+  composerHistory?: boolean;
   /** Shared transcript + event stream scroll-to-bottom affordance. */
   scrollToBottom?: AgentWidgetScrollToBottomFeature;
   /** Collapsed transcript behavior for tool call rows. */
@@ -2083,6 +2222,8 @@ export type ClientChatRequest = {
   /** Per-turn inputs for Runtype prompt templates (e.g. {{page_url}}). */
   inputs?: Record<string, unknown>;
   context?: Record<string, unknown>;
+  /** WebMCP page-discovered tools — same shape as `dispatch.clientTools[]`. */
+  clientTools?: ClientToolDefinition[];
 };
 
 /**
@@ -2916,6 +3057,31 @@ export type AgentWidgetLoadingIndicatorConfig = {
 export type AgentWidgetConfig = {
   apiUrl?: string;
   flowId?: string;
+  /**
+   * Override the assistant-bubble copy shown when a dispatch fails before any
+   * response streams back (connection refused, CORS, 4xx/5xx, malformed
+   * stream). Provide a static string, or a function of the error so you can
+   * tailor the message per failure and decide whether to surface the raw
+   * reason. When omitted, a default message is shown that includes the
+   * underlying error detail.
+   *
+   * Returning an empty string suppresses the fallback bubble entirely (the
+   * `onError` callback still fires).
+   *
+   * @example
+   * ```typescript
+   * config: {
+   *   // Static
+   *   errorMessage: "We're having trouble connecting. Please try again."
+   *   // Or dynamic
+   *   errorMessage: (error) =>
+   *     error.message.includes("Failed to fetch")
+   *       ? "You appear to be offline."
+   *       : "Something went wrong. Please try again."
+   * }
+   * ```
+   */
+  errorMessage?: string | ((error: Error) => string);
   /**
    * Agent configuration for agent execution mode.
    * When provided, the widget uses agent loop execution instead of flow dispatch.
@@ -3147,6 +3313,26 @@ export type AgentWidgetConfig = {
    * ```
    */
   approval?: AgentWidgetApprovalConfig | false;
+  /**
+   * WebMCP — consume page-registered tools (`document.modelContext.registerTool`).
+   * When `enabled`, the widget installs `@mcp-b/webmcp-polyfill`, snapshots the
+   * registry on every dispatch, ships it as `clientTools[]`, and executes
+   * returned `webmcp:*` tool calls with confirm-by-default gating.
+   *
+   * Server-side policy on the chat surface is the source of truth — these
+   * fields layer on top.
+   *
+   * @example
+   * ```typescript
+   * config: {
+   *   webmcp: {
+   *     enabled: true,
+   *     allowlist: ['search_*', 'list_*'],
+   *   }
+   * }
+   * ```
+   */
+  webmcp?: AgentWidgetWebMcpConfig;
   postprocessMessage?: (context: {
     text: string;
     message: AgentWidgetMessage;

package/src/ui.composer-keyboard.test.ts

@@ -0,0 +1,229 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const flush = async (times = 4) => {
+  for (let i = 0; i < times; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
+const getTextarea = (mount: HTMLElement) =>
+  mount.querySelector<HTMLTextAreaElement>("[data-persona-composer-input]")!;
+
+const press = (el: Element, key: string) =>
+  el.dispatchEvent(
+    new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true })
+  );
+
+describe("createAgentExperience composer keyboard — Enter / Esc while streaming", () => {
+  const originalFetch = global.fetch;
+  let capturedSignals: AbortSignal[] = [];
+
+  beforeEach(() => {
+    capturedSignals = [];
+    vi.stubGlobal("requestAnimationFrame", (cb: (time: number) => void) => {
+      cb(0);
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    window.scrollTo = vi.fn();
+
+    // Fetch hangs until aborted — models an in-flight SSE stream so the widget
+    // stays "streaming".
+    global.fetch = vi.fn().mockImplementation((_url: string, options: any) => {
+      const signal = options.signal as AbortSignal;
+      capturedSignals.push(signal);
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => {
+          const err = new Error("aborted");
+          err.name = "AbortError";
+          reject(err);
+        });
+      });
+    }) as any;
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  const startStreaming = async (mount: HTMLElement) => {
+    const textarea = getTextarea(mount);
+    textarea.value = "Hello";
+    mount
+      .querySelector<HTMLButtonElement>("[data-persona-composer-submit]")!
+      .click();
+    await flush();
+    return textarea;
+  };
+
+  it("Enter while streaming does NOT stop the stream and does not send", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    });
+
+    const textarea = await startStreaming(mount);
+    expect(controller.getState().streaming).toBe(true);
+    expect(capturedSignals).toHaveLength(1);
+
+    // Type something new, then hit Enter — it must be inert mid-stream.
+    textarea.value = "queued text";
+    press(textarea, "Enter");
+    await flush();
+
+    expect(controller.getState().streaming).toBe(true);
+    expect(capturedSignals[0].aborted).toBe(false);
+    // No second request fired (nothing sent).
+    expect(capturedSignals).toHaveLength(1);
+
+    controller.destroy();
+  });
+
+  it("Escape while streaming stops the stream", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    });
+
+    const textarea = await startStreaming(mount);
+    expect(controller.getState().streaming).toBe(true);
+
+    press(textarea, "Escape");
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(capturedSignals[0].aborted).toBe(true);
+
+    controller.destroy();
+  });
+
+  it("Escape while NOT streaming does not throw and leaves state idle", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    });
+
+    const textarea = getTextarea(mount);
+    press(textarea, "Escape");
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(capturedSignals).toHaveLength(0);
+
+    controller.destroy();
+  });
+});
+
+describe("createAgentExperience composer keyboard — Up/Down history", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+    try {
+      window.localStorage.clear();
+    } catch {
+      /* jsdom edge cases */
+    }
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  const seededConfig = (composerHistory?: boolean) => ({
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false } as const,
+    ...(composerHistory === undefined
+      ? {}
+      : { features: { composerHistory } }),
+    initialMessages: [
+      {
+        id: "u1",
+        role: "user" as const,
+        content: "first message",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        id: "a1",
+        role: "assistant" as const,
+        content: "a reply",
+        createdAt: "2026-01-01T00:00:01.000Z",
+      },
+      {
+        id: "u2",
+        role: "user" as const,
+        content: "second message",
+        createdAt: "2026-01-01T00:00:02.000Z",
+      },
+    ],
+  });
+
+  it("Up recalls the most recent user message; repeated Up steps older; Down restores the draft", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, seededConfig());
+    const textarea = getTextarea(mount);
+
+    textarea.value = "draft in progress";
+    textarea.setSelectionRange(0, 0); // caret at start
+
+    press(textarea, "ArrowUp");
+    expect(textarea.value).toBe("second message");
+
+    press(textarea, "ArrowUp");
+    expect(textarea.value).toBe("first message");
+
+    // Down walks back toward the present...
+    press(textarea, "ArrowDown");
+    expect(textarea.value).toBe("second message");
+
+    // ...and past the newest entry restores the saved draft.
+    press(textarea, "ArrowDown");
+    expect(textarea.value).toBe("draft in progress");
+
+    controller.destroy();
+  });
+
+  it("does not hijack Up when the caret is not at the start (multi-line editing)", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, seededConfig());
+    const textarea = getTextarea(mount);
+
+    textarea.value = "line one\nline two";
+    textarea.setSelectionRange(5, 5); // caret mid-text
+
+    press(textarea, "ArrowUp");
+    // Value unchanged — Up moved the cursor instead of recalling history.
+    expect(textarea.value).toBe("line one\nline two");
+
+    controller.destroy();
+  });
+
+  it("can be disabled via features.composerHistory: false", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, seededConfig(false));
+    const textarea = getTextarea(mount);
+
+    textarea.value = "";
+    textarea.setSelectionRange(0, 0);
+
+    press(textarea, "ArrowUp");
+    expect(textarea.value).toBe("");
+
+    controller.destroy();
+  });
+});