@runtypelabs/persona 4.24.0 → 4.25.0

package/dist/approval-ui.d.cts

@@ -6577,6 +6577,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6642,6 +6658,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6663,6 +6702,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6963,6 +7019,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the

package/dist/approval-ui.d.ts

@@ -6577,6 +6577,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6642,6 +6658,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6663,6 +6702,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6963,6 +7019,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the

package/dist/artifacts-ui.d.cts

@@ -6579,6 +6579,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6644,6 +6660,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6665,6 +6704,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6965,6 +7021,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the

package/dist/artifacts-ui.d.ts

@@ -6579,6 +6579,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6644,6 +6660,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6665,6 +6704,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6965,6 +7021,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the

package/dist/codegen.cjs

@@ -1,4 +1,4 @@
-"use strict";var $=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var W=(e,i)=>{for(var r in i)$(e,r,{get:i[r],enumerable:!0})},H=(e,i,r,s)=>{if(i&&typeof i=="object"||typeof i=="function")for(let a of M(i))!R.call(e,a)&&a!==r&&$(e,a,{get:()=>i[a],enumerable:!(s=T(i,a))||s.enumerable});return e};var N=e=>H($({},"__esModule",{value:!0}),e);var X={};W(X,{generateCodeSnippet:()=>I});module.exports=N(X);var j="4.24.0";var A=j;function x(e){return e?.cdnBase?.trim().replace(/\/+$/,"").replace(/[\\'"<>`]/g,r=>`%${r.charCodeAt(0).toString(16).toUpperCase().padStart(2,"0")}`)||`https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${A}/dist`}function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(i=>i.toString()).join(", ")}]`:e.toString()}function q(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var O=`({ text, message }: any) => {
+"use strict";var $=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var W=(e,i)=>{for(var r in i)$(e,r,{get:i[r],enumerable:!0})},H=(e,i,r,s)=>{if(i&&typeof i=="object"||typeof i=="function")for(let a of M(i))!R.call(e,a)&&a!==r&&$(e,a,{get:()=>i[a],enumerable:!(s=T(i,a))||s.enumerable});return e};var N=e=>H($({},"__esModule",{value:!0}),e);var X={};W(X,{generateCodeSnippet:()=>I});module.exports=N(X);var j="4.25.0";var A=j;function x(e){return e?.cdnBase?.trim().replace(/\/+$/,"").replace(/[\\'"<>`]/g,r=>`%${r.charCodeAt(0).toString(16).toUpperCase().padStart(2,"0")}`)||`https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${A}/dist`}function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(i=>i.toString()).join(", ")}]`:e.toString()}function q(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var O=`({ text, message }: any) => {
   const jsonSource = (message as any).rawContent || text || message.content;
   if (!jsonSource || typeof jsonSource !== 'string') return null;
   let cleanJson = jsonSource

package/dist/codegen.js

@@ -1,4 +1,4 @@
-var S="4.24.0";var j=S;function $(e){return e?.cdnBase?.trim().replace(/\/+$/,"").replace(/[\\'"<>`]/g,r=>`%${r.charCodeAt(0).toString(16).toUpperCase().padStart(2,"0")}`)||`https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${j}/dist`}function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(i=>i.toString()).join(", ")}]`:e.toString()}function _(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var A=`({ text, message }: any) => {
+var S="4.25.0";var j=S;function $(e){return e?.cdnBase?.trim().replace(/\/+$/,"").replace(/[\\'"<>`]/g,r=>`%${r.charCodeAt(0).toString(16).toUpperCase().padStart(2,"0")}`)||`https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${j}/dist`}function u(e){if(e!==void 0)return typeof e=="string"?e:Array.isArray(e)?`[${e.map(i=>i.toString()).join(", ")}]`:e.toString()}function _(e){if(e)return{getHeaders:u(e.getHeaders),onFeedback:u(e.onFeedback),onCopy:u(e.onCopy),requestMiddleware:u(e.requestMiddleware),actionHandlers:u(e.actionHandlers),actionParsers:u(e.actionParsers),postprocessMessage:u(e.postprocessMessage),contextProviders:u(e.contextProviders),streamParser:u(e.streamParser)}}var A=`({ text, message }: any) => {
   const jsonSource = (message as any).rawContent || text || message.content;
   if (!jsonSource || typeof jsonSource !== 'string') return null;
   let cleanJson = jsonSource

package/dist/context-mentions.d.cts

@@ -6577,6 +6577,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6642,6 +6658,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6663,6 +6702,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6963,6 +7019,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the

package/dist/context-mentions.d.ts

@@ -6577,6 +6577,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6642,6 +6658,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6663,6 +6702,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6963,6 +7019,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the

package/dist/event-stream-view.d.cts

@@ -6577,6 +6577,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6642,6 +6658,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6663,6 +6702,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6963,6 +7019,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the