@runtypelabs/persona 4.23.2 → 4.25.0

package/src/utils/tokens.ts

@@ -1,3 +1,4 @@
+import { CIRCLE_LAUNCHER_TOKENS } from "./launcher-variant";
 import type {
   DeepPartial,
   PersonaTheme,
@@ -9,8 +10,8 @@ import type {
   SemanticTokens,
 } from '../types/theme';
 import {
-  DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH,
   DEFAULT_FLOATING_LAUNCHER_WIDTH,
+  resolveDefaultsVersion,
 } from '../defaults';
 
 // Detached/docked panel defaults, shared by the panel token defaults, the alias
@@ -25,7 +26,7 @@ const spacing = (() => {
   return s as Record<0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64, string>;
 })();
 
-export const DEFAULT_PALETTE = {
+const DEFAULT_PALETTE_BASE = {
   colors: {
     primary: {
       50: '#ffffff',
@@ -209,7 +210,7 @@ export const DEFAULT_PALETTE = {
   },
 };
 
-export const DEFAULT_SEMANTIC: SemanticTokens = {
+const DEFAULT_SEMANTIC_BASE: SemanticTokens = {
   colors: {
     primary: 'palette.colors.primary.500',
     secondary: 'palette.colors.secondary.500',
@@ -257,7 +258,7 @@ export const DEFAULT_SEMANTIC: SemanticTokens = {
   },
 };
 
-export const DEFAULT_COMPONENTS: ComponentTokens = {
+const DEFAULT_COMPONENTS_BASE: ComponentTokens = {
   button: {
     primary: {
       // Primary Actions role: solid primary
@@ -305,13 +306,31 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
   },
   panel: {
     width: DEFAULT_FLOATING_LAUNCHER_WIDTH,
-    maxWidth: DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH,
-    height: '600px',
-    maxHeight: 'calc(100vh - 80px)',
+    // Matches the existing floating runtime geometry. `maxWidth` and
+    // `maxHeight` intentionally do not impose a second cap; ui.ts applies
+    // the responsive width and heightOffset rules for this mode.
+    maxWidth: 'none',
+    height: 'min(640px, max(200px, calc(100vh - 64px)))',
+    maxHeight: 'none',
     borderRadius: 'palette.radius.xl',
     shadow: 'palette.shadows.xl',
     inset: DEFAULT_PANEL_INSET,
     canvasBackground: DEFAULT_PANEL_CANVAS_BACKGROUND,
+    modes: {
+      floating: {
+        border: '1px solid var(--persona-border)',
+        shadow: 'palette.shadows.xl',
+        borderRadius: 'palette.radius.xl',
+      },
+      inline: {
+        border: '1px solid var(--persona-border)',
+        shadow: 'none',
+        borderRadius: 'palette.radius.xl',
+      },
+      docked: { border: 'none', shadow: 'none', borderRadius: 'palette.radius.xl' },
+      sidebar: { border: 'none', borderRadius: '0' },
+      mobile: { border: 'none', shadow: 'none', borderRadius: '0' },
+    },
   },
   header: {
     // Header role: solid primary. Border, subtitle, and action icons stay
@@ -319,11 +338,13 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     background: 'palette.colors.primary.500',
     foreground: 'palette.colors.primary.50',
     borderRadius: 'palette.radius.xl palette.radius.xl 0 0',
-    padding: 'semantic.spacing.md',
+    padding: '20px 24px',
+    minimalPadding: '16px 24px',
     iconBackground: 'palette.colors.primary.600',
     iconForeground: 'palette.colors.primary.50',
   },
   message: {
+    gap: '12px',
     user: {
       // User Messages role: solid primary
       background: 'palette.colors.primary.500',
@@ -532,6 +553,110 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
   },
 };
 
+/** Shared defaults with a small opt-in V5 overlay. */
+const DEFAULT_PALETTE_GRAY_V4 = DEFAULT_PALETTE_BASE.colors.gray;
+const DEFAULT_PALETTE_GRAY_V5 = {
+  50: '#fafafa', 100: '#f5f5f5', 200: '#e5e5e5', 300: '#d4d4d4',
+  400: '#a3a3a3', 500: '#737373', 600: '#525252', 700: '#404040',
+  800: '#262626', 900: '#171717', 950: '#0a0a0a',
+};
+
+export const DEFAULT_PALETTE_V4 = {
+  ...DEFAULT_PALETTE_BASE,
+  colors: { ...DEFAULT_PALETTE_BASE.colors, gray: DEFAULT_PALETTE_GRAY_V4 },
+};
+export const DEFAULT_PALETTE_V5 = {
+  ...DEFAULT_PALETTE_BASE,
+  colors: { ...DEFAULT_PALETTE_BASE.colors, gray: DEFAULT_PALETTE_GRAY_V5 },
+  radius: { none: '0px', sm: '4px', md: '8px', lg: '12px', xl: '16px', '2xl': '24px', full: '9999px' },
+};
+export const DEFAULT_PALETTE = DEFAULT_PALETTE_V4;
+
+export const DEFAULT_SEMANTIC_V4 = DEFAULT_SEMANTIC_BASE;
+export const DEFAULT_SEMANTIC_V5: SemanticTokens = {
+  ...DEFAULT_SEMANTIC_BASE,
+  colors: {
+    ...DEFAULT_SEMANTIC_BASE.colors,
+    surface: '#ffffff', background: '#ffffff', container: 'semantic.colors.surface',
+    textInverse: '#ffffff',
+  },
+  typography: { ...DEFAULT_SEMANTIC_BASE.typography, fontSize: '14px', lineHeight: '1.5' },
+};
+export const DEFAULT_SEMANTIC = DEFAULT_SEMANTIC_V4;
+
+export const DEFAULT_COMPONENTS_V4 = DEFAULT_COMPONENTS_BASE;
+export const DEFAULT_COMPONENTS_V5: ComponentTokens = {
+  ...DEFAULT_COMPONENTS_BASE,
+  launcher: CIRCLE_LAUNCHER_TOKENS,
+  activity: { rowHeight: "32px", labelSize: "13px", iconSize: "16px", indent: "0px", groupIndent: "0px", groupGap: "0px", groupPadding: "0px", transcriptGap: "0px", responseGap: "12px", bodyPadding: "4px 0", bodySize: "13px", bodyLineHeight: "1.5", bodyFontWeight: "400", sectionGap: "8px", bodySurface: "transparent" },
+  toolBubble: { shadow: "none" },
+  reasoningBubble: { shadow: "none" },
+  input: { ...DEFAULT_COMPONENTS_BASE.input, borderRadius: 'palette.radius.full' },
+  introCard: { ...DEFAULT_COMPONENTS_BASE.introCard, title: { fontSize: '22px', fontWeight: '500' } },
+  suggestion: {
+    chip: { ...DEFAULT_COMPONENTS_BASE.suggestion!.chip, fontWeight: '400' },
+    card: { ...DEFAULT_COMPONENTS_BASE.suggestion!.card, fontWeight: '400' },
+    list: { ...DEFAULT_COMPONENTS_BASE.suggestion!.list, fontWeight: '400' },
+  },
+  panel: {
+    ...DEFAULT_COMPONENTS_BASE.panel,
+    width: 'min(400px, calc(100vw - 24px))',
+    height: 'min(704px, calc(100dvh - 104px))',
+    borderRadius: 'palette.radius.xl',
+  },
+  header: {
+    ...DEFAULT_COMPONENTS_BASE.header,
+    background: 'semantic.colors.container', foreground: 'semantic.colors.text',
+    padding: '8px 8px 8px 16px', minimalPadding: '8px 8px 8px 16px',
+    minHeight: '48px', borderBottom: 'none',
+    iconBackground: 'transparent', iconForeground: 'semantic.colors.text', iconScale: '1',
+    controlSize: '28px', controlIconSize: '18px', controlStrokeWidth: '1.5',
+    actionIconForeground: 'semantic.colors.textMuted',
+    controlBorderRadius: '8px',
+    controlHoverBackground: 'color-mix(in srgb, var(--persona-text) 8%, transparent)',
+    controlHoverForeground: 'semantic.colors.text',
+    controlFocusOutline: '2px solid color-mix(in srgb, var(--persona-text) 50%, transparent)',
+    title: { fontSize: '14px', fontWeight: '500', lineHeight: '1.5' },
+  },
+  message: {
+    ...DEFAULT_COMPONENTS_BASE.message,
+    gap: '20px', fullscreenGap: '28px', topFadeHeight: '18px',
+    user: {
+      ...DEFAULT_COMPONENTS_BASE.message.user,
+      background: 'palette.colors.gray.100', text: 'semantic.colors.text',
+      borderRadius: 'palette.radius.xl', shadow: 'none', padding: '8px 14px',
+      fontSize: '14px', lineHeight: '1.5',
+    },
+    assistant: {
+      ...DEFAULT_COMPONENTS_BASE.message.assistant,
+      background: 'transparent', border: 'transparent', borderWidth: '0px',
+      borderRadius: '0px', shadow: 'none', padding: '0px',
+      fontSize: '14px', lineHeight: '1.55',
+    },
+  },
+  composer: {
+    ...DEFAULT_COMPONENTS_BASE.composer,
+    padding: '8px', fontSize: '15px', lineHeight: '1.5', controlSize: '32px', controlIconSize: '20px',
+    sendIconSize: '18px', sendButtonRadius: '9999px', footerBorder: 'none',
+    overlayBand: 'linear-gradient(to bottom, transparent, var(--persona-container) 24px)',
+    focusBorderColor: 'color-mix(in srgb, var(--persona-text) 28%, var(--persona-border))',
+    focusRing: '1px solid color-mix(in srgb, var(--persona-text) 12%, transparent)',
+  },
+};
+export const DEFAULT_COMPONENTS = DEFAULT_COMPONENTS_V4;
+
+export type ThemeDefaultsVersion = 'v4' | 'v5';
+
+export const resolveThemeDefaultsVersion = (future?: { v5Defaults?: boolean }): ThemeDefaultsVersion =>
+  resolveDefaultsVersion({ future });
+
+export const resolveThemeDefaults = (future?: { v5Defaults?: boolean }) => {
+  const version = resolveThemeDefaultsVersion(future);
+  return version === 'v5'
+    ? { palette: DEFAULT_PALETTE_V5, semantic: DEFAULT_SEMANTIC_V5, components: DEFAULT_COMPONENTS_V5 }
+    : { palette: DEFAULT_PALETTE_V4, semantic: DEFAULT_SEMANTIC_V4, components: DEFAULT_COMPONENTS_V4 };
+};
+
 export function resolveTokenValue(theme: PersonaTheme, path: string): string | undefined {
   if (
     !path.startsWith('palette.') &&
@@ -673,10 +798,11 @@ export function createTheme(
   userConfig?: DeepPartial<PersonaTheme>,
   options: CreateThemeOptions = {}
 ): PersonaTheme {
+  const defaults = resolveThemeDefaults(options.future);
   const baseTheme: PersonaTheme = {
-    palette: DEFAULT_PALETTE as PersonaTheme['palette'],
-    semantic: DEFAULT_SEMANTIC as PersonaTheme['semantic'],
-    components: DEFAULT_COMPONENTS as PersonaTheme['components'],
+    palette: defaults.palette as PersonaTheme['palette'],
+    semantic: defaults.semantic as PersonaTheme['semantic'],
+    components: defaults.components as PersonaTheme['components'],
   };
 
   let theme: PersonaTheme = {
@@ -738,6 +864,30 @@ export function createTheme(
     ),
   } as PersonaTheme;
 
+  // A shared header padding is also the minimal-layout override unless the
+  // host supplies the more specific token. Both keys remain emitted CSS vars,
+  // so live updates and scheme changes restyle existing header DOM in place.
+  const activity = userConfig?.components?.activity;
+  for (const kind of ['toolBubble', 'reasoningBubble'] as const) {
+    for (const field of ['rowHeight', 'labelSize', 'iconSize', 'indent', 'bodySurface'] as const) {
+      if (activity?.[field] !== undefined) theme.components[kind][field] = activity[field];
+    }
+  }
+  const legacySurface = userConfig?.components?.collapsibleWidget?.surface;
+  if (legacySurface !== undefined && activity?.bodySurface === undefined) {
+    theme.components.activity = { ...theme.components.activity, bodySurface: legacySurface };
+  }
+
+  const suppliedHeader = userConfig?.components?.header;
+  if (suppliedHeader?.padding !== undefined && suppliedHeader.minimalPadding === undefined) {
+    theme.components.header.minimalPadding = theme.components.header.padding;
+  }
+
+  const suppliedMessage = userConfig?.components?.message;
+  if (suppliedMessage?.gap !== undefined && suppliedMessage.fullscreenGap === undefined) {
+    theme.components.message.fullscreenGap = theme.components.message.gap;
+  }
+
   if (options.validate !== false) {
     const validation = validateTheme(theme);
     if (!validation.valid) {
@@ -1224,12 +1374,21 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   ]);
 
   // Collapsible widget chrome (tool/reasoning/approval bubbles)
-  cssVars['--cw-container'] =
-    cssVars['--persona-components-collapsibleWidget-container'] ?? cssVars['--persona-surface'];
-  cssVars['--cw-surface'] =
-    cssVars['--persona-components-collapsibleWidget-surface'] ?? cssVars['--persona-surface'];
-  cssVars['--cw-border'] =
-    cssVars['--persona-components-collapsibleWidget-border'] ?? cssVars['--persona-border'];
+  const collapsibleWidgetAliases = [
+    ['container', 'surface'],
+    ['surface', 'surface'],
+    ['border', 'border'],
+  ] as const;
+  for (const [name, semanticFallback] of collapsibleWidgetAliases) {
+    const value =
+      cssVars[`--persona-components-collapsibleWidget-${name}`] ??
+      cssVars[`--persona-${semanticFallback}`];
+    if (value !== undefined) {
+      cssVars[`--persona-cw-${name}`] = value;
+      // Kept for custom styles that adopted the original unprefixed aliases.
+      cssVars[`--cw-${name}`] = value;
+    }
+  }
 
   emitAliases(cssVars, [
     ['message-border', 'components-message-border', 'border'],
@@ -1246,6 +1405,7 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     ['message-user-font-family', 'components-message-user-fontFamily'],
     ['message-user-line-height', 'components-message-user-lineHeight'],
     ['message-assistant-padding', 'components-message-assistant-padding'],
+    ['message-assistant-border-width', 'components-message-assistant-borderWidth'],
     ['message-assistant-max-width', 'components-message-assistant-maxWidth'],
     ['message-assistant-font-size', 'components-message-assistant-fontSize'],
     ['message-assistant-font-family', 'components-message-assistant-fontFamily'],

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

@@ -16,6 +16,14 @@
 // A continuous always-hot mic is, in UX terms, a permanent barge-in session, so
 // `getInterruptionMode()` reports the constant `'barge-in'` and the existing
 // mic-button wiring (ui.ts) treats a click as "hang up at any state" unchanged.
+//
+// Prewarm (`prewarm()`, called on mic intent): by default a fire-and-forget
+// `POST /v1/client/agents/:agentId/voice/prewarm`. With `prewarmMode: 'attach'`
+// the WebSocket opens early with `clientCapabilities=attach` and the extra
+// `runtype.attach` subprotocol. If the server negotiates `runtype.attach`, the
+// socket idles (no call) until `startListening()` sends `{"type":"start"}`; if
+// it negotiates plain `runtype.bearer`, it ignored attach and the call is
+// already live, so `startListening()` adopts it as is.
 
 import type {
   VoiceProvider,
@@ -37,6 +45,29 @@ const CAPTURE_BUFFER_SIZE = 4096;
  */
 const LEVEL_RMS_SCALE = 4;
 const RIFF_MAGIC = 0x52494646; // "RIFF"
+/** `prewarm()` warms at most once per this window per provider instance. */
+const PREWARM_THROTTLE_MS = 30_000;
+/** How long `startListening()` waits on an attach still handshaking. */
+const ATTACH_HANDSHAKE_TIMEOUT_MS = 5_000;
+/** Attached-socket idle window: server default and clamp range. */
+const ATTACH_IDLE_DEFAULT_MS = 30_000;
+const ATTACH_IDLE_MIN_MS = 30_000;
+const ATTACH_IDLE_MAX_MS = 600_000;
+
+/** A socket opened by an `'attach'` prewarm, waiting for the click. */
+type AttachedSocket = {
+  ws: WebSocket;
+  /**
+   * `connecting` until the handshake completes; then `attached` (no call yet,
+   * needs `start`) or `live` (the server ignored attach and the call is live).
+   */
+  state: "connecting" | "attached" | "live";
+  /** Settles when the handshake completes, fails, or the socket is released. */
+  ready: Promise<void>;
+  settle: () => void;
+  openedAt: number;
+  idleTimer: ReturnType<typeof setTimeout> | undefined;
+};
 
 /**
  * Strip the canonical 44-byte WAV header (if present) and return the raw PCM16
@@ -63,6 +94,16 @@ function toWsBase(host: string): string {
   return `${secure ? "wss:" : "ws:"}//${trimmed}`;
 }
 
+/** Derive an http(s):// base URL from a configured host (the ws base, reversed). */
+function toHttpBase(host: string): string {
+  return toWsBase(host).replace(/^ws/i, "http");
+}
+
+function clampAttachIdleMs(ms: number | undefined): number {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return ATTACH_IDLE_DEFAULT_MS;
+  return Math.min(ATTACH_IDLE_MAX_MS, Math.max(ATTACH_IDLE_MIN_MS, Math.round(ms)));
+}
+
 export class RuntypeVoiceProvider implements VoiceProvider {
   type: "runtype" = "runtype";
 
@@ -87,6 +128,10 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   // Distinguishes a user-initiated close (code 1000) from a dropped connection.
   private intentionalClose = false;
 
+  // Prewarm latch and the (at most one) socket an `'attach'` prewarm opened.
+  private lastPrewarmAt = Number.NEGATIVE_INFINITY;
+  private attached: AttachedSocket | null = null;
+
   private resultCallbacks: ((result: VoiceResult) => void)[] = [];
   private errorCallbacks: ((error: Error) => void)[] = [];
   private statusCallbacks: ((status: VoiceStatus) => void)[] = [];
@@ -104,6 +149,153 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   /** No-op: the WS session opens lazily in `startListening` (the "call"). */
   async connect(): Promise<void> {}
 
+  /**
+   * Warm the voice path ahead of the click. Fire-and-forget and throttled to
+   * once per {@link PREWARM_THROTTLE_MS}; never emits an error or a status.
+   */
+  prewarm(): void {
+    if (this.callLive || this.attached) return;
+    const agentId = this.config?.agentId;
+    const token = this.config?.clientToken;
+    const host = this.config?.host;
+    if (!agentId || !token || !host) return;
+    const now = Date.now();
+    if (now - this.lastPrewarmAt < PREWARM_THROTTLE_MS) return;
+    this.lastPrewarmAt = now;
+    try {
+      if (this.config?.prewarmMode === "attach") {
+        this.attach(host, agentId, token);
+      } else {
+        this.requestPrewarm(host, agentId, token);
+      }
+    } catch {
+      // A prewarm must never surface an error; the click connects normally.
+    }
+  }
+
+  private requestPrewarm(host: string, agentId: string, token: string): void {
+    if (typeof fetch !== "function") return;
+    const url = `${toHttpBase(host)}/v1/client/agents/${encodeURIComponent(agentId)}/voice/prewarm`;
+    void fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      keepalive: true,
+    }).catch(() => {});
+  }
+
+  private attach(host: string, agentId: string, token: string): void {
+    const params = new URLSearchParams({ clientCapabilities: "attach" });
+    const configuredIdleMs = this.config?.attachIdleMs;
+    const idleMs = clampAttachIdleMs(configuredIdleMs);
+    if (configuredIdleMs !== undefined) params.set("attachIdleMs", String(idleMs));
+    const ws = new WebSocket(`${this.voiceSocketUrl(host, agentId)}?${params}`, [
+      "runtype.bearer",
+      "runtype.attach",
+      token,
+    ]);
+    ws.binaryType = "arraybuffer";
+    let settle: () => void = () => {};
+    const ready = new Promise<void>((resolve) => {
+      settle = resolve;
+    });
+    const entry: AttachedSocket = {
+      ws,
+      state: "connecting",
+      ready,
+      settle,
+      openedAt: 0,
+      idleTimer: undefined,
+    };
+    this.attached = entry;
+
+    ws.onopen = () => {
+      if (this.attached !== entry) return;
+      entry.state = ws.protocol === "runtype.attach" ? "attached" : "live";
+      entry.openedAt = Date.now();
+      this.armAttachIdle(entry, idleMs);
+      if (entry.state === "attached") ws.send('{"type":"ping"}');
+      entry.settle();
+    };
+    ws.onmessage = (event) => {
+      if (this.attached !== entry || typeof event.data !== "string") return;
+      let msg: { type?: unknown; idleMs?: unknown };
+      try {
+        msg = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      // The server's idle window is authoritative; close no later than it does.
+      if (msg.type === "attached" && typeof msg.idleMs === "number") {
+        this.armAttachIdle(entry, msg.idleMs - (Date.now() - entry.openedAt));
+      }
+    };
+    ws.onerror = () => {};
+    ws.onclose = () => {
+      if (this.attached === entry) this.releaseAttached();
+    };
+  }
+
+  private armAttachIdle(entry: AttachedSocket, ms: number): void {
+    clearTimeout(entry.idleTimer);
+    entry.idleTimer = setTimeout(() => {
+      if (this.attached === entry) this.releaseAttached();
+    }, Math.max(0, ms));
+  }
+
+  /** Close and forget the prewarmed socket, if any. Silent by design. */
+  private releaseAttached(): void {
+    const entry = this.attached;
+    if (!entry) return;
+    this.attached = null;
+    clearTimeout(entry.idleTimer);
+    const { ws } = entry;
+    ws.onopen = null;
+    ws.onmessage = null;
+    ws.onerror = null;
+    ws.onclose = null;
+    entry.settle();
+    if (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN) {
+      try {
+        ws.close(1000, "prewarm released");
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * Hand the prewarmed socket to the call, waiting up to
+   * {@link ATTACH_HANDSHAKE_TIMEOUT_MS} for a handshake still in flight.
+   * Resolves `null` when there is none, it stalled, or it dropped, so the
+   * caller opens a fresh socket.
+   */
+  private async takeAttachedSocket(): Promise<{ ws: WebSocket; live: boolean } | null> {
+    const entry = this.attached;
+    if (!entry) return null;
+    if (entry.state === "connecting") {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([
+        entry.ready,
+        new Promise<void>((resolve) => {
+          timer = setTimeout(resolve, ATTACH_HANDSHAKE_TIMEOUT_MS);
+        }),
+      ]);
+      clearTimeout(timer);
+    }
+    if (this.attached !== entry) return null;
+    if (entry.state === "connecting" || entry.ws.readyState !== WebSocket.OPEN) {
+      this.releaseAttached();
+      return null;
+    }
+    this.attached = null;
+    clearTimeout(entry.idleTimer);
+    return { ws: entry.ws, live: entry.state === "live" };
+  }
+
+  private voiceSocketUrl(host: string, agentId: string): string {
+    return `${toWsBase(host)}/ws/agents/${encodeURIComponent(agentId)}/voice`;
+  }
+
   /** Start the call: acquire mic, open the WS, stream PCM until hang-up. */
   async startListening(): Promise<void> {
     if (this.callLive) return; // idempotent: a call is already live
@@ -164,11 +356,25 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         }
       });
 
-      const wsUrl = `${toWsBase(host)}/ws/agents/${encodeURIComponent(agentId)}/voice`;
+      const adopted = await this.takeAttachedSocket();
+      if (generation !== this.callGeneration) {
+        adopted?.ws.close(1000, "client ended call");
+        return;
+      }
+      if (adopted) {
+        const { ws } = adopted;
+        this.ws = ws;
+        this.bindCallSocket(ws, generation);
+        if (!adopted.live) ws.send('{"type":"start"}');
+        this.emitStatus("listening");
+        this.startCapture(captureContext, stream, ws, generation);
+        return;
+      }
+
       // Token rides the subprotocol; `runtype.bearer` is the marker the server
       // echoes as the negotiated subprotocol (browsers fail the handshake if an
       // offered subprotocol goes unanswered).
-      const ws = new WebSocket(wsUrl, ["runtype.bearer", token]);
+      const ws = new WebSocket(this.voiceSocketUrl(host, agentId), ["runtype.bearer", token]);
       ws.binaryType = "arraybuffer";
       this.ws = ws;
 
@@ -177,31 +383,7 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         this.emitStatus("listening");
         this.startCapture(captureContext, stream, ws, generation);
       };
-
-      ws.onmessage = (event) => this.handleMessage(event, generation);
-
-      ws.onerror = () => {
-        if (generation !== this.callGeneration) return;
-        this.emitError(new Error("Voice connection failed"));
-        this.emitStatus("error");
-        this.cleanup();
-      };
-
-      ws.onclose = (evt) => {
-        if (this.intentionalClose) {
-          this.intentionalClose = false;
-          return;
-        }
-        if (generation !== this.callGeneration) return;
-        if (evt.code !== 1000) {
-          const codeMsg = evt.code ? ` (code ${evt.code})` : "";
-          this.emitError(new Error(`Voice connection closed${codeMsg}`));
-          this.emitStatus("error");
-        } else {
-          this.emitStatus("idle");
-        }
-        this.cleanup();
-      };
+      this.bindCallSocket(ws, generation);
     } catch (error) {
       this.cleanup();
       this.emitError(error as Error);
@@ -210,6 +392,34 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     }
   }
 
+  /** Route a call socket's frames, errors, and close into this call. */
+  private bindCallSocket(ws: WebSocket, generation: number): void {
+    ws.onmessage = (event) => this.handleMessage(event, generation);
+
+    ws.onerror = () => {
+      if (generation !== this.callGeneration) return;
+      this.emitError(new Error("Voice connection failed"));
+      this.emitStatus("error");
+      this.cleanup();
+    };
+
+    ws.onclose = (evt) => {
+      if (this.intentionalClose) {
+        this.intentionalClose = false;
+        return;
+      }
+      if (generation !== this.callGeneration) return;
+      if (evt.code !== 1000) {
+        const codeMsg = evt.code ? ` (code ${evt.code})` : "";
+        this.emitError(new Error(`Voice connection closed${codeMsg}`));
+        this.emitStatus("error");
+      } else {
+        this.emitStatus("idle");
+      }
+      this.cleanup();
+    };
+  }
+
   /** End the call (hang up). */
   async stopListening(): Promise<void> {
     this.cleanup();
@@ -374,6 +584,7 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     this.callGeneration += 1;
     this.callLive = false;
     this.isSpeaking = false;
+    this.releaseAttached();
 
     if (this.processor) {
       this.processor.onaudioprocess = null;