@runtypelabs/persona 4.27.0 → 4.28.1

package/dist/webmcp-runtime.js

@@ -1,6 +1,6 @@
-var h="webmcp:",T=t=>t.startsWith(h)?t.slice(h.length):t,u={warn(t,...e){typeof console<"u"&&typeof console.warn=="function"&&console.warn(`[Persona/WebMCP] ${t}`,...e)}},b=class{constructor(e,n){this.config=e;this.#e=n,this.#o=e.onConfirm??null,this.#r=3e4}#o;#r;#t=!1;#i=null;#l=!1;#e;setConfirmHandler(e){this.#o=e}isOperational(){return this.config.enabled!==!0||!this.#t?!1:this.#n()!==null}async snapshotForDispatch(){if(await this.#s(),this.config.enabled!==!0)return[];let e=this.#n();if(!e)return[];let n;try{n=await e.getTools()}catch(i){return u.warn("getTools() threw: shipping an empty WebMCP snapshot.",i),[]}this.#e.recordToolDisplayTitles(n);let o=typeof location<"u"?location.origin:"";return n.filter(i=>this.#c(i.name)).map(i=>{let l=W(i.annotations);return{name:i.name,description:i.description,parametersSchema:P(i.inputSchema),origin:"webmcp",...o?{pageOrigin:o}:{},...l?{annotations:l}:{},...l?.untrustedContentHint===!0?{untrustedContentHint:!0}:{}}})}async executeToolCall(e,n,o){if(await this.#s(),this.config.enabled!==!0)return s("WebMCP is not enabled on this widget.");let i=this.#n();if(!i){let r=typeof document<"u"&&!!document.modelContext;return s(r?"WebMCP is not operational: document.modelContext is present but does not expose the strict getTools()/executeTool() surface (likely a different or older WebMCP polyfill).":"WebMCP bridge is not operational on this page (document.modelContext not available).")}let l=T(e),c;try{c=await i.getTools()}catch(r){let p=r instanceof Error?r.message:String(r);return s(`Failed to read WebMCP registry: ${p}`)}this.#e.recordToolDisplayTitles(c);let f=c.find(r=>r.name===l);if(!f)return s(`WebMCP tool not registered on this page: ${l}`);if(!this.#c(l))return s(`WebMCP tool not allowed by client allowlist: ${l}`);if(o?.aborted)return s("Aborted by cancel()");let m=this.#e.getToolDisplayTitle(l),C={toolName:l,args:n,description:f.description,...m?{title:m}:{},reason:"gate"};if(!await this.#u(C))return s("User declined the tool call.");if(o?.aborted)return s("Aborted by cancel()");let a=new AbortController,y=!1,M=setTimeout(()=>{y=!0,a.abort()},this.#r),g=()=>a.abort();o&&(o.aborted?a.abort():o.addEventListener("abort",g,{once:!0}));try{let r=await i.executeTool(f,k(n),{signal:a.signal});return w(r)}catch(r){if(y)return s(`WebMCP tool '${l}' timed out after ${this.#r}ms`);if(o?.aborted)return s("Aborted by cancel()");let p=r instanceof Error?r.message:String(r);return s(p)}finally{clearTimeout(M),o&&o.removeEventListener("abort",g)}}#s(){return this.config.enabled!==!0?Promise.resolve():(this.#i||(this.#i=this.#a()),this.#i)}async#a(){try{if(this.#n()){this.#t=!0;return}(await this.#e.loadPolyfill()).initializeWebMCPPolyfill(),this.#t=!0}catch(e){u.warn("Failed to load @mcp-b/webmcp-polyfill: WebMCP consumption disabled.",e),this.#t=!1}}#n(){if(typeof document>"u")return null;let e=document.modelContext;if(!e||typeof e!="object")return null;let n=e;return typeof n.getTools!="function"||typeof n.executeTool!="function"?(this.#l||(this.#l=!0,u.warn("document.modelContext is present but does not expose getTools()/executeTool(): WebMCP consumption is disabled. Another (incompatible or older) WebMCP polyfill likely installed document.modelContext before Persona. Remove it, or use a polyfill implementing the strict standard surface (e.g. @mcp-b/webmcp-polyfill).")),null):e}async#u(e){let n=this.#o??A;try{return await n(e)}catch(o){return u.warn(`Confirm handler threw for WebMCP tool '${e.toolName}'; declining.`,o),!1}}#c(e){let n=this.config.allowlist;return!n||n.length===0?!0:n.some(o=>x(e,o))}},x=(t,e)=>{if(e==="*")return!0;let n=e.replace(/[.+?^${}()|[\]\\]/g,"\\$&");return new RegExp("^"+n.replace(/\*/g,".*")+"$").test(t)},d={type:"object",properties:{}},W=t=>{if(!t||typeof t!="object")return;let e={...typeof t.readOnlyHint=="boolean"?{readOnlyHint:t.readOnlyHint}:{},...typeof t.untrustedContentHint=="boolean"?{untrustedContentHint:t.untrustedContentHint}:{}};return Object.keys(e).length>0?e:void 0},P=t=>{if(t===void 0||t==="")return{...d};if(typeof t=="object")return t!==null&&!Array.isArray(t)?t:{...d};try{let e=JSON.parse(t);return e!==null&&typeof e=="object"&&!Array.isArray(e)?e:{...d}}catch{return{...d}}},w=t=>{if(t==null)return{content:[{type:"text",text:""}]};let e;try{e=JSON.parse(t)}catch{return{content:[{type:"text",text:t}]}}return e!==null&&typeof e=="object"&&Array.isArray(e.content)?e:{content:[{type:"text",text:typeof e=="string"?e:D(e)}]}},s=t=>({isError:!0,content:[{type:"text",text:t}]}),A=async t=>{if(typeof window>"u"||typeof window.confirm!="function")return!1;let e=O(t.args),n=`Allow the AI to call ${t.toolName}`+(e?`
+var C="webmcp:",w=t=>t.startsWith(C)?t.slice(C.length):t,u={warn(t,...e){typeof console<"u"&&typeof console.warn=="function"&&console.warn(`[Persona/WebMCP] ${t}`,...e)}},b=class{constructor(e,n){this.config=e;this.#e=n,this.#o=e.onConfirm??null,this.#r=3e4}#o;#r;#t=!1;#i=null;#l=!1;#e;setConfirmHandler(e){this.#o=e}isOperational(){return this.config.enabled!==!0||!this.#t?!1:this.#n()!==null}async snapshotForDispatch(){if(await this.#s(),this.config.enabled!==!0)return[];let e=this.#n();if(!e)return[];let n;try{n=(await e.getTools()).filter(h)}catch(i){return u.warn("getTools() threw: shipping an empty WebMCP snapshot.",i),[]}this.#e.recordToolDisplayTitles(n);let o=typeof location<"u"?location.origin:"";return n.filter(i=>this.#c(i.name)).map(i=>{let l=P(i.annotations);return{name:i.name,description:i.description,parametersSchema:W(i.inputSchema),origin:"webmcp",...o?{pageOrigin:o}:{},...l?{annotations:l}:{},...l?.untrustedContentHint===!0?{untrustedContentHint:!0}:{}}})}async executeToolCall(e,n,o){if(await this.#s(),this.config.enabled!==!0)return s("WebMCP is not enabled on this widget.");let i=this.#n();if(!i){let r=typeof document<"u"&&!!document.modelContext;return s(r?"WebMCP is not operational: document.modelContext is present but does not expose the strict getTools()/executeTool() surface (likely a different or older WebMCP polyfill).":"WebMCP bridge is not operational on this page (document.modelContext not available).")}let l=w(e),c;try{c=(await i.getTools()).filter(h)}catch(r){let p=r instanceof Error?r.message:String(r);return s(`Failed to read WebMCP registry: ${p}`)}this.#e.recordToolDisplayTitles(c);let f=c.find(r=>r.name===l);if(!f)return s(`WebMCP tool not registered on this page: ${l}`);if(!this.#c(l))return s(`WebMCP tool not allowed by client allowlist: ${l}`);if(o?.aborted)return s("Aborted by cancel()");let m=this.#e.getToolDisplayTitle(l),M={toolName:l,args:n,description:f.description,...m?{title:m}:{},reason:"gate"};if(!await this.#u(M))return s("User declined the tool call.");if(o?.aborted)return s("Aborted by cancel()");let a=new AbortController,y=!1,T=setTimeout(()=>{y=!0,a.abort()},this.#r),g=()=>a.abort();o&&(o.aborted?a.abort():o.addEventListener("abort",g,{once:!0}));try{let r=await i.executeTool(f,O(n),{signal:a.signal});return A(r)}catch(r){if(y)return s(`WebMCP tool '${l}' timed out after ${this.#r}ms`);if(o?.aborted)return s("Aborted by cancel()");let p=r instanceof Error?r.message:String(r);return s(p)}finally{clearTimeout(T),o&&o.removeEventListener("abort",g)}}#s(){return this.config.enabled!==!0?Promise.resolve():(this.#i||(this.#i=this.#a()),this.#i)}async#a(){try{if(this.#n()){this.#t=!0;return}let e=await this.#e.loadPolyfill();"initializeWebMCPPolyfill"in e?e.initializeWebMCPPolyfill():e.installWebMCP(),this.#t=!0}catch(e){u.warn("Failed to load @mcp-b/webmcp-polyfill: WebMCP consumption disabled.",e),this.#t=!1}}#n(){if(typeof document>"u")return null;let e=document.modelContext;if(!e||typeof e!="object")return null;let n=e;return typeof n.getTools!="function"||typeof n.executeTool!="function"?(this.#l||(this.#l=!0,u.warn("document.modelContext is present but does not expose getTools()/executeTool(): WebMCP consumption is disabled. Another (incompatible or older) WebMCP polyfill likely installed document.modelContext before Persona. Remove it, or use a polyfill implementing the strict standard surface (e.g. @mcp-b/webmcp-polyfill).")),null):e}async#u(e){let n=this.#o??k;try{return await n(e)}catch(o){return u.warn(`Confirm handler threw for WebMCP tool '${e.toolName}'; declining.`,o),!1}}#c(e){let n=this.config.allowlist;return!n||n.length===0?!0:n.some(o=>x(e,o))}},x=(t,e)=>{if(e==="*")return!0;let n=e.replace(/[.+?^${}()|[\]\\]/g,"\\$&");return new RegExp("^"+n.replace(/\*/g,".*")+"$").test(t)},d={type:"object",properties:{}},P=t=>{if(!t||typeof t!="object")return;let e={...typeof t.readOnlyHint=="boolean"?{readOnlyHint:t.readOnlyHint}:{},...typeof t.untrustedContentHint=="boolean"?{untrustedContentHint:t.untrustedContentHint}:{}};return Object.keys(e).length>0?e:void 0},W=t=>{if(t===void 0||t==="")return{...d};if(typeof t=="object")return t!==null&&!Array.isArray(t)?t:{...d};try{let e=JSON.parse(t);return e!==null&&typeof e=="object"&&!Array.isArray(e)?e:{...d}}catch{return{...d}}},A=t=>{if(t==null)return{content:[{type:"text",text:""}]};let e;try{e=JSON.parse(t)}catch{return{content:[{type:"text",text:t}]}}return e!==null&&typeof e=="object"&&Array.isArray(e.content)?e:{content:[{type:"text",text:typeof e=="string"?e:D(e)}]}},O=t=>{let e;try{e=JSON.stringify(t)??"{}"}catch{e="{}"}let n=JSON.parse(e);if(n===null||typeof n!="object")throw new TypeError("WebMCP tool arguments must be an object or array.");return Object.defineProperty(n,Symbol.toPrimitive,{value:()=>e}),n},s=t=>({isError:!0,content:[{type:"text",text:t}]}),k=async t=>{if(typeof window>"u"||typeof window.confirm!="function")return!1;let e=S(t.args),n=`Allow the AI to call ${t.toolName}`+(e?`
 
 Arguments:
 ${e}`:"")+(t.description?`
 
-${t.description}`:"");return window.confirm(n)},O=t=>{if(t==null)return"";try{let e=JSON.stringify(t,null,2);return e.length>500?e.slice(0,500)+"\u2026":e}catch{return String(t)}},k=t=>{if(t===void 0)return"{}";try{let e=JSON.stringify(t);return e===void 0?"{}":e}catch{return"{}"}},D=t=>{if(t===void 0)return"";try{return JSON.stringify(t)}catch{return String(t)}};export{b as WebMcpBridge};
+${t.description}`:"");return window.confirm(n)},S=t=>{if(t==null)return"";try{let e=JSON.stringify(t,null,2);return e.length>500?e.slice(0,500)+"\u2026":e}catch{return String(t)}},h=t=>(t.window===void 0||typeof window<"u"&&t.window===window)&&(t.origin===void 0||typeof location<"u"&&t.origin===location.origin),D=t=>{if(t===void 0)return"";try{return JSON.stringify(t)}catch{return String(t)}};export{b as WebMcpBridge};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.27.0",
+  "version": "4.28.1",
   "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",
@@ -138,6 +138,7 @@
   },
   "devDependencies": {
     "@size-limit/file": "^12.1.0",
+    "@types/jsdom": "^30.0.0",
     "@types/node": "^20.12.7",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
@@ -147,12 +148,14 @@
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "fake-indexeddb": "^6.2.5",
+    "jsdom": "^28.1.0",
     "rimraf": "^5.0.5",
     "size-limit": "^12.1.0",
     "terser": "^5.49.0",
     "tsup": "^8.0.1",
     "typescript": "^5.4.5",
-    "vitest": "^4.0.9"
+    "vitest": "^4.0.9",
+    "webmcp-polyfill-v6": "npm:@mcp-b/webmcp-polyfill@6.0.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/client.interrupt.test.ts

@@ -90,6 +90,24 @@ describe("client-token turn identity", () => {
     expect(bodies[1].turnId).not.toBe(bodies[0].turnId);
   });
 
+  it("a voice-spoken send carries the spoken-reply hint; others don't", async () => {
+    const bodies: Record<string, unknown>[] = [];
+    global.fetch = vi.fn(async (url: unknown, init: any) => {
+      if (String(url).endsWith("/v1/client/init")) return initResponse();
+      bodies.push(JSON.parse(init.body));
+      const stream = controlledStream();
+      stream.close();
+      return stream.response;
+    }) as unknown as typeof fetch;
+
+    const client = clientTokenClient();
+    await client.dispatch({ messages, voiceSpoken: true }, () => {});
+    await client.dispatch({ messages }, () => {});
+
+    expect(bodies[0].voice).toEqual({ spoken: true });
+    expect(bodies[1]).not.toHaveProperty("voice");
+  });
+
   it("drops SSE events belonging to a superseded turn", async () => {
     const first = controlledStream();
     const second = controlledStream();

package/src/client.ts

@@ -74,6 +74,12 @@ type DispatchOptions = {
    * `submitMode: "interrupt"` so the server cancels the prior run.
    */
   interrupt?: boolean;
+  /**
+   * Client-token only: a voice model reads the reply aloud (a delegated voice
+   * turn). Sends `voice: { spoken: true }` so the server asks for a speakable
+   * answer.
+   */
+  voiceSpoken?: boolean;
 };
 
 export type SSEHandler = (event: AgentWidgetEvent) => void;
@@ -1510,6 +1516,7 @@ export class AgentWidgetClient {
         // superseded run and this client can drop its stale events below.
         turnId,
         ...(options.interrupt && { submitMode: 'interrupt' as const }),
+        ...(options.voiceSpoken && { voice: { spoken: true as const } }),
       };
 
       // Diff-only / send-once WebMCP tool dispatch. `buildPayload()` already

package/src/generated/runtype-openapi-contract.ts

@@ -683,6 +683,9 @@ export type RuntypeClientChatRequest = {
   sessionId: string;
   submitMode?: "normal" | "interrupt" | "steer";
   turnId?: string;
+  voice?: {
+  spoken?: boolean;
+};
 };
 
 export type RuntypeClientChatStreamEvent = RuntypeExecutionStreamEvent;

package/src/session.ts

@@ -2042,7 +2042,7 @@ export class AgentWidgetSession {
     controller: AbortController,
     assistantMessageId: string,
     userMessageId: string,
-    turnOptions?: { composerOptions?: ComposerOptionsPayload; interrupt?: boolean }
+    turnOptions?: { composerOptions?: ComposerOptionsPayload; interrupt?: boolean; voiceSpoken?: boolean }
   ): Promise<void> {
     this.#recordDispatchedProjections(snapshot);
     try {
@@ -2052,7 +2052,8 @@ export class AgentWidgetSession {
           signal: controller.signal,
           assistantMessageId,
           composerOptions: turnOptions?.composerOptions,
-          interrupt: turnOptions?.interrupt
+          interrupt: turnOptions?.interrupt,
+          voiceSpoken: turnOptions?.voiceSpoken
         },
         this.handleEvent
       );
@@ -2070,6 +2071,7 @@ export class AgentWidgetSession {
           signal: controller.signal,
           assistantMessageId,
           composerOptions: turnOptions?.composerOptions,
+          voiceSpoken: turnOptions?.voiceSpoken,
         },
         this.handleEvent
       );
@@ -2705,7 +2707,9 @@ export class AgentWidgetSession {
         userMessageId,
         {
           composerOptions: options?.composerOptions,
-          interrupt: options?.interrupt
+          interrupt: options?.interrupt,
+          // The delegated voice turn's reply is read aloud (spoken-reply hint).
+          voiceSpoken: !!options?.voiceTurn
         }
       );
     } catch (error) {
@@ -3679,6 +3683,7 @@ export class AgentWidgetSession {
 
   private handleEvent = (event: AgentWidgetEvent) => {
     const delegation = this.#voiceDelegation;
+    let delegated = false;
     if (delegation) {
       if (event.type === "error" || (event.type === "status" && event.status === "error")) {
         delegation.failed = true;
@@ -3687,10 +3692,13 @@ export class AgentWidgetSession {
         // unless the server dropped the result (then nobody speaks it).
         if (!delegation.dropped) this.ttsSpokenMessageIds.add(event.message.id);
         if (!delegation.ids.includes(event.message.id)) delegation.ids.push(event.message.id);
+        delegated = true;
       }
     }
     if (event.type === "message") {
       this.upsertMessage(event.message);
+      // The delegated answer grew: a streaming voice bridge reads it now.
+      if (delegated) delegation!.onUpdate?.();
 
       // A resolved approval reaches this handler only from the server's
       // `approval_complete` (resolveApproval's optimistic update upserts

package/src/session.voice.test.ts

@@ -781,6 +781,146 @@ describe('AgentWidgetSession - voice client delegation bridge', () => {
     expect(result.followUp).toBeTypeOf('function');
   });
 
+  describe('streaming the answer (delegation_stream)', () => {
+    /** Streams `chunks` into one assistant message, growing it like a text stream. */
+    const streamReply = (onEvent: (event: AgentWidgetEvent) => void, chunks: string[], id = 'assistant-s1') => {
+      const base = { id, role: 'assistant' as const, createdAt: new Date().toISOString() };
+      let content = '';
+      onEvent({ type: 'status', status: 'connecting' });
+      for (const chunk of chunks) {
+        content += chunk;
+        onEvent({ type: 'message', message: { ...base, content, streaming: true } });
+      }
+      onEvent({ type: 'message', message: { ...base, content, streaming: false } });
+    };
+
+    it('streams the answer in clause pieces while it renders, then reports streamedChars', async () => {
+      drive('user', 'what are your hours', true, 'u1');
+      const pieces: string[] = [];
+      const seenBeforeEnd: string[] = [];
+      dispatch.mockImplementation(async (_options, onEvent) => {
+        streamReply(onEvent, ['We open at ', 'eight, and close ', 'at six. On Sundays ', 'we are closed.']);
+        seenBeforeEnd.push(...pieces);
+        // A tool bubble between two answer messages never streams.
+        onEvent({
+          type: 'message',
+          message: { id: 'tool-1', role: 'assistant', content: '', createdAt: new Date().toISOString(), variant: 'tool' },
+        });
+        streamReply(onEvent, ['Anything else?'], 'assistant-s2');
+        onEvent({ type: 'status', status: 'idle' });
+      });
+      const result = await h.state.bridge!.runDelegatedTurn(
+        req({ delegationId: 'd1', userText: 'what are your hours', stream: (text) => pieces.push(text) }),
+      );
+      expect(result.text).toBe('We open at eight, and close at six. On Sundays we are closed.\n\nAnything else?');
+      // The first pieces went out while the stream was still running.
+      expect(seenBeforeEnd).toEqual(['We open at eight, ', 'and close at six. ']);
+      expect(pieces.join('')).toBe(result.text);
+      expect(result.streamedChars).toBe(result.text.length);
+    });
+
+    it('streams the answer of an approval-parked turn; the approval script is the unstreamed suffix', async () => {
+      drive('user', 'order two croissants', true, 'u1');
+      parkOnApproval();
+      const pieces: string[] = [];
+      const result = await h.state.bridge!.runDelegatedTurn(
+        req({ delegationId: 'd1', userText: 'order two croissants', stream: (text) => pieces.push(text) }),
+      );
+      expect(result.status).toBe('pending_approval');
+      expect(pieces).toEqual(['I can do that.']);
+      expect(result.streamedChars).toBe('I can do that.'.length);
+      expect(result.text.startsWith('I can do that.\n\n')).toBe(true);
+      expect(result.text.slice(result.streamedChars)).toContain("This action needs the user's approval");
+    });
+
+    it('stops streaming when the answer is rewritten, and counts only the shared prefix', async () => {
+      drive('user', 'hours', true, 'u1');
+      const pieces: string[] = [];
+      dispatch.mockImplementation(async (_options, onEvent) => {
+        const base = { id: 'assistant-rw', role: 'assistant' as const, createdAt: new Date().toISOString() };
+        onEvent({ type: 'message', message: { ...base, content: 'We open at eight. Sun', streaming: true } });
+        onEvent({ type: 'message', message: { ...base, content: 'We open at 8am. Closed Sundays.', streaming: false } });
+        onEvent({ type: 'status', status: 'idle' });
+      });
+      const result = await h.state.bridge!.runDelegatedTurn(
+        req({ delegationId: 'd1', userText: 'hours', stream: (text) => pieces.push(text) }),
+      );
+      expect(pieces).toEqual(['We open at eight. ']);
+      expect(result.text).toBe('We open at 8am. Closed Sundays.');
+      expect(result.streamedChars).toBe('We open at '.length);
+    });
+
+    it('streams a held sentence end after 200 ms of quiet, and stops on cancellation', async () => {
+      vi.useFakeTimers();
+      try {
+        drive('user', 'hours', true, 'u1');
+        const pieces: string[] = [];
+        let resume!: () => void;
+        const paused = new Promise<void>((resolve) => (resume = resolve));
+        const base = { id: 'assistant-idle', role: 'assistant' as const, createdAt: new Date().toISOString() };
+        dispatch.mockImplementation(async (_options, onEvent) => {
+          onEvent({ type: 'message', message: { ...base, content: 'We open at 8 a.m.', streaming: true } });
+          await paused;
+          onEvent({ type: 'message', message: { ...base, content: 'We open at 8 a.m. Closed Sundays.', streaming: false } });
+          onEvent({ type: 'status', status: 'idle' });
+        });
+        const turn = h.state.bridge!.runDelegatedTurn(
+          req({ delegationId: 'd1', userText: 'hours', stream: (text) => pieces.push(text) }),
+        );
+        await vi.advanceTimersByTimeAsync(199);
+        expect(pieces).toEqual([]);
+        await vi.advanceTimersByTimeAsync(1);
+        expect(pieces).toEqual(['We open at 8 a.m.']);
+        resume();
+        await vi.advanceTimersByTimeAsync(500);
+        const result = await turn;
+        expect(pieces).toEqual(['We open at 8 a.m.', ' Closed Sundays.']);
+        expect(pieces.join('')).toBe(result.text);
+        expect(result.streamedChars).toBe(result.text.length);
+
+        // Cancelled while a sentence end is held: the idle flush never fires.
+        const later: string[] = [];
+        let resume2!: () => void;
+        const paused2 = new Promise<void>((resolve) => (resume2 = resolve));
+        const base2 = { ...base, id: 'assistant-idle-2' };
+        dispatch.mockImplementation(async (_options, onEvent) => {
+          onEvent({ type: 'message', message: { ...base2, content: 'Sure thing.', streaming: true } });
+          await paused2;
+          onEvent({ type: 'message', message: { ...base2, content: 'Sure thing. Done.', streaming: false } });
+          onEvent({ type: 'status', status: 'idle' });
+        });
+        const turn2 = h.state.bridge!.runDelegatedTurn(
+          req({ delegationId: 'd2', userText: 'more', stream: (text) => later.push(text) }),
+        );
+        await vi.advanceTimersByTimeAsync(100);
+        h.state.bridge!.dropDelegation!('d2');
+        await vi.advanceTimersByTimeAsync(300);
+        expect(later).toEqual([]);
+        resume2();
+        await vi.advanceTimersByTimeAsync(500);
+        await turn2;
+        expect(later).toEqual([]);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('streams nothing and omits streamedChars without a stream callback', async () => {
+      drive('user', 'hours', true, 'u1');
+      dispatch.mockImplementation(async (_options, onEvent) => reply(onEvent, 'We open at nine. Sundays closed.'));
+      const result = await h.state.bridge!.runDelegatedTurn(req({ delegationId: 'd1', userText: 'hours' }));
+      expect(result).not.toHaveProperty('streamedChars');
+    });
+  });
+
+  it('marks only the delegated voice turn as spoken (voice: { spoken: true })', async () => {
+    dispatch.mockImplementation(async (_options, onEvent) => reply(onEvent, 'Nine to five.'));
+    await h.state.bridge!.runDelegatedTurn(req({ delegationId: 'd1', userText: 'what are your hours' }));
+    await session.sendMessage('typed question');
+    const options = dispatch.mock.calls.map(([o]) => (o as { voiceSpoken?: boolean }).voiceSpoken);
+    expect(options).toEqual([true, false]);
+  });
+
   it('follows up with the answer once the visitor approves, kept off browser TTS', async () => {
     drive('user', 'order two croissants', true, 'u1');
     parkOnApproval();

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

@@ -4,7 +4,7 @@
  *
  * 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
+ * tool definitions do not depend on the polyfill's types. These mirror the WebMCP draft
  * (`registerTool(tool, { signal })`) and the MCP tool-result envelope that
  * `@mcp-b/webmcp-polyfill` expects `execute` to return.
  */

package/src/types.ts

@@ -881,9 +881,8 @@ export type WebMcpConfirmInfo = {
   };
   /**
    * 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.)
+   * confirm-by-default gate that fires before every `webmcp:*` call. Tool
+   * callbacks on v6 receive an AbortSignal, not a nested confirmation API.
    */
   reason: 'gate';
 };
@@ -5265,6 +5264,13 @@ export type VoiceDelegationRequest = {
   userUtteranceIds: string[];
   /** The voice model's view of the conversation it delegated from. */
   messages: Array<{ role: string; content: unknown }>;
+  /**
+   * Set when the server streams delegated answers (`delegation_stream`): called
+   * with each speakable piece of the turn's answer, in order, while it renders.
+   * The pieces, concatenated, are a prefix of the result's `text`; the result
+   * says how much of it with `streamedChars`.
+   */
+  stream?: (text: string) => void;
 };
 
 /**
@@ -5305,6 +5311,12 @@ export type VoiceDelegationResult = {
    * @default true
    */
   inChat?: boolean;
+  /**
+   * How many leading characters of `text` already went out through
+   * `request.stream` (the rest, such as an approval script, is unstreamed).
+   * Omitted or 0: nothing was streamed.
+   */
+  streamedChars?: number;
   /**
    * Set when the turn parked on approvals (`text` then asks for the decision).
    * Resolves with the terminal result once the visitor decides (or the
@@ -6266,6 +6278,12 @@ export type ClientChatRequest = {
   turnId?: RuntypeClientChatRequest['turnId'];
   /** Whether this turn should interrupt a prior in-flight response (from Core public OpenAPI). */
   submitMode?: RuntypeClientChatRequest['submitMode'];
+  /**
+   * Spoken-reply hint, set on a delegated voice turn whose reply a voice model
+   * reads aloud: the server asks the agent for a speakable answer (the direct
+   * answer first, in plain sentences). Not persisted into history.
+   */
+  voice?: { spoken: true };
 };
 
 /**
@@ -7686,8 +7704,11 @@ export type AgentWidgetConfig = {
   /**
    * 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.
+   * current document's registry on every dispatch, ships it as `clientTools[]`,
+   * and executes returned `webmcp:*` calls with confirm-by-default gating.
+   * Supports host-installed v5 JSON-string and v6 object-input contracts.
+   * The automatic fallback stays on v5 to preserve existing browser support
+   * and callback-result behavior.
    *
    * Server-side policy on the chat surface is the source of truth: these
    * fields layer on top.

package/src/voice/runtype-voice-provider.ts

@@ -64,7 +64,25 @@
 // agent as conversation; a user bubble becomes conversation only when it is
 // submitted. With `context` negotiated, one `context{text}` frame (chat history
 // as of call start plus the host's `callContext`) is held until the visitor's
-// first final transcript or first delegation.
+// first final transcript or first delegation; a delegation's frames (deltas
+// and result) wait for it (up to 2 s, then it is dropped).
+//
+// Streaming (`delegation_stream` and `delegation_read_back` both negotiated,
+// with client delegation; the read-back tags are what keep a streamed answer
+// spoken as several utterances folded): while a
+// delegated turn renders, its assistant answer goes out as ordered
+// `delegation_delta{delegationId, text}` pieces (clause-sized, see
+// voice-clause-buffer.ts; approval cards, tool bubbles and captions never
+// stream), all before the delegation's first `delegation_update` or
+// `delegation_result`. That frame then carries `streamedChars`: how many
+// leading characters of its `text` the deltas already sent (an approval
+// script appended after the answer is the unstreamed rest). Absent or 0: none.
+// The server reports each spoken chunk with `delegation_progress{delegationId,
+// text}`; the first one of a spoken phase folds the read-back as
+// `delegation_completed{speak:true}` does (status stays "processing" until
+// completed), and that phase's completion doesn't fold another utterance.
+// Delegated sends carry `voice: { spoken: true }` on the chat request, so the
+// agent answers in speakable sentences.
 
 import type {
   VoiceProvider,
@@ -299,8 +317,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   // The released context's send; settles once it went out (or never will).
   #contextSend: { done: Promise<void>; drop: () => void } | null = null;
   #delegations: Promise<void> = Promise.resolve();
-  // Delegations answered ok: their spoken read-back is folded.
+  // Delegations answered ok (or that streamed part of their answer): their
+  // spoken read-back is folded.
   #answered = new Set<string>();
+  // Delegations whose current spoken phase already folded on `delegation_progress`.
+  #progressed = new Set<string>();
+  // The delegation whose read-back `#foldReadback` is waiting for.
+  #foldArmedBy: string | null = null;
   #foldReadback = false;
   #assistantTurns = new Set<string>();
   #foldedTurns = new Set<string>();
@@ -473,7 +496,7 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   #voiceSocketUrl(host: string, agentId: string, attach?: URLSearchParams): string {
     const capabilities = ["partial_transcript", "context"];
     if (this.bridge && this.config?.clientDelegation !== false)
-      capabilities.push("client_delegation", "delegation_update", "delegation_read_back");
+      capabilities.push("client_delegation", "delegation_update", "delegation_read_back", "delegation_stream");
     if (attach) capabilities.unshift("attach");
     const params = new URLSearchParams({
       voiceProtocol: VOICE_PROTOCOL,
@@ -849,6 +872,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
             const tag = msg.delegationId;
             if (typeof tag === "string" && this.#answered.has(tag) && !this.#assistantTurns.has(turnId)) {
               this.#foldedTurns.add(turnId);
+              this.#foldReadback = false;
+            } else if (this.#foldReadback && !this.#assistantTurns.has(turnId)) {
+              // Armed by `delegation_progress`: the server may leave the
+              // read-back untagged (it continued a filler it cut), so the
+              // first new utterance after it is the read-back.
+              this.#foldedTurns.add(turnId);
+              this.#foldReadback = false;
             }
           } else if (this.#foldReadback && !this.#assistantTurns.has(turnId)) {
             this.#foldedTurns.add(turnId);
@@ -891,8 +921,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         } else if (msg.speak !== false && this.#answered.has(delegationId)) {
           // Every spoken phase (the approval ask, the late result) of an answer
           // the chat shows is read back. A refusal of one that never started
-          // here has no chat answer: it renders. `final` may never come.
-          this.#foldReadback = true;
+          // here has no chat answer: it renders. `final` may never come. A
+          // phase whose first `delegation_progress` already armed the fold
+          // ends here without arming it again. With `delegation_read_back`
+          // the tag marks the read-back, so completion arms nothing (only
+          // progress does, for a read-back the server left untagged).
+          if (!this.#progressed.delete(delegationId) && !this.#capabilities.has("delegation_read_back"))
+            this.#armFold(delegationId);
         }
         this.#delegating = msg.type === "delegation_started";
         if (!this.#isSpeaking && !this.#isCancelling()) {
@@ -901,6 +936,23 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         break;
       }
 
+      case "delegation_progress": {
+        // The server handed a spoken chunk of this delegation to the voice
+        // model: its read-back is starting. The first one of a phase folds it,
+        // as `delegation_completed{speak:true}` does; later ones (and that
+        // phase's completion) don't fold another utterance. Still delegating.
+        const delegationId = String(msg.delegationId);
+        if (
+          this.#answered.has(delegationId) &&
+          !this.#progressed.has(delegationId) &&
+          !this.#cancelledDelegations.has(delegationId)
+        ) {
+          this.#progressed.add(delegationId);
+          this.#armFold(delegationId);
+        }
+        break;
+      }
+
       case "delegation_cancelled":
         // The server gave up on it: no more frames for it, and its approval
         // timers stop. The chat turn still renders. Past its deadline (or for
@@ -1021,9 +1073,19 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     if (timedOut) send.drop();
   }
 
+  /** The next new assistant utterance is this delegation's read-back: fold it. */
+  #armFold(delegationId: string): void {
+    this.#foldReadback = true;
+    this.#foldArmedBy = delegationId;
+  }
+
   /** No more frames for this delegation; its chat answer goes back to browser TTS. */
   #dropDelegation(delegationId: string, expired = false): void {
     this.#cancelledDelegations.add(delegationId);
+    // A fold it armed whose read-back never started would hide the next
+    // unrelated utterance: disarm it.
+    if (this.#foldArmedBy === delegationId) this.#foldReadback = false;
+    this.#progressed.delete(delegationId);
     this.bridge?.dropDelegation?.(delegationId, expired);
     this.#followUps.get(delegationId)?.abort();
   }
@@ -1032,28 +1094,46 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   #runDelegation(delegationId: string, request: VoiceDelegationRequest, generation: number): void {
     const bridge = this.bridge!;
     /** Send a frame for this delegation, unless the call or the delegation ended. */
-    const send = (type: "delegation_update" | "delegation_result", status: string, text: string) => {
+    const send = ({ type, ...fields }: Record<string, unknown> & { type: string }) => {
       const ws = this.#ws;
       if (generation !== this.#callGeneration || ws?.readyState !== WebSocket.OPEN) return false;
       if (this.#cancelledDelegations.has(delegationId)) return false;
-      ws.send(JSON.stringify({ type, delegationId, status, text }));
+      ws.send(JSON.stringify({ type, delegationId, ...fields }));
       return true;
     };
+    const answer = (type: "delegation_update" | "delegation_result", status: string, text: string, streamedChars = 0) =>
+      send({ type, status, text, ...(streamedChars > 0 && { streamedChars }) });
     this.#delegations = this.#delegations.then(async () => {
       // Cancelled while queued behind another turn: never start it.
       if (generation !== this.#callGeneration || this.#cancelledDelegations.has(delegationId)) return;
+      // Streaming (`delegation_stream`): the answer goes out as
+      // `delegation_delta` pieces while the chat renders it, after the call
+      // context, and all of them before the result.
+      let deltas: Promise<void> | null = null;
+      // Only with read-back tags: a streamed answer can be spoken as several
+      // utterances, and the tags are what keep all of them folded.
+      const streaming = this.#capabilities.has("delegation_stream") && this.#capabilities.has("delegation_read_back");
+      const stream = (text: string) => {
+        deltas = (deltas ?? this.#awaitContextSend()).then(() => {
+          // The chat shows what was streamed: its read-back is folded.
+          if (send({ type: "delegation_delta", text })) this.#answered.add(delegationId);
+        });
+      };
       const result: VoiceDelegationResult = await bridge
-        .runDelegatedTurn(request)
+        .runDelegatedTurn(streaming ? { ...request, stream } : request)
         .catch(() => ({ status: "failed", text: "" }));
       await this.#awaitContextSend();
+      await deltas;
+      const streamedChars = streaming ? (result.streamedChars ?? 0) : 0;
       // Parked on an approval: ask now (non-terminal), answer once the visitor
       // decides. A server that can't take an update gets the ask as the result.
       const parked = !!result.followUp;
       const update = parked && this.#capabilities.has("delegation_update");
-      const sent = send(
+      const sent = answer(
         update ? "delegation_update" : "delegation_result",
         parked && !update ? "completed" : result.status,
         result.text,
+        streamedChars,
       );
       if (!sent) return;
       if (result.status !== "failed" && result.inChat !== false) this.#answered.add(delegationId);
@@ -1068,12 +1148,12 @@ export class RuntypeVoiceProvider implements VoiceProvider {
           approvalTimeoutMs: this.config?.approvalTimeoutMs && Math.min(this.config.approvalTimeoutMs, APPROVAL_TIMEOUT_MAX_MS),
           readBack: update,
           // Another gated tool in the same turn: another (non-terminal) update.
-          onUpdate: (text) => send("delegation_update", "pending_approval", text),
+          onUpdate: (text) => answer("delegation_update", "pending_approval", text),
         })
         .then((followUp) => {
           this.#followUps.delete(delegationId);
           // Hang-up and cancellation send nothing.
-          if (update && followUp && !abort.signal.aborted) send("delegation_result", followUp.status, followUp.text);
+          if (update && followUp && !abort.signal.aborted) answer("delegation_result", followUp.status, followUp.text);
         });
     });
   }
@@ -1170,6 +1250,8 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     this.#contextSend = null;
     this.#delegations = Promise.resolve();
     this.#answered.clear();
+    this.#progressed.clear();
+    this.#foldArmedBy = null;
     this.#foldReadback = false;
     this.#assistantTurns.clear();
     this.#foldedTurns.clear();