@runtypelabs/persona 3.21.3 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.21.3",
+  "version": "3.23.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",
@@ -27,6 +27,11 @@
       "import": "./dist/testing.js",
       "require": "./dist/testing.cjs"
     },
+    "./smart-dom-reader": {
+      "types": "./dist/smart-dom-reader.d.ts",
+      "import": "./dist/smart-dom-reader.js",
+      "require": "./dist/smart-dom-reader.cjs"
+    },
     "./animations/glyph-cycle": {
       "types": "./dist/animations/glyph-cycle.d.ts",
       "import": "./dist/animations/glyph-cycle.js",
@@ -44,6 +49,7 @@
     "src"
   ],
   "dependencies": {
+    "@mcp-b/webmcp-polyfill": "^3.0.0",
     "dompurify": "^3.3.3",
     "idiomorph": "^0.7.4",
     "lucide": "^0.552.0",
@@ -52,6 +58,7 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@size-limit/file": "^12.1.0",
     "@types/node": "^20.12.7",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
@@ -60,6 +67,7 @@
     "eslint-config-prettier": "^9.1.0",
     "fake-indexeddb": "^6.2.5",
     "rimraf": "^5.0.5",
+    "size-limit": "^12.1.0",
     "tsup": "^8.0.1",
     "typescript": "^5.4.5",
     "vitest": "^4.0.9"
@@ -91,10 +99,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:theme-ref && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:animations",
-    "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:testing": "tsup src/testing.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --dts --out-dir dist/animations --no-splitting",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:theme-ref && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:animations",
+    "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:testing": "tsup src/testing.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --minify --dts --out-dir dist/animations --no-splitting",
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:styles": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/styles/widget.css','dist/widget.css');\"",
     "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup src/index-global.ts --format iife --global-name AgentWidget --minify --sourcemap --splitting false --out-dir dist --loader \".css=text\" && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
@@ -103,6 +112,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:ui": "vitest --ui",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "size": "size-limit"
   }
 }

package/src/client.test.ts

@@ -3083,6 +3083,92 @@ describe('AgentWidgetClient.resumeFlow', () => {
 
     expect(capturedUrl).toBe('http://localhost:43111/api/chat/dispatch/resume');
   });
+
+  it('routes to /v1/client/resume with sessionId in client-token mode (core#3889)', async () => {
+    let capturedUrl: string | undefined;
+    let capturedBody: Record<string, unknown> | undefined;
+    let capturedHeaders: Record<string, string> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
+      capturedUrl = url;
+      capturedBody = JSON.parse(init.body as string);
+      capturedHeaders = init.headers as Record<string, string>;
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com',
+    });
+    // Simulate an initialized client session (resumeFlow reads sessionId off it).
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: 'cs_123',
+      expiresAt: new Date(Date.now() + 60_000),
+    };
+
+    await client.resumeFlow('exec_xyz', { toolu_A: { ok: true } });
+
+    // Session-authed sibling of /v1/client/chat — no Bearer key, sessionId in body.
+    expect(capturedUrl).toBe('https://api.runtype-staging.com/v1/client/resume');
+    expect(capturedBody).toEqual({
+      executionId: 'exec_xyz',
+      toolOutputs: { toolu_A: { ok: true } },
+      streamResponse: true,
+      sessionId: 'cs_123',
+    });
+    expect(capturedHeaders!['Authorization']).toBeUndefined();
+  });
+
+  it('strips a trailing /v1/dispatch from apiUrl when building the client resume URL', async () => {
+    let capturedUrl: string | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string) => {
+      capturedUrl = url;
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com/v1/dispatch',
+    });
+    // A live session so initSession() short-circuits instead of fetching /init.
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: 'cs_123',
+      expiresAt: new Date(Date.now() + 60_000),
+    };
+    await client.resumeFlow('exec_abc', {});
+
+    expect(capturedUrl).toBe('https://api.runtype-staging.com/v1/client/resume');
+  });
+
+  it('refreshes the session via initSession() before resuming when stale (BugBot r3367875360)', async () => {
+    let capturedBody: Record<string, unknown> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, init: RequestInit) => {
+      capturedBody = JSON.parse(init.body as string);
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com',
+    });
+    // A stale session that has already expired — a long WebMCP approval wait can
+    // outlive it, so resumeFlow must not trust this.clientSession directly.
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: 'cs_stale',
+      expiresAt: new Date(Date.now() - 60_000),
+    };
+    // initSession() is the single source of truth for a live session (it returns
+    // the existing one while unexpired, else re-inits). Assert resumeFlow awaits
+    // it and sends the refreshed sessionId, not the stale one.
+    const initSpy = vi
+      .spyOn(client, 'initSession')
+      .mockResolvedValue({ sessionId: 'cs_fresh', expiresAt: new Date(Date.now() + 60_000) } as never);
+
+    await client.resumeFlow('exec_xyz', { toolu_A: { ok: true } });
+
+    expect(initSpy).toHaveBeenCalledTimes(1);
+    expect(capturedBody!.sessionId).toBe('cs_fresh');
+    expect(capturedBody!.sessionId).not.toBe('cs_stale');
+  });
 });
 
 // ============================================================================
@@ -3606,3 +3692,82 @@ describe('AgentWidgetClient - agent_media events', () => {
   });
 });
 
+describe('AgentWidgetClient - requestMiddleware preserves clientTools', () => {
+  it('preserves clientTools when middleware returns a payload that omits it', async () => {
+    // Iter-10 MED: naive middleware that rebuilds the payload by listing
+    // only the fields it cares about used to drop the WebMCP clientTools
+    // snapshot. Preserve them as a fallback when the middleware-returned
+    // object doesn't mention clientTools at all.
+    let capturedBody: string | null = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: { body: string }) => {
+      capturedBody = 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' } });
+    });
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      requestMiddleware: ({ payload }) => ({
+        // Naive middleware: rebuild without acknowledging clientTools.
+        messages: payload.messages,
+      }),
+    });
+    // Force a populated clientTools snapshot by stubbing the bridge spot.
+    (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } | null })
+      .webMcpBridge = {
+        snapshotForDispatch: () => [
+          { name: 'search', description: 's', origin: 'webmcp' },
+        ],
+      };
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      () => undefined,
+    );
+    expect(capturedBody).not.toBeNull();
+    const parsed = JSON.parse(capturedBody!);
+    expect(parsed.clientTools).toEqual([
+      { name: 'search', description: 's', origin: 'webmcp' },
+    ]);
+  });
+
+  it("respects middleware that explicitly sets clientTools (even to undefined)", async () => {
+    // The fallback only triggers when `clientTools` is entirely absent from
+    // the middleware result. An integrator who sets `clientTools: undefined`
+    // explicitly is opting out and must be respected.
+    let capturedBody: string | null = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: { body: string }) => {
+      capturedBody = 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' } });
+    });
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      requestMiddleware: ({ payload }) => ({
+        messages: payload.messages,
+        clientTools: undefined,
+      }),
+    });
+    (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } | null })
+      .webMcpBridge = {
+        snapshotForDispatch: () => [{ name: 'search', description: 's', origin: 'webmcp' }],
+      };
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      () => undefined,
+    );
+    const parsed = JSON.parse(capturedBody!);
+    expect(parsed.clientTools).toBeUndefined();
+  });
+});
+

package/src/client.ts

@@ -20,8 +20,10 @@ import {
   ClientFeedbackRequest,
   ClientFeedbackType,
   PersonaArtifactKind,
-  ContentPart
+  ContentPart,
+  WebMcpConfirmHandler
 } from "./types";
+import { WebMcpBridge } from "./webmcp-bridge";
 import {
   extractTextFromJson,
   createPlainTextParser,
@@ -169,6 +171,10 @@ export class AgentWidgetClient {
   private clientSession: ClientSession | null = null;
   private sessionInitPromise: Promise<ClientSession> | null = null;
 
+  // WebMCP — page-discovered tool consumption (see ./webmcp-bridge).
+  // Constructed lazily: null when `config.webmcp?.enabled !== true`.
+  private readonly webMcpBridge: WebMcpBridge | null;
+
   constructor(private config: AgentWidgetConfig = {}) {
     this.apiUrl = config.apiUrl ?? DEFAULT_ENDPOINT;
     this.headers = {
@@ -183,6 +189,8 @@ export class AgentWidgetClient {
     this.customFetch = config.customFetch;
     this.parseSSEEvent = config.parseSSEEvent;
     this.getHeaders = config.getHeaders;
+    this.webMcpBridge =
+      config.webmcp?.enabled === true ? new WebMcpBridge(config.webmcp) : null;
   }
 
   /**
@@ -192,6 +200,44 @@ export class AgentWidgetClient {
     this.onSSEEvent = callback;
   }
 
+  /**
+   * WebMCP: wire (or replace) the confirm-bubble handler. Called from
+   * `ui.ts` once the widget panel is built and the approval-bubble
+   * chrome is ready to render.
+   */
+  public setWebMcpConfirmHandler(handler: WebMcpConfirmHandler | null): void {
+    this.webMcpBridge?.setConfirmHandler(handler);
+  }
+
+  /**
+   * WebMCP: `true` when the bridge installed the polyfill and can both
+   * snapshot the page registry and execute returned `webmcp:*` tool calls.
+   * `false` for any guard miss (no `document.modelContext`, polyfill not yet
+   * installed, or `config.webmcp.enabled` not set).
+   */
+  public isWebMcpOperational(): boolean {
+    return this.webMcpBridge?.isOperational() === true;
+  }
+
+  /**
+   * WebMCP: execute a returned `webmcp:<name>` tool call against the page's
+   * registry and return the normalized MCP-shaped result for `/resume`. The
+   * bridge handles confirm-bubble gating, the 30s timeout, error
+   * normalization, and `signal`-driven abort — callers never see throws.
+   *
+   * Returns `null` when WebMCP is not enabled on this client (signal to the
+   * session that it should fall back to the legacy local-tool resume path,
+   * if any).
+   */
+  public executeWebMcpToolCall(
+    wireToolName: string,
+    args: unknown,
+    signal?: AbortSignal,
+  ): Promise<import("./types").WebMcpToolResult> | null {
+    if (!this.webMcpBridge) return null;
+    return this.webMcpBridge.executeToolCall(wireToolName, args, signal);
+  }
+
   /**
    * Get the current SSE event callback (used to preserve across client recreation)
    */
@@ -216,11 +262,9 @@ export class AgentWidgetClient {
   /**
    * Get the appropriate API URL based on mode
    */
-  private getClientApiUrl(endpoint: 'init' | 'chat'): string {
+  private getClientApiUrl(endpoint: 'init' | 'chat' | 'resume'): string {
     const baseUrl = this.config.apiUrl?.replace(/\/+$/, '').replace(/\/v1\/dispatch$/, '') || DEFAULT_CLIENT_API_BASE;
-    return endpoint === 'init'
-      ? `${baseUrl}/v1/client/init`
-      : `${baseUrl}/v1/client/chat`;
+    return `${baseUrl}/v1/client/${endpoint}`;
   }
 
   /**
@@ -540,6 +584,9 @@ export class AgentWidgetClient {
         ...(sanitizedMetadata && Object.keys(sanitizedMetadata).length > 0 && { metadata: sanitizedMetadata }),
         ...(basePayload.inputs && Object.keys(basePayload.inputs).length > 0 && { inputs: basePayload.inputs }),
         ...(basePayload.context && { context: basePayload.context }),
+        // Forward per-turn WebMCP tools snapshotted by buildPayload(). The
+        // client-token chat endpoint accepts the same shape as /v1/dispatch.
+        ...(basePayload.clientTools && basePayload.clientTools.length > 0 && { clientTools: basePayload.clientTools }),
       };
 
       if (this.debug) {
@@ -811,24 +858,44 @@ export class AgentWidgetClient {
    * (client-executed) tools. Used by the built-in `ask_user_question`
    * answer-pill sheet, but generic enough for any LOCAL tool.
    *
-   * Posts to the upstream `/resume` endpoint (the dispatch URL with
-   * `/dispatch` replaced by `/resume` — works for both direct-to-Runtype
-   * and the persona proxy) and returns the raw Response so the caller can
-   * pipe its SSE body through `connectStream()`.
+   * Routes by mode:
+   *  - **client-token mode**: POST `${apiBase}/v1/client/resume` (the
+   *    session-authenticated sibling of `/v1/client/chat`; runtypelabs/core#3889),
+   *    with the active `sessionId` in the body and no Bearer key — a browser
+   *    client-token page holds no secret. `clientTools` are already persisted
+   *    server-side from the dispatch turn, so only `toolOutputs` is re-sent.
+   *  - **dispatch / proxy mode**: POST `${apiUrl}/resume` — Runtype mounts
+   *    resume as a child of `/v1/dispatch`, so the URL is `${apiUrl}/resume`,
+   *    and proxies follow the same shape (`/api/chat/dispatch/resume`).
+   *
+   * Returns the raw Response so the caller can pipe its SSE body through
+   * `connectStream()`.
    *
    * @param executionId - The paused execution id carried on `step_await`.
-   * @param toolOutputs - Map keyed by tool name → the tool's result value.
+   * @param toolOutputs - Map keyed by per-call `toolCallId` (core#3878),
+   *   falling back to tool name for legacy servers → the tool's result value.
    */
   public async resumeFlow(
     executionId: string,
     toolOutputs: Record<string, unknown>,
-    options?: { streamResponse?: boolean }
+    options?: { streamResponse?: boolean; signal?: AbortSignal }
   ): Promise<Response> {
-    const trimmed = this.config.apiUrl?.replace(/\/+$/, '') || DEFAULT_CLIENT_API_BASE;
-    // Runtype mounts POST /resume as a child route of /v1/dispatch, so the
-    // final URL is always `${apiUrl}/resume`. Proxies should follow the
-    // same shape (`/api/chat/dispatch/resume`) to keep the widget agnostic.
-    const url = `${trimmed}/resume`;
+    const isClientToken = this.isClientTokenMode();
+    const url = isClientToken
+      ? this.getClientApiUrl('resume')
+      : `${this.config.apiUrl?.replace(/\/+$/, '') || DEFAULT_CLIENT_API_BASE}/resume`;
+
+    // The client-token resume route authenticates the session, not a Bearer
+    // key. A WebMCP approval can sit awaiting user input for a long time, so by
+    // the time we resume the original session may have expired. Re-validate (and
+    // silently re-init if needed) via initSession() — which returns the live
+    // session when `new Date() < expiresAt`, else mints a fresh one — instead of
+    // trusting the possibly-stale `this.clientSession`. (core#3889; BugBot
+    // PR #214 r3367875360.)
+    let resumeSessionId: string | undefined;
+    if (isClientToken) {
+      resumeSessionId = (await this.initSession()).sessionId;
+    }
 
     let headers: Record<string, string> = {
       'Content-Type': 'application/json',
@@ -838,14 +905,21 @@ export class AgentWidgetClient {
       Object.assign(headers, await this.getHeaders());
     }
 
+    const body: Record<string, unknown> = {
+      executionId,
+      toolOutputs,
+      streamResponse: options?.streamResponse ?? true,
+    };
+    // Thread the (refreshed) sessionId through like `/v1/client/chat` does.
+    if (resumeSessionId) {
+      body.sessionId = resumeSessionId;
+    }
+
     return fetch(url, {
       method: 'POST',
       headers,
-      body: JSON.stringify({
-        executionId,
-        toolOutputs,
-        streamResponse: options?.streamResponse ?? true,
-      }),
+      body: JSON.stringify(body),
+      signal: options?.signal,
     });
   }
 
@@ -883,6 +957,13 @@ 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;
+    }
+
     // Add context from providers
     if (this.contextProviders.length) {
       const contextAggregate: Record<string, unknown> = {};
@@ -937,6 +1018,12 @@ 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;
+    }
+
     if (this.contextProviders.length) {
       const contextAggregate: Record<string, unknown> = {};
       await Promise.all(
@@ -970,7 +1057,22 @@ export class AgentWidgetClient {
           config: this.config
         });
         if (result && typeof result === "object") {
-          return result as AgentWidgetRequestPayload;
+          const next = result as AgentWidgetRequestPayload;
+          // Preserve `clientTools` if the middleware returned a fresh
+          // payload object without it. Naive middlewares often rebuild
+          // the payload by listing the fields they care about and
+          // dropping `clientTools` accidentally; the WebMCP wire surface
+          // is invisible to them. The integrator can still set
+          // `clientTools: []` or `clientTools: undefined` explicitly to
+          // strip them on purpose — we only fall back when the field is
+          // entirely absent from the returned object.
+          if (
+            payload.clientTools !== undefined &&
+            !("clientTools" in next)
+          ) {
+            next.clientTools = payload.clientTools;
+          }
+          return next;
         }
       } catch (error) {
         if (typeof console !== "undefined") {
@@ -1811,7 +1913,22 @@ export class AgentWidgetClient {
           // ask_user_question bubble + sheet paths fire. Mark the message with
           // `awaitingLocalTool: true` so the UI knows to resolve via
           // resumeFlow rather than the legacy sendMessage fallback.
-          const toolId = (payload.toolId as string) ?? `local-${nextSequence()}`;
+          //
+          // Key the message by the per-call `toolCallId` (provider `toolu_…`;
+          // core#3878) when present. Two PARALLEL calls to the SAME tool in one
+          // turn collapse to an identical `toolId` (`runtime_webmcp:<name>_<ms>`)
+          // and `index: 0` — only `toolCallId` distinguishes them. Keying on it
+          // (a) keeps the two awaits as DISTINCT messages with their own args
+          // instead of the second clobbering the first, and (b) merges each
+          // await into the matching `tool_start` bubble (also keyed by
+          // `toolCallId`). Fall back to the collapsed `toolId` for legacy
+          // servers that don't emit `toolCallId`.
+          const toolCallId: string | undefined =
+            typeof payload.toolCallId === "string" && payload.toolCallId.length > 0
+              ? (payload.toolCallId as string)
+              : undefined;
+          const toolId =
+            toolCallId ?? (payload.toolId as string) ?? `local-${nextSequence()}`;
           const toolMessage = ensureToolMessage(toolId);
           const tool = toolMessage.toolCall ?? { id: toolId, status: "pending" as const };
           tool.name = payload.toolName as string;
@@ -1827,6 +1944,10 @@ export class AgentWidgetClient {
             ...toolMessage.agentMetadata,
             executionId: (payload.executionId as string) ?? toolMessage.agentMetadata?.executionId,
             awaitingLocalTool: true,
+            // Only set when the server emitted a real per-call id; its presence
+            // is what tells session.ts to batch + key `/resume` by id rather
+            // than by tool name (which can't represent two same-tool calls).
+            ...(toolCallId ? { webMcpToolCallId: toolCallId } : {}),
           };
           emitMessage(toolMessage);
         } else if (payloadType === "text_start") {