@livekit/agents-plugin-cartesia 1.6.2 → 1.6.4

package/src/stt.test.ts

@@ -1,13 +1,22 @@
 // SPDX-FileCopyrightText: 2026 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import { APIConnectionError, APIError, DEFAULT_API_CONNECT_OPTIONS, stt } from '@livekit/agents';
 import { VAD } from '@livekit/agents-plugin-silero';
-import { stt } from '@livekit/agents-plugins-test';
-import { describe, expect, it } from 'vitest';
+import { stt as testStt } from '@livekit/agents-plugins-test';
+import { once } from 'node:events';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { STT } from './stt.js';
 
 const hasCartesiaApiKey = Boolean(process.env.CARTESIA_API_KEY);
 
+const swallowExpectedRejection = (reason: unknown) => {
+  if (reason instanceof APIError) return;
+  throw reason;
+};
+beforeAll(() => process.on('unhandledRejection', swallowExpectedRejection));
+afterAll(() => void process.off('unhandledRejection', swallowExpectedRejection));
+
 describe('Cartesia STT capabilities', () => {
   it('reports no aligned transcript for Ink-2', () => {
     const instance = new STT({ apiKey: 'test-key', model: 'ink-2' });
@@ -16,9 +25,39 @@ describe('Cartesia STT capabilities', () => {
   });
 });
 
+describe('Cartesia STT connection errors', () => {
+  it('does not retain synchronous WebSocket connection errors', async () => {
+    const secret = 'cartesia-secret-api-key-do-not-log';
+    const cartesia = new STT({ apiKey: 'test-key', baseUrl: `http://[${secret}` });
+    const errorEvent = once(cartesia, 'error') as Promise<Parameters<stt.STTCallbacks['error']>>;
+    const stream = cartesia.stream({
+      connOptions: { ...DEFAULT_API_CONNECT_OPTIONS, maxRetry: 0 },
+    });
+    const drain = (async () => {
+      for await (const _ of stream) {
+        // discard events
+      }
+    })();
+
+    try {
+      const [{ error }] = await errorEvent;
+      expect(error).toBeInstanceOf(APIConnectionError);
+      expect(error.message).toBe('SyntaxError');
+      expect(error.message).not.toContain(secret);
+      expect(error.toString()).not.toContain(secret);
+      expect((error as Error & { cause?: unknown }).cause).toBeUndefined();
+    } finally {
+      stream.close();
+      await drain.catch(() => {});
+      // Let SpeechStream.mainTask's expected rejection reach the file-level handler.
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+  });
+});
+
 if (hasCartesiaApiKey) {
   describe('Cartesia STT', async () => {
-    await stt(new STT(), await VAD.load(), { nonStreaming: false });
+    await testStt(new STT(), await VAD.load(), { nonStreaming: false });
   });
 } else {
   describe('Cartesia STT', () => {

package/src/stt.ts

@@ -4,7 +4,10 @@
 import {
   type APIConnectOptions,
   APIConnectionError,
+  APIStatusError,
   AudioByteStream,
+  DEFAULT_API_CONNECT_OPTIONS,
+  asError,
   asLanguageCode,
   calculateAudioDurationSeconds,
   getBaseLanguage,
@@ -25,6 +28,14 @@ const API_VERSION = '2026-03-01';
 const DRAIN_TIMEOUT_MS = 5000;
 const KEEPALIVE_INTERVAL_MS = 30000;
 
+const sanitizedErrorName = (error: Error): string => {
+  if (error instanceof SyntaxError) return 'SyntaxError';
+  if (error instanceof TypeError) return 'TypeError';
+  if (error instanceof RangeError) return 'RangeError';
+  if (error instanceof AggregateError) return 'AggregateError';
+  return 'Error';
+};
+
 /**
  * Fires once when the WebSocket connection is established.
  *
@@ -267,10 +278,12 @@ export class SpeechStream extends stt.SpeechStream {
   #currentTranscript = '';
   #speechDuration = 0;
   #closingWs = false;
+  #connectTimeout: number;
 
   constructor(sttInstance: STT, opts: STTOptions, connOptions?: APIConnectOptions) {
     super(sttInstance, opts.sampleRate, connOptions);
     this.#opts = { ...opts };
+    this.#connectTimeout = connOptions?.timeoutMs ?? DEFAULT_API_CONNECT_OPTIONS.timeoutMs;
   }
 
   override get label(): string {
@@ -295,12 +308,21 @@ export class SpeechStream extends stt.SpeechStream {
       const url = this.#getCartesiaUrl();
       this.#logger.debug(`Connecting to Cartesia STT: ${url}`);
 
-      const ws = new WebSocket(url, {
-        headers: {
-          [AUTHORIZATION_HEADER]: this.#opts.apiKey,
-          [VERSION_HEADER]: API_VERSION,
-        },
-      });
+      let ws: WebSocket;
+      try {
+        ws = new WebSocket(url, {
+          handshakeTimeout: this.#connectTimeout,
+          headers: {
+            [AUTHORIZATION_HEADER]: this.#opts.apiKey,
+            [VERSION_HEADER]: API_VERSION,
+          },
+        });
+      } catch (error) {
+        throw new APIConnectionError({
+          message: sanitizedErrorName(asError(error)),
+          options: { retryable: true },
+        });
+      }
       this.#ws = ws;
 
       // Cartesia returns the request id on the WS upgrade response, before any
@@ -316,16 +338,41 @@ export class SpeechStream extends stt.SpeechStream {
       });
 
       await new Promise<void>((resolve, reject) => {
-        const onOpen = () => {
+        const cleanup = () => {
+          ws.off('open', onOpen);
+          ws.off('unexpected-response', onUnexpectedResponse);
           ws.off('error', onError);
+        };
+        const onOpen = () => {
+          cleanup();
           resolve();
         };
+        const onUnexpectedResponse = (_request: unknown, response: { statusCode?: number }) => {
+          cleanup();
+          ws.on('error', () => {});
+          ws.close();
+          // Authentication headers can appear in WebSocket handshake errors.
+          const statusCode = response.statusCode ?? -1;
+          reject(
+            new APIStatusError({
+              message: `Cartesia WebSocket connection rejected with status ${statusCode}`,
+              options: { statusCode },
+            }),
+          );
+        };
         const onError = (err: Error) => {
-          ws.off('open', onOpen);
-          reject(new APIConnectionError({ message: err.message, options: { retryable: true } }));
+          cleanup();
+          // Transport errors can contain credentials in URLs.
+          reject(
+            new APIConnectionError({
+              message: sanitizedErrorName(err),
+              options: { retryable: true },
+            }),
+          );
         };
 
         ws.once('open', onOpen);
+        ws.once('unexpected-response', onUnexpectedResponse);
         ws.once('error', onError);
       });
 

package/src/tts.test.ts

@@ -1,7 +1,13 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { type APIConnectOptions, DEFAULT_API_CONNECT_OPTIONS, tts } from '@livekit/agents';
+import {
+  type APIConnectOptions,
+  APIConnectionError,
+  APIStatusError,
+  DEFAULT_API_CONNECT_OPTIONS,
+  tts,
+} from '@livekit/agents';
 import { STT } from '@livekit/agents-plugin-openai';
 import { tts as testTts } from '@livekit/agents-plugins-test';
 import { once } from 'node:events';
@@ -110,6 +116,61 @@ async function synthesizeTurn(
 }
 
 describe('Cartesia streaming pool', () => {
+  it('redacts API keys from WebSocket handshake errors', async () => {
+    const secret = 'cartesia-secret-api-key-do-not-log';
+    const wss = new WebSocketServer({
+      host: '127.0.0.1',
+      port: 0,
+      verifyClient: (_info, done) => done(false, 401, 'Unauthorized'),
+    });
+    await once(wss, 'listening');
+    const address = wss.address() as AddressInfo;
+    const cartesia = new TTS({ apiKey: secret, baseUrl: `http://127.0.0.1:${address.port}` });
+    const errorEvent = once(cartesia, 'error') as Promise<Parameters<tts.TTSCallbacks['error']>>;
+
+    try {
+      const stream = cartesia.stream({
+        connOptions: { ...DEFAULT_API_CONNECT_OPTIONS, maxRetry: 0 },
+      });
+      stream.pushText('test');
+      stream.endInput();
+
+      const [{ error }] = await errorEvent;
+      expect(error).toBeInstanceOf(APIStatusError);
+      expect((error as APIStatusError).statusCode).toBe(401);
+      expect(error.message).not.toContain(secret);
+      expect(error.toString()).not.toContain(secret);
+      stream.close();
+    } finally {
+      await cartesia.close();
+      await closeWebSocketServer(wss);
+    }
+  });
+
+  it('does not retain generic WebSocket connection errors', async () => {
+    const secret = 'cartesia-secret-api-key-do-not-log';
+    const cartesia = new TTS({ apiKey: secret, baseUrl: `http://[${secret}` });
+    const errorEvent = once(cartesia, 'error') as Promise<Parameters<tts.TTSCallbacks['error']>>;
+
+    try {
+      const stream = cartesia.stream({
+        connOptions: { ...DEFAULT_API_CONNECT_OPTIONS, maxRetry: 0 },
+      });
+      stream.pushText('test');
+      stream.endInput();
+
+      const [{ error }] = await errorEvent;
+      expect(error).toBeInstanceOf(APIConnectionError);
+      expect(error.message).toBe('SyntaxError');
+      expect(error.message).not.toContain(secret);
+      expect(error.toString()).not.toContain(secret);
+      expect((error as Error & { cause?: unknown }).cause).toBeUndefined();
+      stream.close();
+    } finally {
+      await cartesia.close();
+    }
+  });
+
   it('reuses one websocket across sequential turns', async () => {
     const { wss, baseURL } = await startWebSocketServer();
     const server = serveCartesia(wss);

package/src/tts.ts

@@ -710,6 +710,14 @@ const isRecord = (v: unknown): v is Record<string, unknown> => {
   return v !== null && typeof v === 'object';
 };
 
+const sanitizedErrorName = (error: Error): string => {
+  if (error instanceof SyntaxError) return 'SyntaxError';
+  if (error instanceof TypeError) return 'TypeError';
+  if (error instanceof RangeError) return 'RangeError';
+  if (error instanceof AggregateError) return 'AggregateError';
+  return 'Error';
+};
+
 const isAggregateErrorLike = (e: unknown): e is { errors: unknown[]; name?: string } => {
   if (!isRecord(e)) return false;
   return e.name === 'AggregateError' && Array.isArray(e.errors);
@@ -763,6 +771,7 @@ const waitForWsOpen = async ({
   const cleanup = () => {
     if (timeout) clearTimeout(timeout);
     ws.off('open', onOpen);
+    ws.off('unexpected-response', onUnexpectedResponse);
     ws.off('error', onError);
     ws.off('close', onClose);
     abortSignal?.removeEventListener('abort', onAbort);
@@ -770,6 +779,16 @@ const waitForWsOpen = async ({
 
   const onOpen = () => fut.resolve();
   const onError = (err: Error) => fut.reject(asError(err));
+  const onUnexpectedResponse = (_request: unknown, response: { statusCode?: number }) => {
+    // Authentication headers can appear in WebSocket handshake errors.
+    const statusCode = response.statusCode ?? -1;
+    fut.reject(
+      new APIStatusError({
+        message: `Cartesia WebSocket connection rejected with status ${statusCode}`,
+        options: { statusCode },
+      }),
+    );
+  };
   const onClose = (code: number, reason: Buffer) =>
     fut.reject(
       new Error(`WebSocket closed before open (code=${code}, reason=${reason.toString()})`),
@@ -777,12 +796,16 @@ const waitForWsOpen = async ({
   const onAbort = () => fut.reject(new Error('aborted'));
 
   ws.on('open', onOpen);
+  ws.on('unexpected-response', onUnexpectedResponse);
   ws.on('error', onError);
   ws.on('close', onClose);
   abortSignal?.addEventListener('abort', onAbort, { once: true });
 
   if (timeoutMs > 0) {
-    timeout = setTimeout(() => fut.reject(new Error('connect timeout')), timeoutMs);
+    timeout = setTimeout(
+      () => fut.reject(new APITimeoutError({ message: 'Cartesia WebSocket connection timed out' })),
+      timeoutMs,
+    );
   }
 
   try {
@@ -859,9 +882,11 @@ const connectCartesiaWebSocket = async ({
     }
   };
 
+  let connectError: unknown;
   try {
     return await connectOnce();
   } catch (e) {
+    connectError = e;
     // Mitigation for Node.js dual-stack (IPv6/IPv4) connect flakiness ("happy eyeballs"):
     // some environments surface `AggregateError` with nested `ETIMEDOUT` during the initial
     // WebSocket open. In that case we do a one-off retry forcing IPv4 (`family: 4`) before
@@ -871,11 +896,24 @@ const connectCartesiaWebSocket = async ({
     // - Increase the session TTS connect timeout (`connOptions.ttsConnOptions.timeoutMs`)
     // - Or adjust Node's family autoselection behavior via `NODE_OPTIONS`, e.g.
     //   `--network-family-autoselection-attempt-timeout=5000` (or disable it entirely).
-    if (hasAnyTransientCode(e) || isAggregateErrorLike(e)) {
-      return await connectOnce(4);
+    if (!(e instanceof APIError) && (hasAnyTransientCode(e) || isAggregateErrorLike(e))) {
+      try {
+        return await connectOnce(4);
+      } catch (retryError) {
+        connectError = retryError;
+      }
     }
-    throw e;
   }
+
+  if (connectError instanceof APIError) throw connectError;
+  const error = asError(connectError);
+  const isTimeout =
+    hasErrorCode(connectError, 'ETIMEDOUT') || /timed?\s*out|timeout/i.test(error.message);
+  if (isTimeout) {
+    throw new APITimeoutError({ message: 'Cartesia WebSocket connection timed out' });
+  }
+  // Transport errors can contain credentials in URLs.
+  throw new APIConnectionError({ message: sanitizedErrorName(error) });
 };
 
 const toCartesiaOptions = (