@runtypelabs/persona 4.28.2 → 4.29.1

package/src/voice/voice.test.ts

@@ -1,6 +1,10 @@
 // Voice SDK Tests
 import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach, vi } from 'vitest';
 import type {
+  ClientToolDefinition,
+  VoiceClientToolOutcome,
+  VoiceClientTools,
+  VoiceDirectTurn,
   VoiceConfig,
   VoiceDelegationFollowUp,
   VoiceDelegationRequest,
@@ -9,6 +13,7 @@ import type {
 } from '../types';
 
 import { RuntypeVoiceProvider, buildCallContext } from './runtype-voice-provider';
+import { createVoiceClientToolsSession } from './voice-client-tools-session';
 import { VERSION } from '../version';
 import { BrowserVoiceProvider } from './browser-voice-provider';
 import { createVoiceProvider, createBestAvailableVoiceProvider, isVoiceSupported } from './voice-factory';
@@ -1658,6 +1663,397 @@ describe('RuntypeVoiceProvider (realtime streaming)', () => {
         });
       });
 
+      describe('fast tier (client_tools)', () => {
+        const FAST_CAPS = [...ALL_CAPS, 'client_tools'];
+        const nextSlide: ClientToolDefinition = {
+          name: 'next_slide',
+          description: 'Advance the presentation to the next slide.',
+          parametersSchema: { type: 'object', properties: {} },
+          origin: 'webmcp',
+          pageOrigin: 'https://example.com',
+          annotations: { readOnlyHint: true },
+        };
+        const jumpToSlide: ClientToolDefinition = {
+          name: 'jump_to_slide',
+          description: 'Jump to a 1-based slide position.',
+          parametersSchema: { type: 'object', required: ['position'], properties: { position: { type: 'integer' } } },
+          origin: 'webmcp',
+          annotations: { readOnlyHint: true },
+        };
+
+        function makeFastBridge(tools: ClientToolDefinition[] = [nextSlide, jumpToSlide]) {
+          const base = makeBridge();
+          const state = { tools, fingerprint: 'fp1' };
+          const listeners = new Set<() => void>();
+          const executed: Array<{ name: string; args: Record<string, unknown>; options: { signal: AbortSignal; autoConfirmReadOnly: boolean } }> = [];
+          let respond: (name: string, signal: AbortSignal) => Promise<VoiceClientToolOutcome> = async () => ({
+            status: 'completed',
+            result: { slidePosition: 5, slideTitle: 'Pricing' },
+          });
+          const surface: VoiceClientTools = {
+            snapshot: async () => ({ tools: state.tools, fingerprint: state.fingerprint }),
+            onChange: (listener) => {
+              listeners.add(listener);
+              return () => listeners.delete(listener);
+            },
+            execute: (name, args, options) => {
+              executed.push({ name, args, options });
+              return respond(name, options.signal);
+            },
+            open: async (channel) => createVoiceClientToolsSession(surface, channel),
+          };
+          const recorded: VoiceDirectTurn[] = [];
+          const bridge: VoiceSessionBridge = {
+            ...base.bridge,
+            clientTools: () => surface,
+            recordDirectTurn: (turn) => recorded.push(turn),
+          };
+          return {
+            ...base,
+            bridge,
+            state,
+            executed,
+            recorded,
+            change: () => listeners.forEach((listener) => listener()),
+            setRespond: (fn: typeof respond) => (respond = fn),
+          };
+        }
+
+        async function startFastCall(capabilities = FAST_CAPS, tools?: ClientToolDefinition[]) {
+          const fast = makeFastBridge(tools);
+          const provider = new RuntypeVoiceProvider({ ...baseConfig(), createPlaybackEngine: () => makeFakeEngine() });
+          provider.setSessionBridge(fast.bridge);
+          await provider.startListening();
+          const ws = lastWs();
+          ws.triggerOpen();
+          ws.triggerMessage(
+            JSON.stringify({ type: 'session_config', interruptionMode: 'barge-in', speechMode: 'speech_to_speech', capabilities }),
+          );
+          await flush();
+          return { ...fast, provider, ws };
+        }
+
+        const toolCall = (ws: MockWebSocket, fields: Record<string, unknown> = {}) =>
+          ws.triggerMessage(
+            JSON.stringify({
+              type: 'client_tool_call',
+              delegationId: 'd1',
+              toolCallId: 'vtc_01',
+              name: 'webmcp:jump_to_slide',
+              arguments: { position: 5 },
+              fingerprint: 'fp1',
+              timeoutMs: 5000,
+              ...fields,
+            }),
+          );
+        const started = (ws: MockWebSocket, delegationId: string, text = 'Jump to the pricing slide') =>
+          ws.triggerMessage(
+            JSON.stringify({
+              type: 'delegation_started',
+              delegationId,
+              input: { text, userUtteranceIds: ['u1'], messages: [] },
+            }),
+          );
+        const heard = (ws: MockWebSocket, text = 'Jump to the pricing slide', utteranceId = 'u1') =>
+          ws.triggerMessage(update('user', text, utteranceId));
+        const directCompleted = (ws: MockWebSocket, delegationId = 'd1', text = 'Slide 5: Pricing.') =>
+          ws.triggerMessage(
+            JSON.stringify({ type: 'delegation_completed', delegationId, route: 'direct', speak: true, text, final: true }),
+          );
+        const results = (ws: MockWebSocket) => sentJson(ws).filter((f) => f.type === 'client_tool_result');
+
+        it('declares client_tools and prior_tool_results only when the bridge has WebMCP tools', async () => {
+          const { ws } = await startFastCall();
+          expect(ws.url).toBe(
+            voiceUrl('wss://api.example.com', 'a1', [
+              ...BASE_CAPS,
+              'client_delegation',
+              'delegation_update',
+              'delegation_read_back',
+              'delegation_stream',
+              'client_tools',
+              'prior_tool_results',
+            ]),
+          );
+          const provider = new RuntypeVoiceProvider(baseConfig());
+          provider.setSessionBridge({ ...makeBridge().bridge, clientTools: () => null });
+          await provider.startListening();
+          const declared = new URL(lastWs().url).searchParams.get('clientCapabilities');
+          expect(declared).not.toContain('client_tools');
+          expect(declared).not.toContain('prior_tool_results');
+        });
+
+        it('sends client_tools after session_config with full webmcp: names and the dispatch fields', async () => {
+          const { ws } = await startFastCall();
+          const frames = sentJson(ws).filter((f) => f.type === 'client_tools');
+          expect(frames).toHaveLength(1);
+          expect(frames[0].fingerprint).toBe('fp1');
+          expect(frames[0].tools).toEqual([
+            { ...nextSlide, name: 'webmcp:next_slide' },
+            { ...jumpToSlide, name: 'webmcp:jump_to_slide' },
+          ]);
+        });
+
+        it('keeps sdk-origin names bare and does not double-prefix', async () => {
+          const sdk: ClientToolDefinition = { ...nextSlide, name: 'ask_user_question', origin: 'sdk' };
+          const prefixed: ClientToolDefinition = { ...nextSlide, name: 'webmcp:already' };
+          const { ws } = await startFastCall(FAST_CAPS, [sdk, prefixed]);
+          const [frame] = sentJson(ws).filter((f) => f.type === 'client_tools');
+          expect(frame.tools.map((t: { name: string }) => t.name)).toEqual(['ask_user_question', 'webmcp:already']);
+        });
+
+        it('resends on a fingerprint change with its new fingerprint, and not on an unchanged one', async () => {
+          const { ws, state, change } = await startFastCall();
+          change(); // same fingerprint
+          await flush();
+          expect(sentJson(ws).filter((f) => f.type === 'client_tools')).toHaveLength(1);
+          state.tools = [nextSlide];
+          state.fingerprint = 'fp2';
+          change();
+          await flush();
+          const frames = sentJson(ws).filter((f) => f.type === 'client_tools');
+          expect(frames).toHaveLength(2);
+          expect(frames[1].fingerprint).toBe('fp2');
+          expect(frames[1].tools).toEqual([{ ...nextSlide, name: 'webmcp:next_slide' }]);
+        });
+
+        it('sends no client_tools when the server did not negotiate it', async () => {
+          const { ws } = await startFastCall(ALL_CAPS);
+          expect(sentJson(ws).filter((f) => f.type === 'client_tools')).toEqual([]);
+        });
+
+        it('runs a client_tool_call with the read-only auto-confirm and answers completed', async () => {
+          const { ws, executed } = await startFastCall();
+          toolCall(ws);
+          await flush();
+          expect(executed).toHaveLength(1);
+          expect(executed[0].name).toBe('webmcp:jump_to_slide');
+          expect(executed[0].args).toEqual({ position: 5 });
+          expect(executed[0].options.autoConfirmReadOnly).toBe(true);
+          expect(results(ws)).toEqual([
+            {
+              type: 'client_tool_result',
+              delegationId: 'd1',
+              toolCallId: 'vtc_01',
+              status: 'completed',
+              result: { slidePosition: 5, slideTitle: 'Pricing' },
+            },
+          ]);
+        });
+
+        it('accepts the bare name too', async () => {
+          const { ws, executed } = await startFastCall();
+          toolCall(ws, { name: 'jump_to_slide' });
+          await flush();
+          expect(executed[0].name).toBe('webmcp:jump_to_slide');
+          expect(results(ws)[0].status).toBe('completed');
+        });
+
+        it('answers stale for an unknown tool or a fingerprint other than the last sent, without running anything', async () => {
+          const { ws, executed, state, change } = await startFastCall();
+          toolCall(ws, { name: 'webmcp:delete_deck', toolCallId: 't1' });
+          state.fingerprint = 'fp2';
+          change();
+          await flush();
+          toolCall(ws, { toolCallId: 't2' });
+          await flush();
+          expect(executed).toEqual([]);
+          expect(results(ws).map((r) => [r.toolCallId, r.status])).toEqual([
+            ['t1', 'stale'],
+            ['t2', 'stale'],
+          ]);
+        });
+
+        it('passes denied through and maps a thrown error to failed with its message', async () => {
+          const { ws, setRespond } = await startFastCall();
+          setRespond(async () => ({ status: 'denied', error: { message: 'User declined the tool call.' } }));
+          toolCall(ws, { toolCallId: 't1' });
+          await flush();
+          setRespond(async () => {
+            throw new Error('page exploded');
+          });
+          toolCall(ws, { toolCallId: 't2' });
+          await flush();
+          expect(results(ws)).toEqual([
+            expect.objectContaining({ toolCallId: 't1', status: 'denied' }),
+            expect.objectContaining({ toolCallId: 't2', status: 'failed', error: { message: 'page exploded' } }),
+          ]);
+        });
+
+        it('answers timeout once timeoutMs passes and aborts the page tool', async () => {
+          vi.useFakeTimers();
+          try {
+            const { ws, setRespond } = await startFastCall();
+            let signal: AbortSignal | undefined;
+            setRespond((_name, s) => {
+              signal = s;
+              return new Promise(() => {}); // a page tool that never settles
+            });
+            toolCall(ws, { timeoutMs: 50 });
+            await flush();
+            expect(results(ws)).toEqual([]);
+            await vi.advanceTimersByTimeAsync(60);
+            expect(results(ws)).toEqual([expect.objectContaining({ status: 'timeout' })]);
+            expect(signal?.aborted).toBe(true);
+          } finally {
+            vi.useRealTimers();
+          }
+        });
+
+        it('a call reusing a pending toolCallId replaces it: only the replacement answers', async () => {
+          const { ws, setRespond } = await startFastCall();
+          setRespond((_name, signal) => new Promise((resolve) => signal.addEventListener('abort', () => resolve({ status: 'failed' }))));
+          toolCall(ws);
+          await flush();
+          setRespond(async () => ({ status: 'completed', result: { slidePosition: 2 } }));
+          toolCall(ws);
+          await flush();
+          expect(results(ws)).toEqual([expect.objectContaining({ toolCallId: 'vtc_01', status: 'completed' })]);
+        });
+
+        it('sends nothing for a tool call whose delegation the server cancelled', async () => {
+          const { ws, setRespond } = await startFastCall();
+          let finish!: (o: VoiceClientToolOutcome) => void;
+          setRespond(() => new Promise((resolve) => (finish = resolve)));
+          toolCall(ws);
+          await flush();
+          ws.triggerMessage(JSON.stringify({ type: 'delegation_cancelled', delegationId: 'd1', reason: 'superseded' }));
+          finish({ status: 'completed' });
+          await flush();
+          expect(results(ws)).toEqual([]);
+        });
+
+        it('a direct completion with no started delegation records the heard request and the answer', async () => {
+          const { ws, calls, recorded } = await startFastCall();
+          heard(ws);
+          toolCall(ws);
+          await flush();
+          directCompleted(ws);
+          await flush();
+          expect(calls).toEqual([]);
+          expect(recorded).toEqual([
+            {
+              delegationId: 'd1',
+              userText: 'Jump to the pricing slide',
+              userUtteranceIds: ['u1'],
+              assistantText: 'Slide 5: Pricing.',
+            },
+          ]);
+          directCompleted(ws); // a repeat never records twice
+          expect(recorded).toHaveLength(1);
+          expect(sentJson(ws).filter((f) => f.type === 'delegation_result')).toEqual([]);
+        });
+
+        it('a direct turn keeps the request it answered when the visitor speaks again before it completes', async () => {
+          const { ws, recorded } = await startFastCall();
+          heard(ws);
+          toolCall(ws);
+          await flush();
+          heard(ws, 'Next slide', 'u2');
+          directCompleted(ws);
+          expect(recorded).toEqual([
+            expect.objectContaining({ userText: 'Jump to the pricing slide', userUtteranceIds: ['u1'] }),
+          ]);
+        });
+
+        it('a hand-back aborts the direct tool still running, which then sends nothing', async () => {
+          const { ws, setRespond } = await startFastCall();
+          let signal: AbortSignal | undefined;
+          let finish!: (o: VoiceClientToolOutcome) => void;
+          setRespond((_name, s) => {
+            signal = s;
+            return new Promise((resolve) => (finish = resolve));
+          });
+          heard(ws);
+          toolCall(ws);
+          await flush();
+          started(ws, 'd1');
+          await flush();
+          expect(signal?.aborted).toBe(true);
+          finish({ status: 'completed' });
+          await flush();
+          expect(results(ws)).toEqual([]);
+        });
+
+        it('folds the tagged read-back of a direct turn, which the chat now shows', async () => {
+          const { ws, provider } = await startFastCall([...FAST_CAPS, 'delegation_read_back']);
+          const transcripts: unknown[][] = [];
+          provider.onTranscript((...args) => transcripts.push(args));
+          toolCall(ws);
+          ws.triggerMessage(
+            JSON.stringify({ type: 'transcript_update', role: 'assistant', text: 'Slide 5: Pricing.', utteranceId: 'a9', final: true, delegationId: 'd1' }),
+          );
+          expect(transcripts).toEqual([]);
+        });
+
+        it('a fall-through arrives as an ordinary delegation, and its completion is not a direct turn', async () => {
+          const { ws, calls, recorded, pending, setRespond } = await startFastCall();
+          setRespond(async () => ({ status: 'failed', error: { message: 'nope' } }));
+          heard(ws);
+          toolCall(ws);
+          await flush();
+          started(ws, 'd1');
+          await flush();
+          expect(calls.map((c) => [c.delegationId, c.userText])).toEqual([['d1', 'Jump to the pricing slide']]);
+          pending[0]({ status: 'completed', text: 'Here is pricing.' });
+          await flush();
+          ws.triggerMessage(JSON.stringify({ type: 'delegation_completed', delegationId: 'd1', speak: true, text: 'x' }));
+          directCompleted(ws); // even a mislabeled completion of a started delegation
+          expect(recorded).toEqual([]);
+          expect(sentJson(ws).filter((f) => f.type === 'delegation_result')).toEqual([
+            expect.objectContaining({ delegationId: 'd1', status: 'completed', text: 'Here is pricing.' }),
+          ]);
+        });
+
+        it('hands a fall-through its priorToolResults without running them again on the page', async () => {
+          const { ws, calls, executed, recorded, pending } = await startFastCall([...FAST_CAPS, 'prior_tool_results']);
+          const prior = [
+            { toolCallId: 'vtc_01', name: 'webmcp:jump_to_slide', arguments: { position: 5 }, result: { slideTitle: 'Pricing' } },
+          ];
+          heard(ws);
+          toolCall(ws);
+          await flush();
+          expect(executed).toHaveLength(1);
+          ws.triggerMessage(
+            JSON.stringify({
+              type: 'delegation_started',
+              delegationId: 'd1',
+              input: { text: 'Jump to the pricing slide', userUtteranceIds: ['u1'], messages: [], priorToolResults: prior },
+            }),
+          );
+          await flush();
+          expect(calls).toHaveLength(1);
+          expect(calls[0].priorToolResults).toEqual(prior);
+          pending[0]({ status: 'completed', text: 'You are on Pricing.' });
+          await flush();
+          directCompleted(ws);
+          expect(executed).toHaveLength(1);
+          expect(recorded).toEqual([]);
+        });
+
+        it('leaves priorToolResults unset on a fall-through without them', async () => {
+          const { ws, calls } = await startFastCall();
+          started(ws, 'd1');
+          await flush();
+          expect(calls[0].priorToolResults).toBeUndefined();
+        });
+
+        it('ignores a direct completion when client_tools was not negotiated', async () => {
+          const { ws, recorded } = await startFastCall(ALL_CAPS);
+          heard(ws);
+          directCompleted(ws);
+          expect(recorded).toEqual([]);
+        });
+
+        it('against an old core (no new tokens) sends no new frames and ignores client_tool_call', async () => {
+          const { ws, executed } = await startFastCall(ALL_CAPS);
+          toolCall(ws);
+          await flush();
+          expect(executed).toEqual([]);
+          expect(sentJson(ws)).toEqual([]);
+        });
+      });
+
       describe('capabilities and tolerance', () => {
         it('uses no client delegation, context or updates when session_config has no capabilities (old server)', async () => {
           const { ws, calls, transcripts } = await startDelegatedCall(

package/src/voice-client-tools-bundle.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Bundle guard for the lazy voice-client-tools chunk (the voice fast tier).
+ * Its session code must stay out of both the core IIFE and the voice-runtime
+ * chunk: only calls that negotiate `client_tools` download it.
+ * Skips when `dist/` hasn't been built.
+ */
+const dist = (f: string) => resolve(__dirname, "..", "dist", f);
+
+// Session-only literals, emitted nowhere else.
+const MARKERS = ["Page tool exceeded", "Unknown tool: "];
+
+describe("voice-client-tools bundle split", () => {
+  // Skip only when nothing was built; a build missing the chunk must fail.
+  const built = existsSync(dist("index.global.js"));
+
+  it.runIf(built)("keeps the fast-tier session out of the core IIFE and the voice-runtime chunk", () => {
+    for (const file of ["index.global.js", "voice-runtime.js"]) {
+      const source = readFileSync(dist(file), "utf8");
+      for (const marker of MARKERS) {
+        expect(source.includes(marker), `${file} unexpectedly contains "${marker}"`).toBe(false);
+      }
+    }
+    expect(readFileSync(dist("index.global.js"), "utf8")).toContain("voice-client-tools.js");
+  });
+
+  it.runIf(built)("ships the session in its own chunk, with CJS and declarations", () => {
+    expect(existsSync(dist("voice-client-tools.js")), "dist/voice-client-tools.js is missing").toBe(true);
+    const chunk = readFileSync(dist("voice-client-tools.js"), "utf8");
+    for (const marker of MARKERS) expect(chunk.includes(marker), `chunk is missing "${marker}"`).toBe(true);
+    expect(existsSync(dist("voice-client-tools.cjs"))).toBe(true);
+    expect(existsSync(dist("voice-client-tools.d.ts"))).toBe(true);
+  });
+});

package/src/voice-client-tools-loader.ts

@@ -0,0 +1,24 @@
+import { createChunkLoader } from "./utils/chunk-loader";
+import type { VoiceClientTools, VoiceClientToolsChannel, VoiceClientToolsSession } from "./types";
+
+/**
+ * Loader indirection for the lazy voice fast-tier chunk. Stays in the core
+ * bundle; the fallback import must be the literal package subpath (see
+ * `webmcp-runtime-loader.ts`).
+ */
+export type VoiceClientToolsModule = {
+  createVoiceClientToolsSession: (
+    surface: VoiceClientTools,
+    channel: VoiceClientToolsChannel
+  ) => VoiceClientToolsSession;
+};
+
+const { setLoader, load } = createChunkLoader<VoiceClientToolsModule>({
+  fallbackImport: () => import("@runtypelabs/persona/voice-client-tools"),
+});
+
+/** Override how the chunk is fetched (the IIFE build registers a sibling-URL loader). */
+export const setVoiceClientToolsLoader = setLoader;
+
+/** Load the fast-tier chunk. Memoized; retries after rejection. */
+export const loadVoiceClientTools = load;

package/src/voice-client-tools.ts

@@ -0,0 +1,9 @@
+/**
+ * Subpath/chunk module for the voice fast tier
+ * (`@runtypelabs/persona/voice-client-tools` → `dist/voice-client-tools.{js,cjs}`).
+ *
+ * `client.ts` loads this on demand via `voice-client-tools-loader.ts` when a
+ * Runtype voice call negotiates `client_tools` (the IIFE from a sibling URL,
+ * ESM/CJS via this external subpath), so calls without it never download it.
+ */
+export { createVoiceClientToolsSession, voiceClientToolName } from "./voice/voice-client-tools-session";

package/src/webmcp-bridge.test.ts

@@ -268,7 +268,11 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
         annotations: {
           readOnlyHint: false,
           untrustedContentHint: false,
-          destructiveHint: true, // MCP-only today; not in the WebMCP dict
+          destructiveHint: true,
+          consequentialHint: true,
+          idempotentHint: false,
+          openWorldHint: false,
+          debugging: true,
           evil: () => "not JSON",
         },
       }),
@@ -277,6 +281,11 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
     expect(snap[0]!.annotations).toEqual({
       readOnlyHint: false,
       untrustedContentHint: false,
+      destructiveHint: true,
+      consequentialHint: true,
+      idempotentHint: false,
+      openWorldHint: false,
+      debugging: true,
     });
     expect(snap[0]!).not.toHaveProperty("untrustedContentHint");
   });
@@ -380,6 +389,20 @@ describe("setWebMcpPolyfillLoader", () => {
 });
 
 describe("WebMCP display titles", () => {
+  it("passes sanitized annotations to confirmation without skipping the gate", async () => {
+    registry.tools = [fakeTool({ name: "search", annotations: {
+      readOnlyHint: true, destructiveHint: false, consequentialHint: false,
+      debugging: "yes", extra: () => "ignored",
+    } })];
+    const onConfirm = vi.fn(async () => false);
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const result = await bridge.executeToolCall("webmcp:search", {});
+    expect(onConfirm).toHaveBeenCalledWith(expect.objectContaining({ annotations: {
+      readOnlyHint: true, destructiveHint: false, consequentialHint: false,
+    } }));
+    expect(result.isError).toBe(true);
+  });
+
   it("records declared titles on snapshot and exposes them via getWebMcpToolDisplayTitle", async () => {
     registry.tools = [
       fakeTool({ name: "add_to_cart", title: "Add to Cart" }),
@@ -811,3 +834,131 @@ describe("native preview argument conversion", () => {
     expect(nativeExecute).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("WebMcpBridge.executeVoiceToolCall", () => {
+  it("skips the confirm gate for a tool the registry marks readOnlyHint: true", async () => {
+    const onConfirm = vi.fn(async () => false);
+    registry.tools = [
+      fakeTool({ name: "next_slide", annotations: { readOnlyHint: true }, execute: () => ({ slidePosition: 2 }) }),
+    ];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const r = await bridge.executeVoiceToolCall("webmcp:next_slide", {}, { autoConfirmReadOnly: true });
+    expect(onConfirm).not.toHaveBeenCalled();
+    expect(r).toEqual({ status: "completed", result: { slidePosition: 2 } });
+  });
+
+  it.each([
+    ["no annotations", undefined],
+    ["readOnlyHint false", { readOnlyHint: false }],
+    ["only other hints", { idempotentHint: true }],
+  ])("still shows the gate for a tool with %s, and maps a decline to denied", async (_label, annotations) => {
+    const onConfirm = vi.fn(async () => false);
+    const execute = vi.fn(() => "done");
+    registry.tools = [fakeTool({ name: "edit_slide", annotations, execute })];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const r = await bridge.executeVoiceToolCall("webmcp:edit_slide", {}, { autoConfirmReadOnly: true });
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(execute).not.toHaveBeenCalled();
+    expect(r).toEqual({ status: "denied", error: { message: "User declined the tool call." } });
+  });
+
+  it("shows the gate even for a read-only tool when autoConfirmReadOnly is off", async () => {
+    const onConfirm = vi.fn(async () => true);
+    registry.tools = [fakeTool({ name: "next_slide", annotations: { readOnlyHint: true } })];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    await bridge.executeVoiceToolCall("webmcp:next_slide", {});
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+  });
+
+  it("answers stale for a tool missing from the registry or excluded by the allowlist", async () => {
+    registry.tools = [fakeTool({ name: "secret", annotations: { readOnlyHint: true } })];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm: allowAll, allowlist: ["public_*"] });
+    expect((await bridge.executeVoiceToolCall("webmcp:gone", {})).status).toBe("stale");
+    expect((await bridge.executeVoiceToolCall("webmcp:secret", {})).status).toBe("stale");
+  });
+
+  it("answers failed with the message when the page tool throws or returns an MCP error", async () => {
+    registry.tools = [
+      fakeTool({
+        name: "boom",
+        annotations: { readOnlyHint: true },
+        execute: () => {
+          throw new Error("kaboom");
+        },
+      }),
+      fakeTool({
+        name: "mcp_err",
+        annotations: { readOnlyHint: true },
+        execute: () => ({ isError: true, content: [{ type: "text", text: "no such slide" }] }),
+      }),
+    ];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm: allowAll });
+    const thrown = await bridge.executeVoiceToolCall("webmcp:boom", {}, { autoConfirmReadOnly: true });
+    expect(thrown).toEqual({ status: "failed", error: { message: "kaboom" } });
+    expect(await bridge.executeVoiceToolCall("webmcp:mcp_err", {}, { autoConfirmReadOnly: true })).toEqual({
+      status: "failed",
+      error: { message: "no such slide" },
+    });
+  });
+
+  it("hands the call's signal to the confirm handler so the gate can close on abort", async () => {
+    const abort = new AbortController();
+    const onConfirm = vi.fn(async (info: { signal?: AbortSignal }) => {
+      expect(info.signal).toBe(abort.signal);
+      return false;
+    });
+    registry.tools = [fakeTool({ name: "edit_slide" })];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    await bridge.executeVoiceToolCall("webmcp:edit_slide", {}, { signal: abort.signal, autoConfirmReadOnly: true });
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not run the tool when the signal aborts while the gate is open", async () => {
+    const abort = new AbortController();
+    const execute = vi.fn(() => "done");
+    const onConfirm = vi.fn(async () => {
+      abort.abort();
+      return true;
+    });
+    registry.tools = [fakeTool({ name: "edit_slide", execute })];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const r = await bridge.executeVoiceToolCall("webmcp:edit_slide", {}, {
+      signal: abort.signal,
+      autoConfirmReadOnly: true,
+    });
+    expect(execute).not.toHaveBeenCalled();
+    expect(r.status).toBe("failed");
+  });
+
+  it("keeps executeToolCall's /resume shape and gate unchanged", async () => {
+    const onConfirm = vi.fn(async () => false);
+    registry.tools = [fakeTool({ name: "next_slide", annotations: { readOnlyHint: true } })];
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const r = await bridge.executeToolCall("webmcp:next_slide", {});
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(r).toEqual({ isError: true, content: [{ type: "text", text: "User declined the tool call." }] });
+  });
+});
+
+describe("WebMcpBridge.watchToolChanges", () => {
+  it("calls the listener on the registry's toolchange event until unsubscribed", async () => {
+    const mc = Object.assign(new EventTarget(), makeModelContext());
+    vi.stubGlobal("document", { modelContext: mc });
+    const bridge = new WebMcpBridge({ enabled: true });
+    const listener = vi.fn();
+    const stop = bridge.watchToolChanges(listener);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    mc.dispatchEvent(new Event("toolchange"));
+    expect(listener).toHaveBeenCalledTimes(1);
+    stop();
+    mc.dispatchEvent(new Event("toolchange"));
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("is inert on a registry without events", async () => {
+    const bridge = new WebMcpBridge({ enabled: true });
+    const stop = bridge.watchToolChanges(vi.fn());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(() => stop()).not.toThrow();
+  });
+});