@runtypelabs/persona 4.28.2 → 4.29.0

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

@@ -0,0 +1,116 @@
+import type {
+  ClientToolCallFrame,
+  ClientToolDefinition,
+  ClientToolsFrame,
+  VoiceClientToolOutcome,
+  VoiceClientTools,
+  VoiceClientToolsChannel,
+  VoiceClientToolsSession,
+} from "../types";
+
+const WEBMCP_PREFIX = "webmcp:";
+
+/** The name the server calls a client tool back with: `webmcp:` prefixed for page tools. */
+export function voiceClientToolName(tool: ClientToolDefinition): string {
+  return tool.origin === "webmcp" && !tool.name.startsWith(WEBMCP_PREFIX) ? WEBMCP_PREFIX + tool.name : tool.name;
+}
+
+/**
+ * The fast-tier half of a voice call (see runtype-voice-provider.ts): keeps the
+ * server's `client_tools` snapshot current and answers each `client_tool_call`
+ * with exactly one `client_tool_result`. Ships in the lazy
+ * `voice-client-tools` chunk, loaded only when the server negotiates it.
+ */
+export function createVoiceClientToolsSession(
+  surface: VoiceClientTools,
+  channel: VoiceClientToolsChannel,
+): VoiceClientToolsSession {
+  let closed = false;
+  let queue = Promise.resolve();
+  let sentFingerprint: string | null = null;
+  let sent = new Map<string, ClientToolDefinition>();
+  const calls = new Map<string, { delegationId: string; abort: AbortController }>();
+
+  // Serialized, so snapshots go out in order; only a changed fingerprint is resent.
+  const sync = () => {
+    queue = queue.then(async () => {
+      const snapshot = closed ? null : await surface.snapshot().catch(() => null);
+      if (!snapshot || closed || snapshot.fingerprint === sentFingerprint) return;
+      const tools = snapshot.tools.map((tool) => ({ ...tool, name: voiceClientToolName(tool) }));
+      const frame: ClientToolsFrame = { type: "client_tools", fingerprint: snapshot.fingerprint, tools };
+      if (!channel.send(frame)) return;
+      sentFingerprint = snapshot.fingerprint;
+      sent = new Map(tools.map((tool) => [tool.name, tool]));
+    });
+  };
+
+  const abort = (delegationId?: string) => {
+    for (const [id, call] of calls) {
+      if (delegationId !== undefined && call.delegationId !== delegationId) continue;
+      calls.delete(id);
+      call.abort.abort();
+    }
+  };
+
+  const stopWatch = surface.onChange(sync);
+  sync();
+
+  return {
+    abort,
+    close() {
+      closed = true;
+      stopWatch();
+      abort();
+    },
+    call(msg: Partial<ClientToolCallFrame>) {
+      const { delegationId, toolCallId } = msg;
+      if (closed || typeof delegationId !== "string" || !delegationId || typeof toolCallId !== "string" || !toolCallId)
+        return;
+      const controller = new AbortController();
+      calls.get(toolCallId)?.abort.abort();
+      calls.set(toolCallId, { delegationId, abort: controller });
+      // Exactly one answer, unless the call was aborted (cancelled, handed back, hang-up).
+      const reply = ({ status, result, error }: VoiceClientToolOutcome) => {
+        // A replacement call with the same id owns the slot now: leave it alone.
+        if (calls.get(toolCallId)?.abort !== controller) return;
+        calls.delete(toolCallId);
+        if (closed || channel.cancelled(delegationId)) return;
+        channel.send({
+          type: "client_tool_result",
+          delegationId,
+          toolCallId,
+          status,
+          ...(result !== undefined && { result }),
+          ...(error && { error: { message: error.message } }),
+        });
+      };
+
+      const name = typeof msg.name === "string" ? msg.name : "";
+      const tool = sent.get(name) ?? sent.get(WEBMCP_PREFIX + name);
+      if (!tool || msg.fingerprint !== sentFingerprint) {
+        return reply({ status: "stale", error: { message: tool ? "The page's tools changed." : `Unknown tool: ${name}` } });
+      }
+      const args = msg.arguments && typeof msg.arguments === "object" && !Array.isArray(msg.arguments) ? msg.arguments : {};
+      const timeoutMs = typeof msg.timeoutMs === "number" && msg.timeoutMs > 0 ? msg.timeoutMs : 0;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const run = surface
+        .execute(tool.name, args, { signal: controller.signal, autoConfirmReadOnly: true })
+        .catch((error: unknown): VoiceClientToolOutcome => ({
+          status: "failed",
+          error: { message: error instanceof Error ? error.message : String(error) },
+        }));
+      // The deadline also stops a gate still waiting: a late approval must not run the tool.
+      const deadline = new Promise<VoiceClientToolOutcome>((resolve) => {
+        if (timeoutMs)
+          timer = setTimeout(() => {
+            controller.abort();
+            resolve({ status: "timeout", error: { message: `Page tool exceeded ${timeoutMs}ms.` } });
+          }, timeoutMs);
+      });
+      void Promise.race([run, deadline]).then((outcome) => {
+        clearTimeout(timer);
+        reply(outcome);
+      });
+    },
+  };
+}

package/src/voice/voice-delegation.ts

@@ -4,6 +4,8 @@ import type {
   VoiceDelegationFollowUp,
   VoiceDelegationRequest,
   VoiceDelegationResult,
+  VoiceClientTools,
+  VoiceDirectTurn,
   VoiceSessionBridge,
 } from "../types";
 
@@ -51,6 +53,10 @@ export interface VoiceDelegationHost {
   decide(approvalMessageId: string): void;
   /** Let browser TTS read these messages after all (their spoken result was dropped). */
   unspoken(messageIds: string[]): void;
+  /** WebMCP access for the voice fast tier; `null` when WebMCP is off. */
+  clientTools?(): VoiceClientTools | null;
+  /** Write a server-answered (`route: 'direct'`) turn into the chat. */
+  recordDirect?(turn: VoiceDirectTurn): void;
 }
 
 const SETTLE_POLL_MS = 50;
@@ -185,6 +191,9 @@ export function createVoiceSessionBridge(host: VoiceDelegationHost): VoiceSessio
   };
 
   return {
+    clientTools: host.clientTools,
+    recordDirectTurn: host.recordDirect,
+
     // Read once at call start, before this call has any captions, so the
     // captions here are earlier calls' (e.g. on the previous page of a
     // multi-page site): spoken conversation the new voice session never heard.

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,361 @@ 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 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',
+            ]),
+          );
+          const provider = new RuntypeVoiceProvider(baseConfig());
+          provider.setSessionBridge({ ...makeBridge().bridge, clientTools: () => null });
+          await provider.startListening();
+          expect(new URL(lastWs().url).searchParams.get('clientCapabilities')).not.toContain('client_tools');
+        });
+
+        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('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";