@runtypelabs/persona 4.21.1 → 4.22.1

package/src/utils/throughput-tracker.ts

@@ -12,7 +12,7 @@
 // then prefers exact provider usage (output tokens) when terminal events carry
 // it. A run starts when the stream starts (or lazily on the first visible
 // delta), stays "running" across intermediate step/turn completions, and only
-// finalizes on terminal `flow_complete` / `agent_complete`. Stream errors mark
+// finalizes on terminal `execution_complete`. Stream errors mark
 // the metric unavailable rather than leaving it stuck "running".
 
 export type ThroughputMetricStatus = "idle" | "running" | "complete" | "error";
@@ -47,47 +47,10 @@ interface ThroughputRunStats {
 // execution time or whole-request duration instead.
 const THROUGHPUT_MIN_DURATION_MS = 250;
 
-// Request-level lifecycle events: each marks the beginning of a NEW request.
-// The SSE tap fires for every payload type regardless of whether the client has
-// a handler for it, so any of these that the server emits starts the run with
-// an accurate `startedAt` (capturing time-to-first-token). These RESET any run
-// already in progress, so a prior stream that ended without a terminal/error
-// frame (e.g. `session.cancel()`) doesn't bleed its tokens into the next one.
-const REQUEST_START_EVENTS = new Set([
-  "flow_start",
-  "flow_run_start",
-  "agent_start",
-  "dispatch_start",
-  "run_start",
-]);
-
-// Per-step markers that fire repeatedly WITHIN a single request (a flow emits
-// one per step). These only lazily begin a run: they must never reset, or a
-// multi-step response would restart the metric between steps. If no request- or
-// step-start event is emitted, the first visible delta lazily starts the run.
-const STEP_START_EVENTS = new Set(["step_start", "execution_start"]);
-
-const VISIBLE_DELTA_EVENTS = new Set([
-  "step_delta",
-  "step_chunk",
-  "chunk",
-  "agent_turn_delta",
-]);
-
-const INTERMEDIATE_COMPLETE_EVENTS = new Set([
-  "step_complete",
-  "agent_turn_complete",
-]);
-
-const TERMINAL_COMPLETE_EVENTS = new Set(["flow_complete", "agent_complete"]);
-
-const ERROR_EVENTS = new Set([
-  "step_error",
-  "flow_error",
-  "agent_error",
-  "dispatch_error",
-  "error",
-]);
+// Execution starts reset a stale/cancelled run; step and turn starts only
+// lazily initialize it, since they can repeat within the same execution.
+const STEP_START_EVENTS = new Set(["step_start", "turn_start"]);
+const INTERMEDIATE_COMPLETE_EVENTS = new Set(["step_complete", "turn_complete"]);
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
@@ -134,91 +97,15 @@ function resolveEventType(
   return typeof payload.type === "string" ? payload.type : eventType;
 }
 
-function getTextDelta(payload: Record<string, unknown>): string {
-  if (typeof payload.text === "string") return payload.text;
-  if (typeof payload.delta === "string") return payload.delta;
-  if (typeof payload.content === "string") return payload.content;
-  if (typeof payload.chunk === "string") return payload.chunk;
-  return "";
-}
-
-/**
- * Only count visible model output.
- *
- * For `agent_turn_delta`, count only a contentType of exactly `text` as
- * visible, matching the client renderer (which appends streaming assistant
- * text only when `contentType === "text"`); `thinking`, `tool_input`, any
- * other value, and a missing contentType are ignored so throughput never
- * includes deltas the chat UI doesn't render.
- *
- * For `step_delta` / `step_chunk`, skip tool and context steps: those carry
- * tool I/O, not model-visible text: mirroring the widget's own renderer.
- */
-function isVisibleTextDelta(
-  type: string,
-  payload: Record<string, unknown>
-): boolean {
-  if (type === "step_delta" || type === "step_chunk") {
-    return payload.stepType !== "tool" && payload.executionType !== "context";
-  }
-
-  if (type !== "agent_turn_delta") return true;
-
-  const contentType =
-    typeof payload.contentType === "string"
-      ? payload.contentType
-      : typeof payload.content_type === "string"
-        ? payload.content_type
-        : undefined;
-
-  return contentType === "text";
-}
-
-/** Extract exact output tokens from a variety of usage payload shapes. */
+/** Exact output counts are carried by turn and execution completions. */
 function getOutputTokens(payload: Record<string, unknown>): number | undefined {
-  const result = getRecord(payload, "result");
-  const candidates = [
-    getRecord(payload, "tokens"),
-    getRecord(payload, "totalTokens"),
-    result ? getRecord(result, "tokens") : undefined,
-    getRecord(payload, "usage"),
-    result ? getRecord(result, "usage") : undefined,
-  ];
-
-  for (const candidate of candidates) {
-    if (!candidate) continue;
-    const outputTokens =
-      toFiniteNumber(candidate.output) ??
-      toFiniteNumber(candidate.outputTokens) ??
-      toFiniteNumber(candidate.completionTokens);
-    if (outputTokens !== undefined) return outputTokens;
-  }
-
-  return (
-    toFiniteNumber(payload.outputTokens) ??
-    toFiniteNumber(payload.completionTokens) ??
-    (result
-      ? (toFiniteNumber(result.outputTokens) ??
-        toFiniteNumber(result.completionTokens))
-      : undefined)
-  );
+  const tokens = getRecord(payload, "tokens") ?? getRecord(payload, "totalTokens");
+  return tokens ? toFiniteNumber(tokens.output) : undefined;
 }
 
-/** Extract provider execution time (ms) from a variety of payload shapes. */
-function getExecutionTimeMs(
-  payload: Record<string, unknown>
-): number | undefined {
-  const result = getRecord(payload, "result");
-  return (
-    toFiniteNumber(payload.executionTime) ??
-    toFiniteNumber(payload.executionTimeMs) ??
-    toFiniteNumber(payload.execution_time) ??
-    toFiniteNumber(payload.duration) ??
-    (result
-      ? (toFiniteNumber(result.executionTime) ??
-        toFiniteNumber(result.executionTimeMs))
-      : undefined)
-  );
+/** Current step/execution completions report elapsed milliseconds as durationMs. */
+function getExecutionTimeMs(payload: Record<string, unknown>): number | undefined {
+  return toFiniteNumber(payload.durationMs);
 }
 
 function defaultClock(): number {
@@ -286,8 +173,8 @@ export class ThroughputTracker {
 
   processEvent(eventType: string, payload: unknown): void {
     if (!isRecord(payload)) {
-      // Non-object payloads can still signal lifecycle (e.g. bare "error").
-      if (ERROR_EVENTS.has(eventType) && this.run) {
+      // Non-object payloads can still signal lifecycle (e.g. bare "execution_error").
+      if (eventType === "execution_error" && this.run) {
         this.run = null;
         this.metric = { status: "error" };
       }
@@ -297,7 +184,7 @@ export class ThroughputTracker {
     const type = resolveEventType(eventType, payload);
     const now = this.now();
 
-    if (REQUEST_START_EVENTS.has(type)) {
+    if (type === "execution_start") {
       // New request: start fresh, discarding any incomplete prior run.
       this.startRun(now);
       return;
@@ -309,9 +196,8 @@ export class ThroughputTracker {
       return;
     }
 
-    if (VISIBLE_DELTA_EVENTS.has(type)) {
-      if (!isVisibleTextDelta(type, payload)) return;
-      const text = getTextDelta(payload);
+    if (type === "text_delta") {
+      const text = typeof payload.delta === "string" ? payload.delta : "";
       if (!text) return;
 
       // Lazily start a run if the stream began without a recognized start event.
@@ -367,7 +253,7 @@ export class ThroughputTracker {
       return;
     }
 
-    if (TERMINAL_COMPLETE_EVENTS.has(type)) {
+    if (type === "execution_complete") {
       if (!this.run) return;
       const stats = this.run;
       // Prefer exact output tokens from this terminal event, else accumulated
@@ -396,7 +282,7 @@ export class ThroughputTracker {
       return;
     }
 
-    if (ERROR_EVENTS.has(type)) {
+    if (type === "execution_error" || (type === "error" && payload.recoverable === false)) {
       if (!this.run) return;
       this.run = null;
       this.metric = { status: "error" };

package/src/utils/tokens.ts

@@ -128,6 +128,32 @@ export const DEFAULT_PALETTE = {
       900: '#1e3a8a',
       950: '#172554',
     },
+    purple: {
+      50: '#faf5ff',
+      100: '#f3e8ff',
+      200: '#e9d5ff',
+      300: '#d8b4fe',
+      400: '#c084fc',
+      500: '#a855f7',
+      600: '#9333ea',
+      700: '#7e22ce',
+      800: '#6b21a8',
+      900: '#581c87',
+      950: '#3b0764',
+    },
+    teal: {
+      50: '#f0fdfa',
+      100: '#ccfbf1',
+      200: '#99f6e4',
+      300: '#5eead4',
+      400: '#2dd4bf',
+      500: '#14b8a6',
+      600: '#0d9488',
+      700: '#0f766e',
+      800: '#115e59',
+      900: '#134e4a',
+      950: '#042f2e',
+    },
   },
   spacing,
   typography: {
@@ -472,6 +498,20 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       border: 'palette.colors.gray.200',
     },
   },
+  // Event-stream badge chips: 100-tone fill / dark text per family. tool/agent
+  // keep their pre-token literals (#6b21a8 / #115e59), which sit at the 800
+  // step of the canonical purple/teal ramps.
+  eventStream: {
+    badge: {
+      flow: { background: 'palette.colors.success.100', foreground: 'palette.colors.success.700' },
+      step: { background: 'palette.colors.primary.100', foreground: 'palette.colors.primary.700' },
+      reasoning: { background: 'palette.colors.warning.100', foreground: 'palette.colors.warning.700' },
+      tool: { background: 'palette.colors.purple.100', foreground: 'palette.colors.purple.800' },
+      agent: { background: 'palette.colors.teal.100', foreground: 'palette.colors.teal.800' },
+      error: { background: 'palette.colors.error.100', foreground: 'palette.colors.error.700' },
+      default: { background: 'palette.colors.gray.100', foreground: 'palette.colors.gray.600' },
+    },
+  },
   scrollToBottom: {
     background: 'components.button.primary.background',
     foreground: 'components.button.primary.foreground',
@@ -1085,6 +1125,25 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     ['scroll-to-bottom-gap', 'components-scrollToBottom-gap', '=0.5rem'],
     ['scroll-to-bottom-font-size', 'components-scrollToBottom-fontSize', 'palette-typography-fontSize-sm', '=0.875rem'],
     ['scroll-to-bottom-icon-size', 'components-scrollToBottom-iconSize', '=14px'],
+    // Event-stream badge chips. Materialized in every theme (light defaults in
+    // DEFAULT_COMPONENTS, dark pairs in the built-in dark layer), so the
+    // chip's inline var() refs always resolve inside a themed root and
+    // re-resolve on scheme toggles; the literal terminals only cover unthemed
+    // direct mounts.
+    ['event-badge-flow-bg', 'components-eventStream-badge-flow-background', '=#dcfce7'],
+    ['event-badge-flow-fg', 'components-eventStream-badge-flow-foreground', '=#15803d'],
+    ['event-badge-step-bg', 'components-eventStream-badge-step-background', '=#f5f5f5'],
+    ['event-badge-step-fg', 'components-eventStream-badge-step-foreground', '=#0a0a0a'],
+    ['event-badge-reasoning-bg', 'components-eventStream-badge-reasoning-background', '=#fef9c3'],
+    ['event-badge-reasoning-fg', 'components-eventStream-badge-reasoning-foreground', '=#a16207'],
+    ['event-badge-tool-bg', 'components-eventStream-badge-tool-background', '=#f3e8ff'],
+    ['event-badge-tool-fg', 'components-eventStream-badge-tool-foreground', '=#6b21a8'],
+    ['event-badge-agent-bg', 'components-eventStream-badge-agent-background', '=#ccfbf1'],
+    ['event-badge-agent-fg', 'components-eventStream-badge-agent-foreground', '=#115e59'],
+    ['event-badge-error-bg', 'components-eventStream-badge-error-background', '=#fee2e2'],
+    ['event-badge-error-fg', 'components-eventStream-badge-error-foreground', '=#b91c1c'],
+    ['event-badge-default-bg', 'components-eventStream-badge-default-background', '=#f3f4f6'],
+    ['event-badge-default-fg', 'components-eventStream-badge-default-foreground', '=#4b5563'],
     ['tool-bubble-shadow', 'components-toolBubble-shadow', '=0 5px 15px rgba(15, 23, 42, 0.08)'],
     ['reasoning-bubble-shadow', 'components-reasoningBubble-shadow', '=0 5px 15px rgba(15, 23, 42, 0.08)'],
     ['composer-shadow', 'components-composer-shadow', '=none'],

package/src/utils/voice-support.ts

@@ -1,4 +1,21 @@
-import type { VoiceConfig } from "../types";
+import type { AgentWidgetConfig, VoiceConfig } from "../types";
+
+/** Changes that require replacing a session's capture and playback provider. */
+export function voiceConnectionChanged(previous: AgentWidgetConfig, next: AgentWidgetConfig): boolean {
+  const before = previous.voiceRecognition;
+  const after = next.voiceRecognition;
+  return (before?.enabled === true) !== (after?.enabled === true) ||
+    before?.provider?.type !== after?.provider?.type ||
+    before?.provider?.custom !== after?.provider?.custom ||
+    before?.provider?.runtype?.createPlaybackEngine !== after?.provider?.runtype?.createPlaybackEngine ||
+    JSON.stringify(before?.provider?.runtype) !== JSON.stringify(after?.provider?.runtype) ||
+    previous.agentId !== next.agentId || previous.clientToken !== next.clientToken || previous.apiUrl !== next.apiUrl;
+}
+
+/** Providers whose microphone lifecycle is owned by ChatSession instead of browser dictation. */
+export function usesSessionVoice(config?: Partial<VoiceConfig>): boolean {
+  return config?.type === "runtype" || config?.type === "custom";
+}
 
 /**
  * Eager, construction-free replica of the voice factory's `isVoiceSupported`

package/src/voice/voice-turn-tracker.ts

@@ -0,0 +1,18 @@
+/** Correlate provider transcripts across cancellation and overlapping turns. */
+export class VoiceTurnTracker {
+  private turnId?: string;
+  private cancelled = false;
+
+  start(turnId?: string): void {
+    this.turnId = turnId;
+    this.cancelled = false;
+  }
+
+  cancel(): void {
+    this.cancelled = true;
+  }
+
+  accepts(turnId?: string): boolean {
+    return !this.cancelled && (!turnId || !this.turnId || turnId === this.turnId);
+  }
+}

package/src/webmcp-bridge.test.ts

@@ -11,7 +11,8 @@ import type {
 // calls `initializeWebMCPPolyfill()` (idempotent install of document.modelContext).
 // We stub the install as a no-op and provide `document.modelContext` ourselves,
 // modeling the strict producer-preview surface the bridge consumes:
-//   - getTools(): async; inputSchema is a JSON string; NO annotations
+//   - getTools(): async; inputSchema in either generation (see
+//     `registry.schemaShape`); annotations only when the tool declared them
 //   - executeTool(info, argsJson, { signal }): async; validates+runs execute(),
 //     returns JSON.stringify(rawResult) or null; honors the abort signal.
 // ---------------------------------------------------------------------------
@@ -45,21 +46,46 @@ type MockTool = {
   description?: string;
   inputSchema?: object;
   title?: string;
+  annotations?: Record<string, unknown>;
   execute: (args: Record<string, unknown>, client: MockClient) => unknown;
 };
 
-const registry: { tools: MockTool[] } = { tools: [] };
+/**
+ * Which generation of the WebMCP `inputSchema` contract the fake emits.
+ *
+ * `"object"` is what `@mcp-b/webmcp-polyfill` v5 and Chrome 154+ return after
+ * `webmcp#241`; `"string"` is the serialized form Chrome 149-153 and 154's
+ * same-document tools still emit. Both are live in the field, so the snapshot
+ * tests run against both -- pinning this fake to one generation is exactly how
+ * the v5 bump landed green while every real dispatch 400'd.
+ */
+type SchemaShape = "object" | "string";
+
+const registry: { tools: MockTool[]; schemaShape: SchemaShape } = {
+  tools: [],
+  schemaShape: "object",
+};
 
 /** 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.
+    // Mirrors the real polyfill's getTools(): `title` is always present, ""
+    // when the tool didn't declare one; annotations are absent. v5 OMITS
+    // `inputSchema` for a tool that registered none, where v4 always emitted a
+    // `{"type":"object"}` string.
     return registry.tools.map((t) => ({
       name: t.name,
       description: t.description ?? `mock ${t.name}`,
-      inputSchema: JSON.stringify(t.inputSchema ?? { type: "object" }),
+      ...(t.inputSchema === undefined
+        ? {}
+        : {
+            inputSchema:
+              registry.schemaShape === "object"
+                ? t.inputSchema
+                : JSON.stringify(t.inputSchema),
+          }),
       title: t.title ?? "",
+      ...(t.annotations === undefined ? {} : { annotations: t.annotations }),
     }));
   },
   async executeTool(
@@ -110,6 +136,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   polyfillMock.initThrows = false;
   registry.tools = [];
+  registry.schemaShape = "object";
   // location is read by snapshotForDispatch; document.modelContext is the
   // consumer surface. Both are absent in the Node test environment.
   vi.stubGlobal("location", { origin: "https://example.test" });
@@ -166,29 +193,111 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
     expect(bridge.isOperational()).toBe(false);
   });
 
-  it("ships only the JSON-serializable surface (name, description, schema, origin)", async () => {
+  // Both `inputSchema` generations must produce the same wire tool: the object
+  // form (webmcp#241 / polyfill v5 / Chrome 154+) and the serialized string
+  // Chrome 149-153 still emits.
+  it.each(["object", "string"] as const)(
+    "ships only the JSON-serializable surface (name, description, schema, origin) [%s inputSchema]",
+    async (schemaShape) => {
+      registry.schemaShape = schemaShape;
+      registry.tools = [
+        fakeTool({
+          name: "search",
+          description: "search the shop",
+          inputSchema: { type: "object", properties: { q: { type: "string" } } },
+        }),
+      ];
+      const bridge = new WebMcpBridge({ enabled: true });
+      const snap = await bridge.snapshotForDispatch();
+      expect(snap).toHaveLength(1);
+      const tool = snap[0]!;
+      expect(tool.name).toBe("search");
+      expect(tool.description).toBe("search the shop");
+      expect(tool.parametersSchema).toEqual({
+        type: "object",
+        properties: { q: { type: "string" } },
+      });
+      expect(tool.origin).toBe("webmcp");
+      expect(tool.pageOrigin).toBe("https://example.test");
+      expect((tool as unknown as { execute?: unknown }).execute).toBeUndefined();
+      // Now that the registry was read, the bridge reports operational.
+      expect(bridge.isOperational()).toBe(true);
+    },
+  );
+
+  // `parametersSchema` is required by the server's InlineClientToolSchema, and
+  // one entry missing it fails the whole DispatchRequestSchema union: a tool
+  // with no usable schema must degrade to "takes no arguments", never to an
+  // omitted key that 400s the turn.
+  it("always sends a parametersSchema, even when the tool declared none", async () => {
+    registry.tools = [fakeTool({ name: "ping" })];
+    const snap = await new WebMcpBridge({ enabled: true }).snapshotForDispatch();
+    expect(snap[0]!.parametersSchema).toEqual({ type: "object", properties: {} });
+  });
+
+  it("forwards annotations and hoists untrustedContentHint to the top level", async () => {
     registry.tools = [
       fakeTool({
-        name: "search",
-        description: "search the shop",
-        inputSchema: { type: "object", properties: { q: { type: "string" } } },
+        name: "get_reviews",
+        annotations: { readOnlyHint: true, untrustedContentHint: true },
       }),
     ];
-    const bridge = new WebMcpBridge({ enabled: true });
-    const snap = await bridge.snapshotForDispatch();
-    expect(snap).toHaveLength(1);
-    const tool = snap[0]!;
-    expect(tool.name).toBe("search");
-    expect(tool.description).toBe("search the shop");
-    expect(tool.parametersSchema).toEqual({
-      type: "object",
-      properties: { q: { type: "string" } },
+    const snap = await new WebMcpBridge({ enabled: true }).snapshotForDispatch();
+    expect(snap[0]!.annotations).toEqual({
+      readOnlyHint: true,
+      untrustedContentHint: true,
     });
-    expect(tool.origin).toBe("webmcp");
-    expect(tool.pageOrigin).toBe("https://example.test");
-    expect((tool as unknown as { execute?: unknown }).execute).toBeUndefined();
-    // Now that the registry was read, the bridge reports operational.
-    expect(bridge.isOperational()).toBe(true);
+    // The server acts on the top-level field, not the nested metadata copy.
+    expect(snap[0]!.untrustedContentHint).toBe(true);
+  });
+
+  it("omits annotations and the top-level hint when the tool declared none", async () => {
+    registry.tools = [fakeTool({ name: "search" })];
+    const snap = await new WebMcpBridge({ enabled: true }).snapshotForDispatch();
+    expect(snap[0]!).not.toHaveProperty("annotations");
+    expect(snap[0]!).not.toHaveProperty("untrustedContentHint");
+  });
+
+  it("does not hoist untrustedContentHint: false, and drops unknown annotation keys", async () => {
+    registry.tools = [
+      fakeTool({
+        name: "add_to_cart",
+        annotations: {
+          readOnlyHint: false,
+          untrustedContentHint: false,
+          destructiveHint: true, // MCP-only today; not in the WebMCP dict
+          evil: () => "not JSON",
+        },
+      }),
+    ];
+    const snap = await new WebMcpBridge({ enabled: true }).snapshotForDispatch();
+    expect(snap[0]!.annotations).toEqual({
+      readOnlyHint: false,
+      untrustedContentHint: false,
+    });
+    expect(snap[0]!).not.toHaveProperty("untrustedContentHint");
+  });
+
+  it.each([
+    ["unparseable string", "{not json"],
+    ["non-object JSON string", '"just a string"'],
+    ["JSON array string", "[1,2,3]"],
+    ["array object", [1, 2, 3]],
+    ["null", null],
+  ])("falls back to an empty schema for %s", async (_label, inputSchema) => {
+    registry.tools = [fakeTool({ name: "odd" })];
+    // Bypass the fake's shape switch: these are malformed values a page or a
+    // future runtime could hand us, not either sanctioned generation.
+    vi.stubGlobal("document", {
+      modelContext: {
+        ...makeModelContext(),
+        async getTools() {
+          return [{ name: "odd", description: "odd", inputSchema, title: "" }];
+        },
+      },
+    });
+    const snap = await new WebMcpBridge({ enabled: true }).snapshotForDispatch();
+    expect(snap[0]!.parametersSchema).toEqual({ type: "object", properties: {} });
   });
 
   it("applies client-side allowlist glob (`search_*`)", async () => {

package/src/webmcp-bridge.ts

@@ -49,8 +49,22 @@ export const WEBMCP_TOOL_PREFIX = "webmcp:";
 export interface ModelContextToolInfo {
   name: string;
   description: string;
-  /** JSON-encoded JSON Schema for the tool's input. */
-  inputSchema?: string;
+  /**
+   * JSON Schema for the tool's input, in EITHER generation of the WebMCP
+   * contract. Never read it raw: `normalizeInputSchema` in
+   * `webmcp-runtime-entry.ts` collapses both shapes to the object the wire
+   * needs.
+   *
+   * `webmcp#241` changed this from a JSON-encoded string to a JSON Schema
+   * object. `@mcp-b/webmcp-polyfill` made the switch in v5, and Chrome ships it
+   * from 154.0.8013 (cross-document tools first) -- but Chrome 149-153, most of
+   * the Origin Trial population, and 154's same-document tools still emit the
+   * string. Both are live in the field, so we accept both.
+   *
+   * Absent when the tool registered no schema: v5 omits the member, where v4
+   * always emitted a `{"type":"object"}` string.
+   */
+  inputSchema?: object | string;
   /**
    * Display title declared on the tool (`ToolDescriptor.title` in the WebMCP
    * spec). The polyfill returns `""` when the tool didn't declare one. Note:
@@ -59,6 +73,16 @@ export interface ModelContextToolInfo {
    * channel available to us.
    */
   title?: string;
+  /**
+   * WebMCP `Tool.annotations`. Returned by `getTools()` since
+   * `@mcp-b/webmcp-polyfill` v5 (and by Chrome's native implementation);
+   * absent on v4 and whenever the tool declared none -- the spec omits the
+   * member rather than emitting an empty object.
+   */
+  annotations?: {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+  };
 }
 
 export interface ModelContextCoreLike {
@@ -208,7 +232,7 @@ export const stripWebMcpPrefix = (name: string): string =>
 
 /**
  * `true` when `wireToolName` carries the `webmcp:` prefix. Used by `client.ts`
- * to route `step_await` events.
+ * to route `await` events.
  */
 export const isWebMcpToolName = (name: string): boolean =>
   name.startsWith(WEBMCP_TOOL_PREFIX);