@kuralle-syrinx/cartesia 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kuralle-syrinx/cartesia",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@kuralle-syrinx/core": "2.1.0",
+    "@kuralle-syrinx/ws": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,884 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { WebSocketServer, type WebSocket } from "ws";
+import {
+  PipelineBusImpl,
+  Route,
+  type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
+  type TextToSpeechWordTimestampsPacket,
+  type TtsErrorPacket,
+} from "@kuralle-syrinx/core";
+
+import { CartesiaTTSPlugin } from "./index.js";
+
+let servers: WebSocketServer[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          for (const client of server.clients) client.terminate();
+          server.close(() => resolve());
+        }),
+    ),
+  );
+});
+
+async function createLocalServer(onConnection: (socket: WebSocket, requestUrl: string, apiKeyHeader: string) => void): Promise<string> {
+  const server = await new Promise<WebSocketServer>((resolve) => {
+    let nextServer: WebSocketServer;
+    nextServer = new WebSocketServer({ port: 0 }, () => {
+      resolve(nextServer);
+    });
+  });
+  servers.push(server);
+  server.on("connection", (socket, request) => {
+    const header = request.headers["x-api-key"];
+    onConnection(socket, request.url ?? "", Array.isArray(header) ? header[0] ?? "" : header ?? "");
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+  return `ws://127.0.0.1:${address.port}/tts/websocket`;
+}
+
+function startBus(bus: PipelineBusImpl): Promise<void> {
+  return bus.start();
+}
+
+async function waitForCondition(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error("Timed out waiting for Cartesia test condition");
+}
+
+describe("CartesiaTTSPlugin", () => {
+  it("streams text over one authenticated websocket without leaking the API key in the URL", async () => {
+    const receivedRequests: any[] = [];
+    const endpointUrl = await createLocalServer((socket, requestUrl, apiKeyHeader) => {
+      expect(requestUrl).toContain("cartesia_version=");
+      expect(requestUrl).not.toContain("test-cartesia-key");
+      expect(apiKeyHeader).toBe("test-cartesia-key");
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        receivedRequests.push(msg);
+        if (msg.transcript === "Hello there.") {
+          socket.send(JSON.stringify({
+            type: "chunk",
+            context_id: msg.context_id,
+            data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64"),
+            done: false,
+            status_code: 206,
+          }));
+        }
+        if (msg.context_id === "turn-1" && msg.continue === false) {
+          socket.send(JSON.stringify({
+            type: "done",
+            context_id: "turn-1",
+            done: true,
+            status_code: 206,
+          }));
+        }
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    const ends: TextToSpeechEndPacket[] = [];
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      text: "Hello there.",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      text: "Hello there.",
+    });
+    await waitForCondition(() => receivedRequests.length >= 2 && audio.length >= 1 && ends.length >= 1);
+
+    expect(receivedRequests).toEqual([
+      expect.objectContaining({
+        context_id: "turn-1",
+        continue: true,
+        transcript: "Hello there.",
+      }),
+      expect.objectContaining({
+        context_id: "turn-1",
+        continue: false,
+        flush: true,
+        transcript: "",
+      }),
+    ]);
+    expect(audio).toEqual([
+      expect.objectContaining({
+        contextId: "turn-1",
+        audio: new Uint8Array([1, 2, 3, 4]),
+      }),
+    ]);
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-1" })]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("cancels active Cartesia contexts on TTS interruption", async () => {
+    const receivedRequests: any[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        receivedRequests.push(JSON.parse(data.toString()));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-interrupt",
+      timestampMs: Date.now(),
+      text: "This will be interrupted.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    bus.push(Route.Critical, {
+      kind: "interrupt.tts",
+      contextId: "turn-interrupt",
+      timestampMs: Date.now(),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    expect(receivedRequests).toEqual([
+      expect.objectContaining({
+        context_id: "turn-interrupt",
+        continue: true,
+      }),
+      {
+        context_id: "turn-interrupt",
+        cancel: true,
+      },
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("drops late Cartesia audio and done frames for cancelled contexts", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.cancel === true) {
+          socket.send(JSON.stringify({
+            context_id: msg.context_id,
+            data: Buffer.from([9, 8, 7, 6]).toString("base64"),
+          }));
+          socket.send(JSON.stringify({
+            context_id: msg.context_id,
+            done: true,
+          }));
+        }
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    const ends: TextToSpeechEndPacket[] = [];
+
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-cancelled",
+      timestampMs: Date.now(),
+      text: "This generation will be cancelled.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    bus.push(Route.Critical, {
+      kind: "interrupt.tts",
+      contextId: "turn-cancelled",
+      timestampMs: Date.now(),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(audio).toEqual([]);
+    expect(ends).toEqual([]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits tts.end when Cartesia streams audio but never acknowledges flush", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.transcript !== "Hello there.") return;
+        socket.send(JSON.stringify({
+          type: "chunk",
+          context_id: msg.context_id,
+          data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64"),
+          done: false,
+          status_code: 206,
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const ends: TextToSpeechEndPacket[] = [];
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+      finish_timeout_ms: 20,
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-timeout-end",
+      timestampMs: Date.now(),
+      text: "Hello there.",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-timeout-end",
+      timestampMs: Date.now(),
+      text: "Hello there.",
+    });
+    await waitForCondition(() => ends.length >= 1);
+
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-timeout-end" })]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits a typed TTS error and closes the context when Cartesia returns an error frame", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        socket.send(JSON.stringify({
+          type: "error",
+          done: true,
+          title: "Invalid model",
+          message: "The model is not valid.",
+          error_code: "model_not_found",
+          status_code: 400,
+          context_id: msg.context_id,
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const errors: TtsErrorPacket[] = [];
+    const ends: TextToSpeechEndPacket[] = [];
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "bad-model",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-error",
+      timestampMs: Date.now(),
+      text: "This will fail.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-error",
+        component: "tts",
+      }),
+    ]);
+    expect(errors[0]!.cause.message).toContain("Invalid model");
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-error" })]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("surfaces Cartesia error field text in tts.error cause.message", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        socket.send(JSON.stringify({
+          type: "error",
+          context_id: msg.context_id,
+          status_code: 400,
+          done: true,
+          error: "Model sunsetted: The requested model has been sunsetted and is no longer available.",
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const errors: TtsErrorPacket[] = [];
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "bad-model",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-x",
+      timestampMs: Date.now(),
+      text: "This will fail.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-x",
+        component: "tts",
+      }),
+    ]);
+    expect(errors[0]!.cause.message).toContain("Model sunsetted");
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("turns malformed provider messages into TTS errors instead of throwing from the websocket listener", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", () => {
+        socket.send("{not-json");
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const errors: TtsErrorPacket[] = [];
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-malformed",
+      timestampMs: Date.now(),
+      text: "Trigger malformed provider frame.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-malformed",
+        component: "tts",
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("rejects malformed Cartesia audio payloads before playback", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        socket.send(JSON.stringify({
+          type: "chunk",
+          context_id: msg.context_id,
+          data: "not-base64",
+          done: false,
+          status_code: 206,
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    const errors: TtsErrorPacket[] = [];
+    const ends: TextToSpeechEndPacket[] = [];
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-malformed-audio",
+      timestampMs: Date.now(),
+      text: "Trigger malformed provider audio.",
+    });
+    await waitForCondition(() => errors.length > 0);
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-malformed-audio",
+      timestampMs: Date.now(),
+    });
+    await waitForCondition(() => ends.length > 0);
+
+    expect(audio).toEqual([]);
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-malformed-audio",
+        component: "tts",
+        cause: expect.objectContaining({
+          message: "Cartesia TTS provider audio data must be valid base64",
+        }),
+      }),
+    ]);
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-malformed-audio" })]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits tts.error for odd-length PCM16 provider audio without throwing into the bus pump", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        socket.send(JSON.stringify({
+          type: "chunk",
+          context_id: msg.context_id,
+          data: Buffer.from(new Uint8Array([1, 2, 3])).toString("base64"),
+          done: false,
+          status_code: 206,
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    const errors: TtsErrorPacket[] = [];
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-odd-pcm",
+      timestampMs: Date.now(),
+      text: "Trigger odd PCM.",
+    });
+    await waitForCondition(() => errors.length > 0);
+
+    expect(audio).toEqual([]);
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-odd-pcm",
+        component: "tts",
+        cause: expect.objectContaining({
+          message: expect.stringMatching(/even number of bytes/i),
+        }),
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("ignores the empty-data flush_done acknowledgement instead of treating it as malformed audio", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.transcript === "Hello there.") {
+          socket.send(JSON.stringify({
+            type: "chunk",
+            context_id: msg.context_id,
+            data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64"),
+            done: false,
+            status_code: 206,
+          }));
+        }
+        if (msg.context_id === "turn-flush" && msg.continue === false) {
+          // Real Cartesia answers a flush request with a flush_done control frame
+          // that carries an empty `data` string before the terminal done frame.
+          socket.send(JSON.stringify({
+            type: "flush_done",
+            context_id: "turn-flush",
+            data: "",
+            done: false,
+            status_code: 206,
+            flush_done: true,
+          }));
+          socket.send(JSON.stringify({
+            type: "done",
+            context_id: "turn-flush",
+            done: true,
+            status_code: 200,
+          }));
+        }
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    const errors: TtsErrorPacket[] = [];
+    const ends: TextToSpeechEndPacket[] = [];
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-flush",
+      timestampMs: Date.now(),
+      text: "Hello there.",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-flush",
+      timestampMs: Date.now(),
+    });
+    await waitForCondition(() => ends.length >= 1);
+
+    expect(errors).toEqual([]);
+    expect(audio).toEqual([
+      expect.objectContaining({
+        contextId: "turn-flush",
+        audio: new Uint8Array([1, 2, 3, 4]),
+      }),
+    ]);
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-flush" })]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("fails active contexts when the Cartesia websocket closes before provider done", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", () => {
+        socket.close(1011, "provider restart");
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const errors: TtsErrorPacket[] = [];
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-close",
+      timestampMs: Date.now(),
+      text: "This context should fail if the provider closes.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    expect(errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-close",
+        component: "tts",
+        cause: expect.objectContaining({
+          message: expect.stringContaining("WebSocket closed unexpectedly"),
+        }),
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("does not keep a Cartesia context active when the initial provider send fails", async () => {
+    const endpointUrl = await createLocalServer(() => {});
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const errors: TtsErrorPacket[] = [];
+    const ends: TextToSpeechEndPacket[] = [];
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    // Simulate a closed socket: the managed connection's send throws.
+    const send = vi.fn(() => {
+      throw new Error("WebSocket is not open");
+    });
+    Object.assign(plugin as unknown as { conn: { ensureReady: () => Promise<void>; send: typeof send; close: () => Promise<void> } }, {
+      conn: { ensureReady: async () => undefined, send, close: async () => undefined },
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-unsent",
+      timestampMs: Date.now(),
+      text: "This request never reaches Cartesia.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-unsent",
+      timestampMs: Date.now(),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    // The send was attempted but failed; the context must not stay active —
+    // an error fires and the turn ends instead of hanging.
+    expect(send).toHaveBeenCalled();
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-unsent",
+        component: "tts",
+        cause: expect.objectContaining({
+          message: "WebSocket is not open",
+        }),
+      }),
+    ]);
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-unsent" })]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits tts.word_timestamps from Cartesia's real top-level parallel-array timestamp frame", async () => {
+    const audioChunk = new Uint8Array(3200);
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.transcript === "Hello world.") {
+          socket.send(JSON.stringify({
+            type: "chunk",
+            context_id: msg.context_id,
+            data: Buffer.from(audioChunk).toString("base64"),
+            done: false,
+            status_code: 206,
+          }));
+          socket.send(JSON.stringify({
+            type: "timestamps",
+            context_id: msg.context_id,
+            word_timestamps: {
+              words: ["Hello", "world."],
+              start: [0.0, 0.5],
+              end: [0.4, 0.9],
+            },
+          }));
+        }
+        if (msg.continue === false) {
+          socket.send(JSON.stringify({ type: "done", context_id: msg.context_id, done: true, status_code: 200 }));
+        }
+      });
+    });
+
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const wordTsPackets: TextToSpeechWordTimestampsPacket[] = [];
+    bus.on("tts.word_timestamps", (pkt) => {
+      wordTsPackets.push(pkt as TextToSpeechWordTimestampsPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, { kind: "tts.text", contextId: "turn-ts", timestampMs: Date.now(), text: "Hello world." });
+    bus.push(Route.Main, { kind: "tts.done", contextId: "turn-ts", timestampMs: Date.now(), text: "Hello world." });
+    await waitForCondition(() => wordTsPackets.length >= 1);
+
+    expect(wordTsPackets[0]!.words).toEqual([
+      { word: "Hello",  startMs: 0,   endMs: 400 },
+      { word: "world.", startMs: 500, endMs: 900 },
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("does not keep a Cartesia context active when the terminal provider send fails", async () => {
+    const endpointUrl = await createLocalServer(() => {});
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const errors: TtsErrorPacket[] = [];
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-test",
+    });
+    // The first send (the transcript) succeeds; the terminal flush send fails.
+    let failNext = false;
+    const send = vi.fn(() => {
+      if (failNext) throw new Error("WebSocket is not open");
+    });
+    Object.assign(plugin as unknown as { conn: { ensureReady: () => Promise<void>; send: typeof send; close: () => Promise<void> } }, {
+      conn: { ensureReady: async () => undefined, send, close: async () => undefined },
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-terminal-unsent",
+      timestampMs: Date.now(),
+      text: "This request reaches Cartesia.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(send).toHaveBeenCalledTimes(1);
+
+    failNext = true;
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-terminal-unsent",
+      timestampMs: Date.now(),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-terminal-unsent",
+        component: "tts",
+        cause: expect.objectContaining({
+          message: "WebSocket is not open",
+        }),
+      }),
+    ]);
+    expect(send).toHaveBeenCalledTimes(2);
+
+    failNext = false;
+    bus.push(Route.Critical, {
+      kind: "interrupt.tts",
+      contextId: "turn-terminal-unsent",
+      timestampMs: Date.now(),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    // The context was already removed, so the interrupt sends no Cancel.
+    expect(send).toHaveBeenCalledTimes(2);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+});

package/src/index.ts

@@ -0,0 +1,395 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Cartesia TTS Plugin
+
+import type { PipelineBus } from "@kuralle-syrinx/core";
+import {
+  Route,
+  type AudioFormat,
+  type PluginConfig,
+  type RetryConfig,
+  type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
+  type TextToSpeechWordTimestampsPacket,
+  type TtsWordTimestamp,
+  type TtsErrorPacket,
+  type VoicePlugin,
+  assertAudioFormat,
+  assertAudioPayload,
+  categorizeTtsError,
+  isRecoverable,
+  optionalStringConfig,
+  readProviderRetryConfig,
+  requireStringConfig,
+} from "@kuralle-syrinx/core";
+import { WebSocketConnection, type SocketData, type SocketFactory } from "@kuralle-syrinx/ws";
+
+const KEEP_ALIVE_INTERVAL_MS = 10_000;
+
+export class CartesiaTTSPlugin implements VoicePlugin {
+  // socketFactory is injectable so the same plugin runs on Node (default) or
+  // Cloudflare Workers (pass createWorkersSocket).
+  constructor(private readonly socketFactory?: SocketFactory) {}
+
+  private bus: PipelineBus | null = null;
+  private conn: WebSocketConnection | null = null;
+  private apiKey = "";
+  private voiceId = "c2ac25f9-ecc4-4f56-9095-651354df60c0";
+  private modelId = "sonic-3";
+  private endpointUrl = "wss://api.cartesia.ai/tts/websocket";
+  private apiVersion = "2024-06-10";
+  private sampleRate = 16000;
+  private language = "en";
+  private retryConfig: RetryConfig = readProviderRetryConfig({});
+  private activeContexts = new Set<string>();
+  private cancelledContexts = new Set<string>();
+  private finishTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private disposers: Array<() => void> = [];
+  private audioFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 16000, channels: 1 };
+
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    this.bus = bus;
+    this.apiKey = requireStringConfig(config, "api_key");
+    this.voiceId = optionalStringConfig(config, "voice_id") ?? this.voiceId;
+    this.modelId = optionalStringConfig(config, "model_id") ?? this.modelId;
+    this.endpointUrl = optionalStringConfig(config, "endpoint_url") ?? this.endpointUrl;
+    this.apiVersion = optionalStringConfig(config, "cartesia_version") ?? this.apiVersion;
+    this.sampleRate = (config["sample_rate"] as number) ?? this.sampleRate;
+    this.language = optionalStringConfig(config, "language") ?? this.language;
+    this.retryConfig = readProviderRetryConfig(config);
+    const finishTimeoutMs = readNonNegativeInteger(config["finish_timeout_ms"], 2000);
+    this.audioFormat = { encoding: "pcm_s16le", sampleRateHz: this.sampleRate, channels: 1 };
+    assertAudioFormat(this.audioFormat);
+
+    this.conn = new WebSocketConnection({
+      url: () => {
+        const params = new URLSearchParams({ cartesia_version: this.apiVersion });
+        const separator = this.endpointUrl.includes("?") ? "&" : "?";
+        return `${this.endpointUrl}${separator}${params.toString()}`;
+      },
+      headers: { "X-API-Key": this.apiKey },
+      socketFactory: this.socketFactory ?? await defaultSocketFactory(),
+      retry: this.retryConfig,
+      replayBufferSize: (config["replay_buffer_size"] as number) ?? 32,
+      onReplay: (event, count) => {
+        this.emitMetric("", `tts.cartesia.reconnect_replay_${event}`, String(count));
+      },
+      keepAliveIntervalMs: KEEP_ALIVE_INTERVAL_MS,
+      onMessage: (data) => this.handleProviderMessage(data),
+      onConnectionLost: (err) => this.failActiveContexts(err),
+      onUnrecoverable: (err) => this.failActiveContexts(err),
+    });
+    await this.conn.connect();
+
+    this.disposers.push(
+      bus.on("tts.text", async (pkt: unknown) => {
+        const textPkt = pkt as { text: string; contextId: string };
+        await this.sendText(textPkt.text, textPkt.contextId);
+      }),
+      bus.on("tts.done", async (pkt: unknown) => {
+        const donePkt = pkt as { contextId: string };
+        if (!this.activeContexts.has(donePkt.contextId)) {
+          this.emitEnd(donePkt.contextId);
+          return;
+        }
+        if (finishTimeoutMs > 0) this.scheduleFinishTimeout(donePkt.contextId, finishTimeoutMs);
+        await this.finishContext(donePkt.contextId);
+      }),
+      bus.on("interrupt.tts", () => {
+        this.cancelActiveContexts().catch(() => {
+          // Best-effort interruption.
+        });
+      }),
+    );
+  }
+
+  async sendText(text: string, contextId: string): Promise<void> {
+    if (!text.trim()) return;
+    if (this.cancelledContexts.has(contextId)) return;
+    this.activeContexts.add(contextId);
+    const sent = await this.trySend(
+      JSON.stringify({
+        model_id: this.modelId,
+        transcript: text,
+        voice: { mode: "id", id: this.voiceId },
+        output_format: {
+          container: "raw",
+          encoding: "pcm_s16le",
+          sample_rate: this.sampleRate,
+        },
+        language: this.language,
+        context_id: contextId || crypto.randomUUID(),
+        continue: true,
+        add_timestamps: true,
+      }),
+      contextId,
+    );
+    if (!sent) {
+      this.activeContexts.delete(contextId);
+    }
+  }
+
+  /** Flush/cancel current TTS generation (called on interrupt). */
+  async flush(contextId = ""): Promise<void> {
+    if (!contextId) {
+      await this.cancelActiveContexts();
+      return;
+    }
+    await this.cancelContext(contextId);
+  }
+
+  async finishContext(contextId: string): Promise<void> {
+    if (this.cancelledContexts.has(contextId)) return;
+    const sent = await this.trySend(
+      JSON.stringify({
+        model_id: this.modelId,
+        transcript: "",
+        voice: { mode: "id", id: this.voiceId },
+        output_format: {
+          container: "raw",
+          encoding: "pcm_s16le",
+          sample_rate: this.sampleRate,
+        },
+        language: this.language,
+        context_id: contextId,
+        continue: false,
+        flush: true,
+      }),
+      contextId,
+    );
+    if (!sent) {
+      this.activeContexts.delete(contextId);
+    }
+  }
+
+  async close(): Promise<void> {
+    for (const dispose of this.disposers.splice(0)) dispose();
+    this.activeContexts.clear();
+    this.cancelledContexts.clear();
+    for (const timer of this.finishTimers.values()) clearTimeout(timer);
+    this.finishTimers.clear();
+    await this.conn?.close();
+    this.conn = null;
+    this.bus = null;
+  }
+
+  /** Send a frame, ensuring the socket is ready; emit a typed error if it cannot be sent. */
+  private async trySend(payload: string, contextId: string): Promise<boolean> {
+    try {
+      await this.conn?.ensureReady();
+      this.conn?.send(payload);
+      return true;
+    } catch (err) {
+      this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+      return false;
+    }
+  }
+
+  private async cancelActiveContexts(): Promise<void> {
+    const contextIds = [...this.activeContexts];
+    for (const contextId of contextIds) this.cancelledContexts.add(contextId);
+    this.activeContexts.clear();
+    await Promise.all(contextIds.map((contextId) => this.cancelContext(contextId)));
+  }
+
+  private async cancelContext(contextId: string): Promise<void> {
+    if (!contextId) return;
+    this.cancelledContexts.add(contextId);
+    this.activeContexts.delete(contextId);
+    this.clearFinishTimeout(contextId);
+    await this.trySend(
+      JSON.stringify({
+        context_id: contextId,
+        cancel: true,
+      }),
+      contextId,
+    );
+  }
+
+  private handleProviderMessage(data: SocketData): void {
+    if (typeof data !== "string") return; // Cartesia frames are JSON text
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(data) as Record<string, unknown>;
+    } catch (err) {
+      this.failActiveContexts(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+
+    const contextId = typeof msg["context_id"] === "string" ? msg["context_id"] : "";
+    if (this.cancelledContexts.has(contextId)) {
+      if (msg["done"] === true || msg["type"] === "error" || isErrorStatusCode(msg["status_code"])) {
+        this.cancelledContexts.delete(contextId);
+      }
+      return;
+    }
+
+    if (msg["type"] === "error" || isErrorStatusCode(msg["status_code"])) {
+      this.activeContexts.delete(contextId);
+      this.clearFinishTimeout(contextId);
+      this.emitError(contextId, cartesiaProviderError(msg));
+      if (msg["done"] === true) this.emitEnd(contextId);
+      return;
+    }
+
+    if (msg["type"] === "timestamps") {
+      this.emitWordTimestamps(contextId, msg["word_timestamps"]);
+    }
+
+    // Cartesia audio arrives as non-empty base64 `data`. Control frames such as
+    // `flush_done` (the acknowledgement of a `flush: true` request) carry an empty
+    // `data` string and must not be decoded as audio.
+    if (typeof msg["data"] === "string" && msg["data"].length > 0) {
+      try {
+        const audioBytes = decodeStrictBase64(msg["data"], "Cartesia TTS provider audio data");
+        assertAudioPayload(this.audioFormat, new Uint8Array(audioBytes));
+        const audioPacket: TextToSpeechAudioPacket = {
+          kind: "tts.audio",
+          contextId,
+          timestampMs: Date.now(),
+          audio: new Uint8Array(audioBytes),
+          sampleRateHz: this.sampleRate,
+          provider: { name: "cartesia", model: this.modelId, region: "global", cancelled: false },
+        };
+        this.bus?.push(Route.Main, audioPacket);
+      } catch (err) {
+        this.activeContexts.delete(contextId);
+        this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+    if (msg["done"] === true) {
+      this.activeContexts.delete(contextId);
+      this.clearFinishTimeout(contextId);
+      this.emitEnd(contextId);
+    }
+  }
+
+  private emitError(contextId: string, err: Error): void {
+    const category = categorizeTtsError(err);
+    const packet: TtsErrorPacket = {
+      kind: "tts.error",
+      contextId,
+      timestampMs: Date.now(),
+      component: "tts" as const,
+      category,
+      cause: err,
+      isRecoverable: isRecoverable(category),
+    };
+    this.bus?.push(Route.Critical, packet);
+  }
+
+  private scheduleFinishTimeout(contextId: string, timeoutMs: number): void {
+    this.clearFinishTimeout(contextId);
+    const timer = setTimeout(() => {
+      this.finishTimers.delete(contextId);
+      if (!this.activeContexts.has(contextId)) return;
+      this.emitMetric(contextId, "tts.cartesia.finish_timeout", String(timeoutMs));
+      this.activeContexts.delete(contextId);
+      this.emitEnd(contextId);
+    }, timeoutMs);
+    this.finishTimers.set(contextId, timer);
+  }
+
+  private clearFinishTimeout(contextId: string): void {
+    const timer = this.finishTimers.get(contextId);
+    if (!timer) return;
+    clearTimeout(timer);
+    this.finishTimers.delete(contextId);
+  }
+
+  private emitMetric(contextId: string, name: string, value: string): void {
+    this.bus?.push(Route.Background, {
+      kind: "metric.conversation",
+      contextId,
+      timestampMs: Date.now(),
+      name,
+      value,
+    });
+  }
+
+  private failActiveContexts(err: Error): void {
+    const contextIds = [...this.activeContexts];
+    this.activeContexts.clear();
+    if (contextIds.length === 0) {
+      this.emitError("", err);
+      return;
+    }
+    for (const contextId of contextIds) {
+      this.emitError(contextId, err);
+    }
+  }
+
+  private emitEnd(contextId: string): void {
+    const packet: TextToSpeechEndPacket = {
+      kind: "tts.end",
+      contextId,
+      timestampMs: Date.now(),
+    };
+    this.bus?.push(Route.Main, packet);
+  }
+
+  private emitWordTimestamps(contextId: string, value: unknown): void {
+    if (!contextId || value === null || typeof value !== "object") return;
+    const raw = value as Record<string, unknown>;
+    const rawWords = Array.isArray(raw["words"]) ? raw["words"] : [];
+    const rawStarts = Array.isArray(raw["start"]) ? raw["start"] : [];
+    const rawEnds = Array.isArray(raw["end"]) ? raw["end"] : [];
+    const count = Math.min(rawWords.length, rawStarts.length, rawEnds.length);
+    const words: TtsWordTimestamp[] = [];
+    for (let i = 0; i < count; i += 1) {
+      const word = rawWords[i];
+      const start = rawStarts[i];
+      const end = rawEnds[i];
+      if (typeof word !== "string" || typeof start !== "number" || typeof end !== "number") continue;
+      words.push({
+        word,
+        startMs: Math.round(start * 1000),
+        endMs: Math.round(end * 1000),
+      });
+    }
+    if (words.length === 0) return;
+    this.bus?.push(Route.Main, {
+      kind: "tts.word_timestamps",
+      contextId,
+      timestampMs: Date.now(),
+      words,
+    });
+  }
+}
+
+async function defaultSocketFactory(): Promise<SocketFactory> {
+  const mod = await import("@kuralle-syrinx/ws/node");
+  return mod.createNodeWsSocket;
+}
+
+function isErrorStatusCode(value: unknown): boolean {
+  return typeof value === "number" && value >= 400;
+}
+
+function cartesiaProviderError(msg: Record<string, unknown>): Error {
+  const title = typeof msg["title"] === "string" ? msg["title"] : "Cartesia TTS provider error";
+  const message = typeof msg["message"] === "string" ? msg["message"] : "";
+  const error = typeof msg["error"] === "string" ? msg["error"] : "";
+  const errorCode = typeof msg["error_code"] === "string" ? msg["error_code"] : "";
+  const statusCode = typeof msg["status_code"] === "number" ? `status ${String(msg["status_code"])}` : "";
+  const details = [message, error, errorCode, statusCode].filter((part) => part.length > 0).join(" ");
+  return new Error(details ? `${title}: ${details}` : title);
+}
+
+function decodeStrictBase64(value: string, name: string): Buffer {
+  const normalized = value.replace(/\s+/g, "");
+  if (normalized.length === 0 || normalized.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+    throw new Error(`${name} must be valid base64`);
+  }
+  const decoded = Buffer.from(normalized, "base64");
+  if (decoded.toString("base64") !== normalized) {
+    throw new Error(`${name} must be valid base64`);
+  }
+  return decoded;
+}
+
+function readNonNegativeInteger(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const integer = Math.floor(value);
+  return integer >= 0 ? integer : fallback;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}