@runtypelabs/persona 4.28.2 → 4.29.0

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

@@ -35,6 +35,7 @@ export type RuntypeExecutionStreamEvent = ({
   finalOutput?: string;
   iterations?: number;
   kind: "agent" | "flow";
+  outcome?: "completed" | "error" | "aborted";
   seq: number;
   stepErrorCount?: number;
   stopReason?: string;
@@ -60,6 +61,7 @@ export type RuntypeExecutionStreamEvent = ({
   executionId: string;
   finalOutput?: string;
   kind: "agent" | "flow";
+  outcome?: "completed" | "error" | "aborted";
   seq: number;
   stopReason?: string;
   type: "execution_error";
@@ -379,6 +381,15 @@ export type RuntypeExecutionStreamEvent = ({
   seq: number;
   type: "state_delta";
 }) | ({
+  annotations?: {
+  consequentialHint?: boolean;
+  debugging?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+};
   executionId: string;
   hiddenParameterNames?: Array<string>;
   iteration?: number;
@@ -477,6 +488,15 @@ export type RuntypeExecutionStreamEvent = ({
   seq: number;
   type: "approval_complete";
 }) | ({
+  annotations?: {
+  consequentialHint?: boolean;
+  debugging?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+};
   awaitReason?: string;
   awaitedAt?: string;
   crawlId?: string;
@@ -641,6 +661,15 @@ export type RuntypeClientInitResponse = {
 export type RuntypeClientChatRequest = {
   assistantMessageId?: string;
   clientTools?: Array<{
+  annotations?: {
+  consequentialHint?: boolean;
+  debugging?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+};
   description: string;
   name: string;
   origin?: "webmcp" | "sdk";
@@ -694,6 +723,15 @@ export type RuntypeClientResumeRequest = {
   after?: string;
   assistantMessageId?: string;
   clientTools?: Array<{
+  annotations?: {
+  consequentialHint?: boolean;
+  debugging?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+};
   description: string;
   name: string;
   origin?: "webmcp" | "sdk";

package/src/index-core.ts

@@ -174,6 +174,7 @@ export type {
   // WebMCP: page-discovered tool consumption
   AgentWidgetWebMcpConfig,
   ClientToolDefinition,
+  ToolAnnotations,
   WebMcpConfirmHandler,
   WebMcpConfirmInfo,
   WebMcpToolResult,
@@ -659,6 +660,16 @@ export type {
   VoiceDelegationStatus,
   VoiceDelegationFollowUp,
   VoiceSessionBridge,
+  VoiceClientTools,
+  VoiceClientToolsSnapshot,
+  VoiceClientToolsChannel,
+  VoiceClientToolsSession,
+  VoiceClientToolOutcome,
+  VoiceClientToolStatus,
+  VoiceDirectTurn,
+  ClientToolsFrame,
+  ClientToolCallFrame,
+  ClientToolResultFrame,
   PcmStreamPlayer,
   AgentWidgetVoiceStatusEvent,
   ReadAloudState,

package/src/index-global.ts

@@ -221,6 +221,12 @@ import { setVoiceRuntimeLoader } from "./voice-runtime-loader";
 
 setVoiceRuntimeLoader(siblingChunk("voice-runtime.js"));
 
+// The voice fast tier (`client_tools`), fetched by client.ts only when a voice
+// call negotiates it. Same sibling-URL scheme.
+import { setVoiceClientToolsLoader } from "./voice-client-tools-loader";
+
+setVoiceClientToolsLoader(siblingChunk("voice-client-tools.js"));
+
 // ---------------------------------------------------------------------------
 // Deferred artifacts-ui loading.
 //

package/src/session.test.ts

@@ -1259,4 +1259,30 @@ describe('AgentWidgetSession - WebMCP native approval gate', () => {
       getMessages().find((m) => m.variant === 'approval')?.approval?.status
     ).toBe('approved');
   });
+
+  it('closes the bubble and resolves false when the call signal aborts, and ignores a later click', async () => {
+    const { session, getMessages } = makeSession();
+    const abort = new AbortController();
+    const promise = session.requestWebMcpApproval({
+      toolName: 'edit_slide',
+      args: {},
+      reason: 'gate',
+      signal: abort.signal,
+    });
+    const bubble = getMessages().find((m) => m.variant === 'approval')!;
+    expect(bubble.approval?.status).toBe('pending');
+    abort.abort();
+    await expect(promise).resolves.toBe(false);
+    expect(getMessages().find((m) => m.variant === 'approval')?.approval?.status).toBe('timeout');
+    session.resolveWebMcpApproval(bubble.id, 'approved');
+    expect(getMessages().find((m) => m.variant === 'approval')?.approval?.status).toBe('timeout');
+  });
+
+  it('shows no bubble for a call whose signal already aborted', async () => {
+    const { session, getMessages } = makeSession();
+    await expect(
+      session.requestWebMcpApproval({ toolName: 'edit_slide', args: {}, reason: 'gate', signal: AbortSignal.abort() })
+    ).resolves.toBe(false);
+    expect(getMessages().some((m) => m.variant === 'approval')).toBe(false);
+  });
 });

package/src/session.ts

@@ -3076,6 +3076,7 @@ export class AgentWidgetSession {
     } catch {
       // fall through to explicit approval
     }
+    if (info.signal?.aborted) return Promise.resolve(false);
 
     const approval: AgentWidgetApproval = {
       id: `webmcp-${++this.#webMcpApprovalSeq}`,
@@ -3102,6 +3103,12 @@ export class AgentWidgetSession {
 
     return new Promise<boolean>((resolve) => {
       this.webMcpApprovalResolvers.set(approvalMessageId, resolve);
+      // The call gave up (deadline or cancel): close the card so a late click cannot look like it ran the tool.
+      info.signal?.addEventListener(
+        "abort",
+        () => this.resolveWebMcpApproval(approvalMessageId, "timeout"),
+        { once: true }
+      );
     });
   }
 
@@ -3113,7 +3120,7 @@ export class AgentWidgetSession {
    */
   public resolveWebMcpApproval(
     approvalMessageId: string,
-    decision: "approved" | "denied"
+    decision: "approved" | "denied" | "timeout"
   ): void {
     const resolve = this.webMcpApprovalResolvers.get(approvalMessageId);
     if (!resolve) return;

package/src/session.voice.test.ts

@@ -623,6 +623,49 @@ describe('AgentWidgetSession - voice client delegation bridge', () => {
     ]);
   });
 
+  it('offers no client tools when WebMCP is off', () => {
+    expect(h.state.bridge!.clientTools!()).toBeNull();
+  });
+
+  it('records a server-answered (direct) turn: the caption becomes the user turn, the readout an answer', async () => {
+    const caption = (role: 'user' | 'assistant', text: string, turnId: string) =>
+      h.state.transcriptCb!(role, text, true, { turnId, caption: true });
+    caption('user', 'Next slide', 'u1');
+    h.state.bridge!.recordDirectTurn!({
+      delegationId: 'd1',
+      userText: 'Next slide',
+      userUtteranceIds: ['u1'],
+      assistantText: 'Slide 2: Agenda.',
+    });
+    expect(view()).toEqual([
+      ['assistant', 'Welcome! How can I help?'],
+      ['user', 'Next slide'],
+      ['assistant', 'Slide 2: Agenda.'],
+    ]);
+    expect(messages.find((m) => m.content === 'Next slide')!.voiceCaption).toBeUndefined();
+    expect(spoken('voice-direct-d1')).toBe(true);
+    expect(dispatch).not.toHaveBeenCalled();
+
+    // The next typed turn carries both as conversation.
+    dispatch.mockImplementation(async (_options, onEvent) => reply(onEvent, 'Sure.', 'assistant-r2'));
+    await session.sendMessage('and the one after?');
+    const sent = dispatch.mock.calls[0][0].messages.filter((m) => !m.voiceCaption);
+    expect(sent.map((m) => m.content)).toEqual([
+      'Welcome! How can I help?',
+      'Next slide',
+      'Slide 2: Agenda.',
+      'and the one after?',
+    ]);
+  });
+
+  it('records a direct turn with no caption and no readout as just the request', () => {
+    h.state.bridge!.recordDirectTurn!({ delegationId: 'd2', userText: 'Next slide', userUtteranceIds: [], assistantText: '' });
+    expect(view()).toEqual([
+      ['assistant', 'Welcome! How can I help?'],
+      ['user', 'Next slide'],
+    ]);
+  });
+
   it('trims GPT-Live\'s leading space from bubbles and the submitted request', async () => {
     h.state.transcriptCb!('user', ' What are your opening hours', true, { turnId: 'u1', caption: true });
     dispatch.mockImplementation(async (_options, onEvent) => reply(onEvent, 'Nine to five.'));

package/src/types.ts

@@ -818,14 +818,18 @@ export type AgentWidgetAgentRequestPayload = {
 // WebMCP Types (page-discovered tools shipped per dispatch)
 // ============================================================================
 
-/**
- * Wire shape for a single client-discovered tool sent on `dispatch.clientTools[]`.
- *
- * Mirrors the SDK's `ClientToolDefinition` in `@runtypelabs/sdk`. Only the
- * JSON-serializable surface of a WebMCP tool: the `execute` function stays
- * client-side; the server merges these into the agent's tool catalog under
- * the `webmcp:` namespace.
- */
+/** Advisory WebMCP and MCP hints. These do not grant approval or safe retry. */
+export type ToolAnnotations = {
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  consequentialHint?: boolean;
+  untrustedContentHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  debugging?: boolean;
+};
+
+/** Wire metadata for a client-side tool; its execute function stays in the browser. */
 export type ClientToolDefinition = {
   /** Bare tool name; the server prepends `webmcp:` on the wire. */
   name: string;
@@ -842,20 +846,16 @@ export type ClientToolDefinition = {
   /** Origin of the page that registered the tool: for server-side audit. */
   pageOrigin?: string;
   /**
-   * WebMCP `Tool.annotations` (spec). Not used for gating server-side; the
-   * widget reads these client-side. Forwarded so traces/dashboards can show
-   * `readOnlyHint` / `untrustedContentHint` on tool-call records.
+   * WebMCP hints and MCP compatibility hints forwarded to runtime tool metadata
+   * and confirmation callbacks. No hint skips the default confirmation gate.
    */
-  annotations?: {
-    readOnlyHint?: boolean;
-    untrustedContentHint?: boolean;
-  };
+  annotations?: ToolAnnotations;
   /**
    * Hoisted copy of `annotations.untrustedContentHint`. This is the field the
    * server actually acts on (`InlineClientToolSchema`): it spotlights the
    * tool's output before the model reads it, so instructions embedded in
    * page-provided content (reviews, comments, emails) are not treated as
-   * instructions. `annotations` itself is trace/dashboard metadata only.
+   * instructions. A nested true hint also opts into output protection.
    */
   untrustedContentHint?: boolean;
 };
@@ -875,16 +875,19 @@ export type WebMcpConfirmInfo = {
    * didn't declare one.
    */
   title?: string;
-  annotations?: {
-    readOnlyHint?: boolean;
-    untrustedContentHint?: boolean;
-  };
+  annotations?: ToolAnnotations;
   /**
    * Why the confirm was requested. Currently always `'gate'`: the default
    * confirm-by-default gate that fires before every `webmcp:*` call. Tool
    * callbacks on v6 receive an AbortSignal, not a nested confirmation API.
    */
   reason: 'gate';
+  /**
+   * Aborts when the call no longer needs an answer (its deadline passed, or it
+   * was cancelled). A confirm UI should close and resolve `false`; the tool
+   * never runs after it aborts either way.
+   */
+  signal?: AbortSignal;
 };
 
 /**
@@ -5355,8 +5358,126 @@ export interface VoiceSessionBridge {
    * declined too, as the approval TTL would.
    */
   dropDelegation?(delegationId: string, expired?: boolean): void;
+  /**
+   * The page tools a voice call may offer the server's fast tier
+   * (`client_tools` / `client_tool_call`). Returns `null` when WebMCP is not
+   * enabled on this widget; the provider then does not declare `client_tools`.
+   */
+  clientTools?(): VoiceClientTools | null;
+  /**
+   * The server answered a delegation itself (`delegation_completed.route ===
+   * 'direct'`): record the visitor's turn and the spoken answer in the chat,
+   * as a delegated turn would have. `assistantText` may be empty (no readout).
+   */
+  recordDirectTurn?(turn: VoiceDirectTurn): void;
 }
 
+/** A delegation the server answered on its fast tier, for the chat history. */
+export type VoiceDirectTurn = {
+  delegationId: string;
+  userText: string;
+  userUtteranceIds: string[];
+  assistantText: string;
+};
+
+/** `client_tool_result.status` (open enum on the wire). */
+export type VoiceClientToolStatus =
+  | 'completed'
+  | 'failed'
+  | 'denied'
+  | 'stale'
+  | 'timeout'
+  | (string & {});
+
+/** What running one `client_tool_call` produced. */
+export type VoiceClientToolOutcome = {
+  status: VoiceClientToolStatus;
+  /** The page tool's return value (any JSON), on `completed`. */
+  result?: unknown;
+  error?: { message: string };
+};
+
+/** The page's tool set as of now, plus its content fingerprint. */
+export type VoiceClientToolsSnapshot = {
+  /** Exactly what `/v1/client/chat` would send as `clientTools[]` (bare names). */
+  tools: ClientToolDefinition[];
+  fingerprint: string;
+};
+
+/** WebMCP access for a voice call (see {@link VoiceSessionBridge.clientTools}). */
+export interface VoiceClientTools {
+  snapshot(): Promise<VoiceClientToolsSnapshot>;
+  /** Subscribe to registry changes; returns an unsubscribe. */
+  onChange(listener: () => void): () => void;
+  /**
+   * Run a page tool. `autoConfirmReadOnly`: skip the confirm gate when the
+   * tool's registry entry has `annotations.readOnlyHint === true`.
+   */
+  execute(
+    name: string,
+    args: Record<string, unknown>,
+    options: { signal: AbortSignal; autoConfirmReadOnly: boolean },
+  ): Promise<VoiceClientToolOutcome>;
+  /**
+   * Start the call's fast-tier session (loads its lazy chunk): it sends
+   * `client_tools` through `channel` now and on every change, and answers
+   * the `client_tool_call` frames handed to it.
+   */
+  open(channel: VoiceClientToolsChannel): Promise<VoiceClientToolsSession>;
+}
+
+/** The call socket, as the fast-tier session sees it. */
+export type VoiceClientToolsChannel = {
+  /** Send a frame; `false` when the call (socket) is gone. */
+  send(frame: ClientToolsFrame | ClientToolResultFrame): boolean;
+  /** The server cancelled this delegation: its tool results are not sent. */
+  cancelled(delegationId: string): boolean;
+};
+
+/** A call's fast-tier session (see {@link VoiceClientTools.open}). */
+export interface VoiceClientToolsSession {
+  call(frame: Partial<ClientToolCallFrame>): void;
+  /** Abort running tool calls (of one delegation, or all); they send nothing. */
+  abort(delegationId?: string): void;
+  close(): void;
+}
+
+/**
+ * Client → server (`runtype-browser-v1`, `client_tools` capability): the page's
+ * tool set, after `session_config` and whenever its fingerprint changes. Names
+ * are the FULL names the server calls back with: `webmcp:` prefixed for
+ * `origin: 'webmcp'`, bare for `sdk`.
+ */
+export type ClientToolsFrame = {
+  type: 'client_tools';
+  /** The content fingerprint the chat path computes for the same `clientTools[]`. */
+  fingerprint: string;
+  tools: ClientToolDefinition[];
+};
+
+/** Server → client: the fast tier picked a page tool for this delegation. */
+export type ClientToolCallFrame = {
+  type: 'client_tool_call';
+  delegationId: string;
+  toolCallId: string;
+  /** `webmcp:<name>` or bare; the client accepts both. */
+  name: string;
+  arguments: Record<string, unknown>;
+  /** The `client_tools` fingerprint the call was chosen from. */
+  fingerprint: string;
+  timeoutMs: number;
+};
+
+/** Client → server: the answer to one {@link ClientToolCallFrame}. */
+export type ClientToolResultFrame = {
+  type: 'client_tool_result';
+  delegationId: string;
+  toolCallId: string;
+  status: VoiceClientToolStatus;
+  result?: unknown;
+  error?: { message: string };
+};
+
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the
  * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.

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

@@ -83,8 +83,26 @@
 // 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.
+//
+// Fast tier (`client_tools`, declared only with client delegation and WebMCP
+// enabled; the session ships in the lazy voice-client-tools chunk): after
+// `session_config` the provider sends `client_tools{fingerprint, tools}`, the
+// same WebMCP snapshot and fingerprint the chat path sends as `clientTools[]`
+// but with each page tool's FULL name (`webmcp:<name>`; sdk tools stay bare),
+// and again whenever the fingerprint changes. The server may then answer a
+// delegation itself, with no `delegation_started`: it sends
+// `client_tool_call{delegationId, toolCallId, name, arguments, fingerprint,
+// timeoutMs}`, which runs through the WebMCP execute path (the confirm gate is
+// skipped only for a tool whose registry entry says `readOnlyHint: true`) and
+// is answered by one `client_tool_result{status}`: `completed`, `denied` (gate
+// declined), `stale` (unknown tool, or a fingerprint other than the last one
+// sent), `failed`, or `timeout` (past `timeoutMs`, which bounds the gate too).
+// Then `delegation_completed{route:'direct', text}` for a delegation that never
+// started here writes the heard user turn and `text` into the chat. When the
+// server falls through, the delegation arrives as today's `delegation_started`.
 
 import type {
+  VoiceClientToolsSession,
   VoiceProvider,
   VoiceResult,
   VoiceStatus,
@@ -327,6 +345,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   #foldReadback = false;
   #assistantTurns = new Set<string>();
   #foldedTurns = new Set<string>();
+  // Fast tier (see header): the call's session, from the lazy voice-client-tools chunk.
+  #fastTier: Promise<VoiceClientToolsSession | null> | null = null;
+  // Delegations this call saw start, and the last final user utterance (a direct turn's request).
+  #started = new Set<string>();
+  #heard: { id: string; text: string } | null = null;
+  // Direct turns in flight: the utterance each answers, captured at its first client_tool_call.
+  #direct = new Map<string, { id: string; text: string } | null>();
 
   #resultCallbacks: ((result: VoiceResult) => void)[] = [];
   #errorCallbacks: ((error: Error) => void)[] = [];
@@ -495,8 +520,10 @@ 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)
+    if (this.bridge && this.config?.clientDelegation !== false) {
       capabilities.push("client_delegation", "delegation_update", "delegation_read_back", "delegation_stream");
+      if (this.bridge.clientTools?.()) capabilities.push("client_tools");
+    }
     if (attach) capabilities.unshift("attach");
     const params = new URLSearchParams({
       voiceProtocol: VOICE_PROTOCOL,
@@ -849,8 +876,34 @@ export class RuntypeVoiceProvider implements VoiceProvider {
           this.#contextSent = true;
           this.#pendingContext = this.#buildContextText();
         }
+        if (this.#clientDelegation && this.#capabilities.has("client_tools") && !this.#fastTier) {
+          this.#fastTier =
+            this.bridge
+              ?.clientTools?.()
+              ?.open({
+                send: (frame) => {
+                  const ws = this.#ws;
+                  if (generation !== this.#callGeneration || ws?.readyState !== WebSocket.OPEN) return false;
+                  ws.send(JSON.stringify(frame));
+                  return true;
+                },
+                cancelled: (id) => this.#cancelledDelegations.has(id),
+              })
+              .catch(() => null) ?? null;
+        }
         break;
 
+      case "client_tool_call": {
+        // A direct turn: keep the request it answers (speech may follow) and fold its read-back.
+        const id = String(msg.delegationId);
+        if (this.#fastTier && !this.#direct.has(id)) {
+          this.#direct.set(id, this.#heard);
+          this.#answered.add(id);
+        }
+        void this.#fastTier?.then((session) => session?.call(msg));
+        break;
+      }
+
       case "transcript_update": {
         const role = msg.role === "assistant" ? "assistant" : "user";
         // A reply the client cancelled keeps streaming until the server clears it.
@@ -860,7 +913,10 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         if (role === "user") {
           // Release on a final user transcript, not a partial: a mid-utterance
           // context append makes the voice model answer early (or not delegate).
-          if (msg.final === true) this.#flushCallContext(generation);
+          if (msg.final === true) {
+            this.#flushCallContext(generation);
+            this.#heard = { id: turnId, text: String(msg.text ?? "") };
+          }
           this.#foldReadback = false;
         } else {
           // Read-back of a delegated result the chat already renders. A server
@@ -902,6 +958,10 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         const delegationId = String(msg.delegationId ?? msg.turnId);
         if (msg.type === "delegation_started") {
           this.#flushCallContext(generation);
+          this.#started.add(delegationId);
+          // A direct attempt that fell through: its answer is the chat turn's now, and its tool must not act late.
+          this.#answered.delete(delegationId);
+          if (this.#direct.delete(delegationId)) void this.#fastTier?.then((session) => session?.abort(delegationId));
           // `input`: run this turn through the chat pipeline (client delegation).
           const input = msg.input;
           if (this.#clientDelegation && input) {
@@ -918,7 +978,21 @@ export class RuntypeVoiceProvider implements VoiceProvider {
               generation,
             );
           }
-        } else if (msg.speak !== false && this.#answered.has(delegationId)) {
+        } else if (msg.route === "direct" && this.#fastTier && !this.#started.has(delegationId)) {
+          // The server answered it itself: write the request it answered and its
+          // answer into the chat, as the chat pipeline would have.
+          const heard = this.#direct.get(delegationId) ?? this.#heard;
+          this.#direct.delete(delegationId);
+          this.#started.add(delegationId);
+          this.#answered.add(delegationId);
+          this.bridge?.recordDirectTurn?.({
+            delegationId,
+            userText: heard?.text ?? "",
+            userUtteranceIds: heard ? [heard.id] : [],
+            assistantText: typeof msg.text === "string" ? msg.text : "",
+          });
+        }
+        if (msg.type === "delegation_completed" && 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. A
@@ -1086,6 +1160,9 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     // unrelated utterance: disarm it.
     if (this.#foldArmedBy === delegationId) this.#foldReadback = false;
     this.#progressed.delete(delegationId);
+    // A direct answer that never completed has no chat message to fold onto.
+    if (!this.#started.has(delegationId)) this.#answered.delete(delegationId);
+    void this.#fastTier?.then((session) => session?.abort(delegationId));
     this.bridge?.dropDelegation?.(delegationId, expired);
     this.#followUps.get(delegationId)?.abort();
   }
@@ -1255,6 +1332,11 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     this.#foldReadback = false;
     this.#assistantTurns.clear();
     this.#foldedTurns.clear();
+    void this.#fastTier?.then((session) => session?.close());
+    this.#fastTier = null;
+    this.#started.clear();
+    this.#direct.clear();
+    this.#heard = null;
     this.#finishedArmed = false;
     this.#cancelledUntil = 0;
     this.#playbackEndsAt = 0;

package/src/voice/session-voice-wiring.ts

@@ -16,7 +16,7 @@ import type { VoiceTurnTracker } from "./voice-turn-tracker";
 /** The session members the wiring touches (some are TS-private on the class). */
 export type VoiceWiringSession = Pick<
   AgentWidgetSession,
-  "injectMessage" | "sendMessage" | "resolveWebMcpApproval" | "resolveApproval"
+  "injectMessage" | "sendMessage" | "resolveWebMcpApproval" | "resolveApproval" | "getClient"
 > & {
   messages: AgentWidgetMessage[];
   callbacks: AgentWidgetSession["callbacks"];
@@ -92,6 +92,31 @@ export const wireSessionVoice = (
             // now. A stream still running reads it when it ends, once.
             if (!s.streaming) s.speakLatestAssistantMessage(ids);
           },
+          clientTools: () => s.getClient().getVoiceClientTools(),
+          recordDirect: ({ delegationId, userText, userUtteranceIds, assistantText }) => {
+            // The heard transcript bubble becomes the conversation turn, as a
+            // delegated send would make it; without one, the request text is.
+            const bubbleId = p.keyed?.claimUserTurn(userText, userUtteranceIds);
+            let claimed = false;
+            // upsertMessage merges, so it cannot drop the caption flag: replace the bubble.
+            s.messages = s.messages.map((m) => {
+              if (m.id !== bubbleId || m.role !== 'user') return m;
+              claimed = true;
+              const { voiceCaption: _caption, ...turn } = m;
+              return { ...turn, viaVoice: true };
+            });
+            if (claimed) {
+              s.callbacks.onMessagesChanged([...s.messages]);
+            } else if (userText.trim()) {
+              s.injectMessage({ role: 'user', content: userText.trim() });
+            }
+            const answer = assistantText.trim();
+            if (!answer) return;
+            // The voice model speaks this answer: browser TTS must not read it again.
+            const id = `voice-direct-${delegationId}`;
+            s.ttsSpokenMessageIds.add(id);
+            s.injectMessage({ id, role: 'assistant', content: answer });
+          },
           decide: (id) => {
             if (s.webMcpApprovalResolvers.has(id)) return s.resolveWebMcpApproval(id, 'denied');
             const approval = s.messages.find((m) => m.id === id)?.approval;