@runtypelabs/persona 4.24.0 → 4.25.0

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;

package/src/voice/voice.test.ts

@@ -217,14 +217,17 @@ describe('Voice Support Check', () => {
 const WS_OPEN = 1;
 
 class MockWebSocket {
+  static CONNECTING = 0;
   static OPEN = WS_OPEN;
   static instances: MockWebSocket[] = [];
 
   url: string;
   protocols: string | string[] | undefined;
+  /** Negotiated subprotocol, set by the test before `triggerOpen()`. */
+  protocol = '';
   binaryType = '';
   readyState = 0;
-  sent: ArrayBuffer[] = [];
+  sent: Array<ArrayBuffer | string> = [];
   closeCalls: Array<{ code?: number; reason?: string }> = [];
   onopen: (() => void) | null = null;
   onmessage: ((ev: { data: unknown }) => void) | null = null;
@@ -237,7 +240,7 @@ class MockWebSocket {
     MockWebSocket.instances.push(this);
   }
 
-  send(data: ArrayBuffer) {
+  send(data: ArrayBuffer | string) {
     this.sent.push(data);
   }
 
@@ -535,4 +538,271 @@ describe('RuntypeVoiceProvider (realtime streaming)', () => {
     engine.finishedCb?.(); // playback drained
     expect(statuses).toEqual(['listening']);
   });
+});
+
+describe('RuntypeVoiceProvider prewarm', () => {
+  let getUserMedia: ReturnType<typeof vi.fn>;
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    MockWebSocket.instances = [];
+    getUserMedia = vi.fn(async () => makeStream().stream);
+    fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal('WebSocket', MockWebSocket);
+    vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+    vi.stubGlobal('fetch', fetchMock);
+    (globalThis as any).window.AudioContext = MockAudioContext;
+    (globalThis as any).window.webkitAudioContext = MockAudioContext;
+    (globalThis as any).window.location = { protocol: 'https:' };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    delete (globalThis as any).window.AudioContext;
+    delete (globalThis as any).window.webkitAudioContext;
+    delete (globalThis as any).window.location;
+  });
+
+  const config = (extra: Partial<NonNullable<VoiceConfig['runtype']>> = {}) => ({
+    agentId: 'agent/1',
+    clientToken: 'ct_secret',
+    host: 'https://api.example.com',
+    ...extra,
+  });
+  const attachConfig = (extra: Partial<NonNullable<VoiceConfig['runtype']>> = {}) =>
+    config({ prewarmMode: 'attach', ...extra });
+  const lastWs = () => MockWebSocket.instances[MockWebSocket.instances.length - 1];
+  const openAs = (ws: MockWebSocket, protocol: string) => {
+    ws.protocol = protocol;
+    ws.triggerOpen();
+  };
+
+  describe("'request' mode (default)", () => {
+    it('POSTs the prewarm endpoint with the bearer token and no body', () => {
+      new RuntypeVoiceProvider(config()).prewarm();
+
+      expect(fetchMock).toHaveBeenCalledOnce();
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toBe('https://api.example.com/v1/client/agents/agent%2F1/voice/prewarm');
+      expect(init).toEqual({
+        method: 'POST',
+        headers: { Authorization: 'Bearer ct_secret' },
+        keepalive: true,
+      });
+      expect(MockWebSocket.instances).toHaveLength(0);
+    });
+
+    it.each([
+      ['http://localhost:8787', 'http://localhost:8787'],
+      ['wss://api.example.com', 'https://api.example.com'],
+      ['api.example.com', 'https://api.example.com'],
+    ])('derives the http base from %s', (host, base) => {
+      new RuntypeVoiceProvider(config({ host })).prewarm();
+      expect(fetchMock.mock.calls[0][0]).toBe(`${base}/v1/client/agents/agent%2F1/voice/prewarm`);
+    });
+
+    it('fires at most once per 30s per provider', () => {
+      const provider = new RuntypeVoiceProvider(config());
+      provider.prewarm();
+      provider.prewarm();
+      vi.advanceTimersByTime(29_999);
+      provider.prewarm();
+      expect(fetchMock).toHaveBeenCalledOnce();
+      vi.advanceTimersByTime(1);
+      provider.prewarm();
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('swallows rejected and throwing fetches without emitting errors or status', async () => {
+      const errors: Error[] = [];
+      const statuses: string[] = [];
+      fetchMock.mockRejectedValueOnce(new Error('offline'));
+      const provider = new RuntypeVoiceProvider(config());
+      provider.onError((e) => errors.push(e));
+      provider.onStatusChange((s) => statuses.push(s));
+      provider.prewarm();
+      await vi.advanceTimersByTimeAsync(30_000);
+      fetchMock.mockImplementationOnce(() => {
+        throw new Error('sync');
+      });
+      expect(() => provider.prewarm()).not.toThrow();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(errors).toEqual([]);
+      expect(statuses).toEqual([]);
+    });
+
+    it('does nothing without credentials or during a live call', async () => {
+      new RuntypeVoiceProvider(config({ clientToken: undefined })).prewarm();
+      expect(fetchMock).not.toHaveBeenCalled();
+
+      const provider = new RuntypeVoiceProvider(config());
+      await provider.startListening();
+      provider.prewarm();
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("'attach' mode", () => {
+    it('opens the voice socket with the attach capability and subprotocol, then pings', () => {
+      new RuntypeVoiceProvider(attachConfig()).prewarm();
+
+      const ws = lastWs();
+      expect(ws.url).toBe('wss://api.example.com/ws/agents/agent%2F1/voice?clientCapabilities=attach');
+      expect(ws.protocols).toEqual(['runtype.bearer', 'runtype.attach', 'ct_secret']);
+      expect(fetchMock).not.toHaveBeenCalled();
+      openAs(ws, 'runtype.attach');
+      expect(ws.sent).toEqual(['{"type":"ping"}']);
+    });
+
+    it('sends a clamped attachIdleMs when configured', () => {
+      new RuntypeVoiceProvider(attachConfig({ attachIdleMs: 5_000 })).prewarm();
+      expect(lastWs().url).toContain('clientCapabilities=attach&attachIdleMs=30000');
+    });
+
+    it('never attaches twice concurrently', () => {
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.prewarm();
+      vi.advanceTimersByTime(60_000);
+      provider.prewarm();
+      expect(MockWebSocket.instances).toHaveLength(1);
+    });
+
+    it('reuses an attached socket on click: sends start and captures on it', async () => {
+      const statuses: string[] = [];
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.onStatusChange((s) => statuses.push(s));
+      provider.prewarm();
+      const ws = lastWs();
+      openAs(ws, 'runtype.attach');
+      ws.triggerMessage('{"type":"attached","idleMs":30000}');
+
+      await provider.startListening();
+
+      expect(MockWebSocket.instances).toHaveLength(1);
+      expect(ws.sent).toEqual(['{"type":"ping"}', '{"type":"start"}']);
+      expect(statuses).toEqual(['listening']);
+      pumpCapture(constantBuffer(0.1));
+      expect(ws.sent).toHaveLength(3);
+      // The call owns the socket now: the attach idle timer no longer closes it.
+      vi.advanceTimersByTime(600_000);
+      expect(ws.closeCalls).toEqual([]);
+    });
+
+    it('adopts a socket whose server ignored attach without sending start', async () => {
+      const transcripts: string[] = [];
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.onTranscript((_role, text) => transcripts.push(text));
+      provider.prewarm();
+      const ws = lastWs();
+      openAs(ws, 'runtype.bearer');
+      expect(ws.sent).toEqual([]);
+
+      await provider.startListening();
+
+      expect(MockWebSocket.instances).toHaveLength(1);
+      expect(ws.sent).toEqual([]);
+      ws.triggerMessage(JSON.stringify({ type: 'transcript_final', role: 'user', text: 'hi' }));
+      expect(transcripts).toEqual(['hi']);
+    });
+
+    it('opens a fresh socket when the attached one dropped before the click', async () => {
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.prewarm();
+      const attached = lastWs();
+      openAs(attached, 'runtype.attach');
+      attached.triggerClose(4408);
+
+      await provider.startListening();
+
+      expect(MockWebSocket.instances).toHaveLength(2);
+      expect(lastWs().url).toBe('wss://api.example.com/ws/agents/agent%2F1/voice');
+      expect(lastWs().protocols).toEqual(['runtype.bearer', 'ct_secret']);
+    });
+
+    it('abandons a handshake stalled for 5s and opens a fresh socket', async () => {
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.prewarm();
+      const stalled = lastWs();
+
+      const started = provider.startListening();
+      await vi.advanceTimersByTimeAsync(4_999);
+      expect(MockWebSocket.instances).toHaveLength(1);
+      await vi.advanceTimersByTimeAsync(1);
+      await started;
+
+      expect(stalled.closeCalls).toEqual([{ code: 1000, reason: 'prewarm released' }]);
+      expect(MockWebSocket.instances).toHaveLength(2);
+      expect(lastWs().protocols).toEqual(['runtype.bearer', 'ct_secret']);
+    });
+
+    it('uses an attach that completes while the click waits on it', async () => {
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.prewarm();
+      const ws = lastWs();
+
+      const started = provider.startListening();
+      await vi.advanceTimersByTimeAsync(1_000);
+      openAs(ws, 'runtype.attach');
+      await started;
+
+      expect(MockWebSocket.instances).toHaveLength(1);
+      expect(ws.sent).toContain('{"type":"start"}');
+    });
+
+    it('closes an unused attached socket at the idle window', () => {
+      const errors: Error[] = [];
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.onError((e) => errors.push(e));
+      provider.prewarm();
+      const ws = lastWs();
+      openAs(ws, 'runtype.attach');
+
+      vi.advanceTimersByTime(29_999);
+      expect(ws.closeCalls).toEqual([]);
+      vi.advanceTimersByTime(1);
+      expect(ws.closeCalls).toEqual([{ code: 1000, reason: 'prewarm released' }]);
+      expect(errors).toEqual([]);
+    });
+
+    it("follows the server's idle window from the attached reply", () => {
+      const provider = new RuntypeVoiceProvider(attachConfig({ attachIdleMs: 120_000 }));
+      provider.prewarm();
+      const ws = lastWs();
+      openAs(ws, 'runtype.attach');
+      vi.advanceTimersByTime(1_000);
+      ws.triggerMessage('{"type":"attached","idleMs":60000}');
+
+      vi.advanceTimersByTime(58_999);
+      expect(ws.closeCalls).toEqual([]);
+      vi.advanceTimersByTime(1);
+      expect(ws.closeCalls).toHaveLength(1);
+    });
+
+    it('closes the attaching socket when the call is hung up mid-handshake', async () => {
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.prewarm();
+      const ws = lastWs();
+
+      const started = provider.startListening();
+      await vi.advanceTimersByTimeAsync(100);
+      await provider.stopListening();
+      await started;
+
+      expect(ws.closeCalls).toEqual([{ code: 1000, reason: 'prewarm released' }]);
+      expect(MockWebSocket.instances).toHaveLength(1);
+      expect(provider.isBargeInActive()).toBe(false);
+    });
+
+    it('disconnect closes an attached socket', async () => {
+      const provider = new RuntypeVoiceProvider(attachConfig());
+      provider.prewarm();
+      const ws = lastWs();
+      openAs(ws, 'runtype.attach');
+      await provider.disconnect();
+      expect(ws.closeCalls).toEqual([{ code: 1000, reason: 'prewarm released' }]);
+    });
+  });
 });

package/dist/voice-runtime-EFR3R5ES.js

@@ -1 +0,0 @@
-import{a as m}from"./chunk-5EIIHQLQ.js";var g=16e3,y=24e3,k=4096,C=4,S=1380533830;function E(r){return r.byteLength>=44&&new DataView(r).getUint32(0,!1)===S?new Uint8Array(r,44):new Uint8Array(r)}function V(r){let t=r.replace(/\/+$/,"");return/^wss?:\/\//i.test(t)?t:/^https?:\/\//i.test(t)?t.replace(/^http/i,"ws"):`${typeof window<"u"&&window.location?.protocol==="https:"?"wss:":"ws:"}//${t}`}var d=class{constructor(t){this.config=t;this.type="runtype";this.ws=null;this.captureContext=null;this.levelCallbacks=[];this.mediaStream=null;this.sourceNode=null;this.processor=null;this.playback=null;this.callLive=!1;this.isSpeaking=!1;this.callGeneration=0;this.intentionalClose=!1;this.resultCallbacks=[];this.errorCallbacks=[];this.statusCallbacks=[];this.transcriptCallbacks=[];this.metricsCallbacks=[]}async connect(){}async startListening(){if(this.callLive)return;let t=this.config?.agentId,e=this.config?.clientToken,i=this.config?.host;if(!t)throw new Error("Runtype voice requires an agentId");if(!e)throw new Error("Runtype voice requires a clientToken");if(!i)throw new Error("Runtype voice requires a host (or widget apiUrl)");let s=++this.callGeneration;this.intentionalClose=!1,this.callLive=!0;try{let o=await navigator.mediaDevices.getUserMedia({audio:{sampleRate:g,channelCount:1,echoCancellation:!0}});if(s!==this.callGeneration){o.getTracks().forEach(a=>a.stop());return}this.mediaStream=o;let p=window.AudioContext||window.webkitAudioContext,u=new p({sampleRate:g});u.state==="suspended"&&await u.resume().catch(()=>{}),this.captureContext=u;let l=this.config?.createPlaybackEngine?await this.config.createPlaybackEngine():new m(y);if(s!==this.callGeneration){l.destroy(),o.getTracks().forEach(a=>a.stop()),u.close().catch(()=>{});return}this.playback=l,l.onFinished(()=>{s===this.callGeneration&&(this.isSpeaking=!1,this.ws&&this.ws.readyState===WebSocket.OPEN&&this.emitStatus("listening"))});let f=`${V(i)}/ws/agents/${encodeURIComponent(t)}/voice`,n=new WebSocket(f,["runtype.bearer",e]);n.binaryType="arraybuffer",this.ws=n,n.onopen=()=>{s===this.callGeneration&&(this.emitStatus("listening"),this.startCapture(u,o,n,s))},n.onmessage=a=>this.handleMessage(a,s),n.onerror=()=>{s===this.callGeneration&&(this.emitError(new Error("Voice connection failed")),this.emitStatus("error"),this.cleanup())},n.onclose=a=>{if(this.intentionalClose){this.intentionalClose=!1;return}if(s===this.callGeneration){if(a.code!==1e3){let c=a.code?` (code ${a.code})`:"";this.emitError(new Error(`Voice connection closed${c}`)),this.emitStatus("error")}else this.emitStatus("idle");this.cleanup()}}}catch(o){throw this.cleanup(),this.emitError(o),this.emitStatus("error"),o}}async stopListening(){this.cleanup(),this.emitStatus("idle")}async disconnect(){this.cleanup(),this.emitStatus("disconnected"),this.resultCallbacks=[],this.errorCallbacks=[],this.statusCallbacks=[],this.transcriptCallbacks=[],this.metricsCallbacks=[]}stopPlayback(){this.playback&&this.playback.flush(),this.isSpeaking=!1,this.ws&&this.ws.readyState===WebSocket.OPEN&&this.emitStatus("listening")}getInterruptionMode(){return"barge-in"}isBargeInActive(){return this.callLive}onLevel(t){this.levelCallbacks.push(t)}async deactivateBargeIn(){this.cleanup(),this.emitStatus("idle")}startCapture(t,e,i,s){let o=t.createMediaStreamSource(e);this.sourceNode=o;let p=t.createScriptProcessor(k,1,1);this.processor=p,p.onaudioprocess=u=>{if(s!==this.callGeneration||i.readyState!==WebSocket.OPEN)return;let l=u.inputBuffer.getChannelData(0),f=new Int16Array(l.length),n=0;for(let a=0;a<l.length;a++){let c=Math.max(-1,Math.min(1,l[a]));n+=c*c,f[a]=c<0?c*32768:c*32767}if(i.send(f.buffer),this.levelCallbacks.length>0){let a=Math.sqrt(n/l.length),c=Math.max(0,Math.min(1,a*C));for(let b of this.levelCallbacks)b(c)}},o.connect(p),p.connect(t.destination)}handleMessage(t,e){if(e!==this.callGeneration)return;if(t.data instanceof ArrayBuffer){this.handleAudioFrame(t.data,e);return}let i;try{i=JSON.parse(t.data)}catch{return}switch(i.type){case"transcript_interim":this.emitStatus("listening"),this.emitTranscript("user",i.text??"",!1);break;case"transcript_final":{let s=i.role==="assistant"?"assistant":"user";this.emitStatus(s==="user"?"processing":"speaking"),this.emitTranscript(s,i.text??"",!0);break}case"audio_end":this.playback?this.playback.markStreamEnd():(this.isSpeaking=!1,this.emitStatus("listening"));break;case"metrics":this.emitMetrics({llmMs:i.llm_ms,ttsMs:i.tts_ms,firstAudioMs:i.first_audio_ms,totalMs:i.total_ms});break;case"error":this.emitError(new Error(i.error||"Voice error")),this.emitStatus("error");break}}handleAudioFrame(t,e){if(e!==this.callGeneration||!this.playback)return;let i=E(t);i.length!==0&&(this.isSpeaking||(this.isSpeaking=!0,this.emitStatus("speaking")),this.playback.enqueue(i))}cleanup(){if(this.callGeneration+=1,this.callLive=!1,this.isSpeaking=!1,this.processor&&(this.processor.onaudioprocess=null,this.processor.disconnect(),this.processor=null),this.sourceNode&&(this.sourceNode.disconnect(),this.sourceNode=null),this.mediaStream&&(this.mediaStream.getTracks().forEach(t=>t.stop()),this.mediaStream=null),this.captureContext&&(this.captureContext.close().catch(()=>{}),this.captureContext=null),this.playback&&(this.playback.destroy(),this.playback=null),this.ws){this.intentionalClose=!0;try{this.ws.close(1e3,"client ended call")}catch{}this.ws=null}}onResult(t){this.resultCallbacks.push(t)}onError(t){this.errorCallbacks.push(t)}onStatusChange(t){this.statusCallbacks.push(t)}onTranscript(t){this.transcriptCallbacks.push(t)}onMetrics(t){this.metricsCallbacks.push(t)}emitStatus(t){this.statusCallbacks.forEach(e=>e(t))}emitError(t){this.errorCallbacks.forEach(e=>e(t))}emitTranscript(t,e,i){this.transcriptCallbacks.forEach(s=>s(t,e,i))}emitMetrics(t){this.metricsCallbacks.forEach(e=>e(t))}};var h=class{constructor(t={}){this.config=t;this.type="browser";this.recognition=null;this.resultCallbacks=[];this.errorCallbacks=[];this.statusCallbacks=[];this.isListening=!1;this.w=typeof window<"u"?window:void 0}async connect(){this.statusCallbacks.forEach(t=>t("connected"))}async startListening(){try{if(this.isListening)throw new Error("Already listening");if(!this.w)throw new Error("Window object not available");let t=this.w.SpeechRecognition||this.w.webkitSpeechRecognition;if(!t)throw new Error("Browser speech recognition not supported");this.recognition=new t,this.recognition.lang=this.config?.language||"en-US",this.recognition.continuous=this.config?.continuous||!1,this.recognition.interimResults=!0,this.recognition.onresult=e=>{let i=Array.from(e.results).map(o=>o[0]).map(o=>o.transcript).join(""),s=e.results[e.results.length-1].isFinal;this.resultCallbacks.forEach(o=>o({text:i,confidence:s?.8:.5,provider:"browser"})),s&&!this.config?.continuous&&this.stopListening()},this.recognition.onerror=e=>{this.errorCallbacks.forEach(i=>i(new Error(e.error))),this.statusCallbacks.forEach(i=>i("error"))},this.recognition.onstart=()=>{this.isListening=!0,this.statusCallbacks.forEach(e=>e("listening"))},this.recognition.onend=()=>{this.isListening=!1,this.statusCallbacks.forEach(e=>e("idle"))},this.recognition.start()}catch(t){throw this.errorCallbacks.forEach(e=>e(t)),this.statusCallbacks.forEach(e=>e("error")),t}}async stopListening(){this.recognition&&(this.recognition.stop(),this.recognition=null),this.isListening=!1,this.statusCallbacks.forEach(t=>t("idle"))}onResult(t){this.resultCallbacks.push(t)}onError(t){this.errorCallbacks.push(t)}onStatusChange(t){this.statusCallbacks.push(t)}async disconnect(){await this.stopListening(),this.statusCallbacks.forEach(t=>t("disconnected"))}static isSupported(){return"SpeechRecognition"in window||"webkitSpeechRecognition"in window}};function v(r){switch(r.type){case"runtype":if(!r.runtype)throw new Error("Runtype voice provider requires configuration");return new d(r.runtype);case"browser":if(!h.isSupported())throw new Error("Browser speech recognition not supported");return new h(r.browser||{});case"custom":{let t=r.custom;if(!t)throw new Error("Custom voice provider requires a `custom` provider instance or factory");let e=typeof t=="function"?t():t;if(!e||typeof e.startListening!="function")throw new Error("Custom voice provider `custom` must be a VoiceProvider (or a factory returning one)");return e}default:throw new Error(`Unknown voice provider type: ${r.type}`)}}function w(r){if(r?.type==="custom"&&r.custom)return v({type:"custom",custom:r.custom});if(r?.type==="runtype"&&r.runtype)return v({type:"runtype",runtype:r.runtype});if(h.isSupported())return v({type:"browser",browser:r?.browser||{language:"en-US"}});throw new Error("No supported voice providers available")}function P(r){try{return w(r),!0}catch{return!1}}export{h as BrowserVoiceProvider,d as RuntypeVoiceProvider,w as createBestAvailableVoiceProvider,v as createVoiceProvider,P as isVoiceSupported};