@runtypelabs/persona 3.29.1 → 3.30.0

package/src/webmcp-bridge.test.ts

@@ -27,6 +27,7 @@ vi.mock("@mcp-b/webmcp-polyfill", () => ({
 // Import AFTER vi.mock so the bridge's dynamic import resolves to the mock.
 import {
   WebMcpBridge,
+  getWebMcpToolDisplayTitle,
   isWebMcpToolName,
   stripWebMcpPrefix,
   computeClientToolsFingerprint,
@@ -39,6 +40,7 @@ type MockTool = {
   name: string;
   description?: string;
   inputSchema?: object;
+  title?: string;
   execute: (args: Record<string, unknown>, client: MockClient) => unknown;
 };
 
@@ -47,10 +49,13 @@ const registry: { tools: MockTool[] } = { tools: [] };
 /** A fake `document.modelContext` exposing the strict consumer surface. */
 const makeModelContext = () => ({
   async getTools() {
+    // Mirrors the real polyfill's getRegisteredToolInfos(): `title` is always
+    // present, "" when the tool didn't declare one; annotations are absent.
     return registry.tools.map((t) => ({
       name: t.name,
       description: t.description ?? `mock ${t.name}`,
       inputSchema: JSON.stringify(t.inputSchema ?? { type: "object" }),
+      title: t.title ?? "",
     }));
   },
   async executeTool(
@@ -199,6 +204,67 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
   });
 });
 
+describe("WebMCP display titles", () => {
+  it("records declared titles on snapshot and exposes them via getWebMcpToolDisplayTitle", async () => {
+    registry.tools = [
+      fakeTool({ name: "add_to_cart", title: "Add to Cart" }),
+      fakeTool({ name: "search_products" }),
+    ];
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBe("Add to Cart");
+    expect(getWebMcpToolDisplayTitle("webmcp:add_to_cart")).toBe("Add to Cart");
+    expect(getWebMcpToolDisplayTitle("search_products")).toBeUndefined();
+  });
+
+  it("evicts a stale title when the tool re-registers without one", async () => {
+    registry.tools = [fakeTool({ name: "add_to_cart", title: "Add to Cart" })];
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBe("Add to Cart");
+
+    registry.tools = [fakeTool({ name: "add_to_cart" })];
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBeUndefined();
+  });
+
+  it("evicts the title when the tool is removed from the registry entirely", async () => {
+    registry.tools = [
+      fakeTool({ name: "add_to_cart", title: "Add to Cart" }),
+      fakeTool({ name: "search_products", title: "Search the catalog" }),
+    ];
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBe("Add to Cart");
+
+    registry.tools = [fakeTool({ name: "search_products", title: "Search the catalog" })];
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBeUndefined();
+    expect(getWebMcpToolDisplayTitle("search_products")).toBe("Search the catalog");
+  });
+
+  it("passes the declared title to the confirm gate", async () => {
+    registry.tools = [fakeTool({ name: "add_to_cart", title: "Add to Cart" })];
+    const onConfirm = vi.fn(async () => true);
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const r = await bridge.executeToolCall("webmcp:add_to_cart", {});
+    expect(r.isError).toBeFalsy();
+    expect(onConfirm).toHaveBeenCalledWith(
+      expect.objectContaining({ toolName: "add_to_cart", title: "Add to Cart" })
+    );
+  });
+
+  it("omits title from the confirm gate when the tool didn't declare one", async () => {
+    registry.tools = [fakeTool({ name: "add_to_cart" })];
+    const onConfirm = vi.fn(async () => true);
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    await bridge.executeToolCall("webmcp:add_to_cart", {});
+    expect(onConfirm).toHaveBeenCalledWith(
+      expect.not.objectContaining({ title: expect.anything() })
+    );
+  });
+});
+
 describe("WebMcpBridge.executeToolCall", () => {
   it("returns isError when WebMCP is not enabled", async () => {
     const bridge = new WebMcpBridge({} as AgentWidgetWebMcpConfig);

package/src/webmcp-bridge.ts

@@ -66,6 +66,14 @@ interface ModelContextToolInfo {
   description: string;
   /** JSON-encoded JSON Schema for the tool's input. */
   inputSchema?: string;
+  /**
+   * Display title declared on the tool (`ToolDescriptor.title` in the WebMCP
+   * spec). The polyfill returns `""` when the tool didn't declare one. Note:
+   * `annotations` (incl. the legacy `annotations.title`) are NOT exposed on
+   * this strict consumer surface — top-level `title` is the only display-name
+   * channel available to us.
+   */
+  title?: string;
 }
 
 interface ModelContextCoreLike {
@@ -77,6 +85,43 @@ interface ModelContextCoreLike {
   ): Promise<string | null>;
 }
 
+/**
+ * Page-global map of bare tool name → declared display title
+ * (`ToolDescriptor.title`). `document.modelContext` is page-global, so a
+ * single map shared across widget/bridge instances is semantically correct.
+ * Refreshed on every registry read (`snapshotForDispatch` / `executeToolCall`)
+ * and consumed by the approval bubble's summary line via
+ * `getWebMcpToolDisplayTitle`.
+ */
+const webMcpToolDisplayTitles = new Map<string, string>();
+
+/**
+ * Record declared display titles from a fresh `getTools()` read. The map is
+ * rebuilt from scratch — callers always pass the FULL registry snapshot — so
+ * a tool that unregistered or dropped its title can't leave a stale label
+ * behind. Exported for tests; production callers are the bridge's registry
+ * reads.
+ */
+export const recordWebMcpToolDisplayTitles = (
+  infos: ModelContextToolInfo[],
+): void => {
+  webMcpToolDisplayTitles.clear();
+  for (const info of infos) {
+    const title = info.title?.trim();
+    if (title) webMcpToolDisplayTitles.set(info.name, title);
+  }
+};
+
+/**
+ * Look up the display title a page tool declared via the WebMCP spec's
+ * `ToolDescriptor.title`. Accepts wire (`webmcp:add_to_cart`) or bare
+ * (`add_to_cart`) names. Returns `undefined` when the tool didn't declare
+ * one (callers fall back to humanizing the tool name).
+ */
+export const getWebMcpToolDisplayTitle = (
+  toolName: string,
+): string | undefined => webMcpToolDisplayTitles.get(stripWebMcpPrefix(toolName));
+
 const log = {
   warn(message: string, ...rest: unknown[]): void {
     if (typeof console !== "undefined" && typeof console.warn === "function") {
@@ -220,6 +265,7 @@ export class WebMcpBridge {
       log.warn("getTools() threw — shipping an empty WebMCP snapshot.", err);
       return [];
     }
+    recordWebMcpToolDisplayTitles(infos);
 
     const pageOrigin = typeof location !== "undefined" ? location.origin : "";
 
@@ -295,6 +341,7 @@ export class WebMcpBridge {
       const message = err instanceof Error ? err.message : String(err);
       return errorResult(`Failed to read WebMCP registry: ${message}`);
     }
+    recordWebMcpToolDisplayTitles(infos);
     const info = infos.find((candidate) => candidate.name === bareName);
 
     if (!info) {
@@ -323,10 +370,12 @@ export class WebMcpBridge {
 
     // Confirm-by-default gate. Every `webmcp:*` call routes through here,
     // regardless of `annotations.readOnlyHint`.
+    const displayTitle = getWebMcpToolDisplayTitle(bareName);
     const gateInfo: WebMcpConfirmInfo = {
       toolName: bareName,
       args,
       description: info.description,
+      ...(displayTitle ? { title: displayTitle } : {}),
       reason: "gate",
     };
     if (!(await this.requestConfirm(gateInfo))) {