@kuralle-syrinx/cartesia 4.4.1 → 4.5.0

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { type AudioFormat, type PipelineBus, type PluginConfig, type VoicePlugin } from "@kuralle-syrinx/core";
+import { type AttributionKey, type WireEvent, type WireProtocol } from "@kuralle-syrinx/tts-core";
+import type { SocketData, SocketFactory } from "@kuralle-syrinx/ws";
+interface CartesiaWireConfig {
+    readonly modelId: string;
+    readonly voiceId: string;
+    readonly sampleRate: number;
+    readonly language: string;
+    readonly audioFormat: AudioFormat;
+    readonly addTimestamps: boolean;
+    readonly outputContainer: string;
+    readonly outputEncoding: string;
+    readonly generationConfig?: Record<string, unknown>;
+}
+/** Exported for unit tests that exercise encode without a live socket. */
+export declare class CartesiaWireProtocol implements WireProtocol {
+    private readonly cfg;
+    private readonly charactersByKey;
+    constructor(cfg: CartesiaWireConfig);
+    attributionFor(contextId: string): {
+        key: AttributionKey;
+        contextId: string;
+    };
+    encodeText(key: AttributionKey, text: string): SocketData[];
+    encodeFinish(contextId: string, activeKeys: readonly AttributionKey[]): SocketData[];
+    encodeCancel(key: AttributionKey): SocketData[];
+    encodeClose(): SocketData[];
+    decode(data: SocketData): WireEvent[];
+}
+export declare class CartesiaTTSPlugin implements VoicePlugin {
+    private readonly socketFactory?;
+    constructor(socketFactory?: SocketFactory | undefined);
+    private session;
+    initialize(bus: PipelineBus, config: PluginConfig): Promise<void>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EAGjB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAIL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIpE,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrD;AAED,0EAA0E;AAC1E,qBAAa,oBAAqB,YAAW,YAAY;IAG3C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;gBAExC,GAAG,EAAE,kBAAkB;IAEpD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,cAAc,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAI7E,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE;IAoB3D,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,EAAE;IAoBpF,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU,EAAE;IAK/C,WAAW,IAAI,UAAU,EAAE;IAI3B,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE;CA4DtC;AAED,qBAAa,iBAAkB,YAAW,WAAW;IAGvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAAd,aAAa,CAAC,EAAE,aAAa,YAAA;IAE1D,OAAO,CAAC,OAAO,CAAoC;IAE7C,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/index.js

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Cartesia TTS Plugin
+//
+// The streaming lifecycle lives in @kuralle-syrinx/tts-core. This file is the Cartesia wire
+// protocol: per-context attribution (the provider echoes `context_id`), the speak/flush/cancel
+// JSON frames, and the inbound decode of base64 audio + word timestamps + the `done` flag.
+// Cartesia ships whole PCM16 frames, so it validates alignment in `decode` (erroring on an
+// odd-length payload) rather than relying on the engine's streaming carry.
+import { Route, assertAudioFormat, assertAudioPayload, optionalStringConfig, readProviderRetryConfig, requireStringConfig, } from "@kuralle-syrinx/core";
+import { attributionKey, defaultNodeSocketFactory, startStreamingTtsSession, } from "@kuralle-syrinx/tts-core";
+const KEEP_ALIVE_INTERVAL_MS = 10_000;
+/** Exported for unit tests that exercise encode without a live socket. */
+export class CartesiaWireProtocol {
+    cfg;
+    charactersByKey = new Map();
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    attributionFor(contextId) {
+        return { key: attributionKey(contextId), contextId };
+    }
+    encodeText(key, text) {
+        this.charactersByKey.set(key, (this.charactersByKey.get(key) ?? 0) + text.length);
+        const frame = {
+            model_id: this.cfg.modelId,
+            transcript: text,
+            voice: { mode: "id", id: this.cfg.voiceId },
+            output_format: {
+                container: this.cfg.outputContainer,
+                encoding: this.cfg.outputEncoding,
+                sample_rate: this.cfg.sampleRate,
+            },
+            language: this.cfg.language,
+            context_id: key || crypto.randomUUID(),
+            continue: true,
+            add_timestamps: this.cfg.addTimestamps,
+            ...this.cfg.generationConfig,
+        };
+        return [JSON.stringify(frame)];
+    }
+    encodeFinish(contextId, activeKeys) {
+        if (activeKeys.length === 0)
+            return [];
+        return [
+            JSON.stringify({
+                model_id: this.cfg.modelId,
+                transcript: "",
+                voice: { mode: "id", id: this.cfg.voiceId },
+                output_format: {
+                    container: this.cfg.outputContainer,
+                    encoding: this.cfg.outputEncoding,
+                    sample_rate: this.cfg.sampleRate,
+                },
+                language: this.cfg.language,
+                context_id: contextId,
+                continue: false,
+                flush: true,
+            }),
+        ];
+    }
+    encodeCancel(key) {
+        this.charactersByKey.delete(key);
+        return [JSON.stringify({ context_id: key, cancel: true })];
+    }
+    encodeClose() {
+        return [];
+    }
+    decode(data) {
+        if (typeof data !== "string")
+            return []; // Cartesia frames are JSON text
+        const msg = JSON.parse(data); // parse failure → engine fails all contexts
+        const contextId = typeof msg["context_id"] === "string" ? msg["context_id"] : "";
+        const key = attributionKey(contextId);
+        if (msg["type"] === "error" || isErrorStatusCode(msg["status_code"])) {
+            // A `done:true` error frame both reports the error AND ends the context.
+            return [{ type: "error", key: contextId ? key : null, error: cartesiaProviderError(msg), endsContext: msg["done"] === true }];
+        }
+        const events = [];
+        if (msg["type"] === "timestamps") {
+            const words = parseWordTimestamps(msg["word_timestamps"]);
+            if (contextId && words.length > 0) {
+                events.push({
+                    type: "sideband",
+                    key,
+                    route: Route.Main,
+                    build: (ctxId, timestampMs) => ({ kind: "tts.word_timestamps", contextId: ctxId, timestampMs, words }),
+                });
+            }
+        }
+        // Audio arrives as non-empty base64 `data`; control frames such as `flush_done` carry an
+        // empty `data` and must not be decoded as audio.
+        if (typeof msg["data"] === "string" && msg["data"].length > 0) {
+            try {
+                const bytes = new Uint8Array(decodeStrictBase64(msg["data"], "Cartesia TTS provider audio data"));
+                assertAudioPayload(this.cfg.audioFormat, bytes);
+                events.push({ type: "audio", key, pcm: bytes });
+            }
+            catch (err) {
+                events.push({ type: "error", key, error: err instanceof Error ? err : new Error(String(err)) });
+            }
+        }
+        if (msg["done"] === true) {
+            const characters = this.charactersByKey.get(key) ?? 0;
+            this.charactersByKey.delete(key);
+            // Sideband before context_end so the engine still has the key→context mapping.
+            if (characters > 0) {
+                const modelId = this.cfg.modelId;
+                events.push({
+                    type: "sideband",
+                    key,
+                    route: Route.Background,
+                    build: (ctxId, timestampMs) => ({
+                        kind: "usage.recorded",
+                        contextId: ctxId,
+                        timestampMs,
+                        stage: "tts",
+                        provider: "cartesia",
+                        model: modelId,
+                        characters,
+                    }),
+                });
+            }
+            events.push({ type: "context_end", key });
+        }
+        return events;
+    }
+}
+export class CartesiaTTSPlugin {
+    socketFactory;
+    // socketFactory is injectable so the same plugin runs on Node (default) or
+    // Cloudflare Workers (pass createWorkersSocket).
+    constructor(socketFactory) {
+        this.socketFactory = socketFactory;
+    }
+    session = null;
+    async initialize(bus, config) {
+        const apiKey = requireStringConfig(config, "api_key");
+        const voiceId = optionalStringConfig(config, "voice_id") ?? "c2ac25f9-ecc4-4f56-9095-651354df60c0";
+        const modelId = optionalStringConfig(config, "model_id") ?? "sonic-3";
+        const endpointUrl = optionalStringConfig(config, "endpoint_url") ?? "wss://api.cartesia.ai/tts/websocket";
+        const apiVersion = optionalStringConfig(config, "cartesia_version") ?? "2024-06-10";
+        const sampleRate = config["sample_rate"] ?? 16000;
+        const language = optionalStringConfig(config, "language") ?? "en";
+        const addTimestamps = config["add_timestamps"] === undefined ? true : config["add_timestamps"] === true;
+        const outputContainer = optionalStringConfig(config, "output_container") ?? "raw";
+        const outputEncoding = optionalStringConfig(config, "output_encoding") ?? "pcm_s16le";
+        // Optional provider-specific passthrough merged into generation frames (speed, volume, etc.).
+        const generationConfig = readPlainObject(config["generation_config"]);
+        const audioFormat = { encoding: "pcm_s16le", sampleRateHz: sampleRate, channels: 1 };
+        assertAudioFormat(audioFormat);
+        this.session = await startStreamingTtsSession(bus, {
+            protocol: new CartesiaWireProtocol({
+                modelId,
+                voiceId,
+                sampleRate,
+                language,
+                audioFormat,
+                addTimestamps,
+                outputContainer,
+                outputEncoding,
+                generationConfig,
+            }),
+            provider: { name: "cartesia", model: modelId, region: "global" },
+            format: audioFormat,
+            sampleRateHz: sampleRate,
+            url: () => {
+                const params = new URLSearchParams({ cartesia_version: apiVersion });
+                const separator = endpointUrl.includes("?") ? "&" : "?";
+                return `${endpointUrl}${separator}${params.toString()}`;
+            },
+            headers: { "X-API-Key": apiKey },
+            retry: readProviderRetryConfig(config),
+            finishTimeoutMs: readNonNegativeInteger(config["finish_timeout_ms"], 2000),
+            metricPrefix: "tts.cartesia",
+            socketFactory: this.socketFactory ?? (await defaultNodeSocketFactory()),
+            replayBufferSize: config["replay_buffer_size"] ?? 32,
+            keepAliveIntervalMs: KEEP_ALIVE_INTERVAL_MS,
+        });
+    }
+    async close() {
+        await this.session?.dispose();
+        this.session = null;
+    }
+}
+function isErrorStatusCode(value) {
+    return typeof value === "number" && value >= 400;
+}
+function cartesiaProviderError(msg) {
+    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, name) {
+    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 parseWordTimestamps(value) {
+    if (value === null || typeof value !== "object")
+        return [];
+    const raw = value;
+    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 = [];
+    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) });
+    }
+    return words;
+}
+function readNonNegativeInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    const integer = Math.floor(value);
+    return integer >= 0 ? integer : fallback;
+}
+function readPlainObject(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/cartesia",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "private": false,
   "description": "Cartesia streaming TTS adapter for Syrinx",
   "keywords": [
@@ -22,21 +22,28 @@
     "url": "https://github.com/kuralle/syrinx/issues"
   },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "@kuralle-syrinx/core": "4.4.1",
-    "@kuralle-syrinx/tts-core": "4.4.1",
-    "@kuralle-syrinx/ws": "4.4.1"
+    "@kuralle-syrinx/core": "4.5.0",
+    "@kuralle-syrinx/tts-core": "4.5.0",
+    "@kuralle-syrinx/ws": "4.5.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "@types/ws": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6",
     "ws": "^8.21.0"
   },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,914 @@
+// 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,
+  type UsageRecordedPacket,
+} from "@kuralle-syrinx/core";
+import { attributionKey } from "@kuralle-syrinx/tts-core";
+
+import { CartesiaTTSPlugin, CartesiaWireProtocol } 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("emits usage.recorded with stage tts and characters equal to synthesized text length", async () => {
+    const text = "Hello there.";
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.transcript === text) {
+          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-usage" && msg.continue === false) {
+          socket.send(JSON.stringify({
+            type: "done",
+            context_id: "turn-usage",
+            done: true,
+            status_code: 206,
+          }));
+        }
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new CartesiaTTSPlugin();
+    const ends: TextToSpeechEndPacket[] = [];
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-cartesia-key",
+      endpoint_url: endpointUrl,
+      voice_id: "voice-test",
+      model_id: "sonic-3",
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-usage",
+      timestampMs: Date.now(),
+      text,
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-usage",
+      timestampMs: Date.now(),
+      text,
+    });
+    await waitForCondition(() => ends.length >= 1 && usage.length >= 1);
+
+    expect(usage).toEqual([
+      expect.objectContaining({
+        kind: "usage.recorded",
+        contextId: "turn-usage",
+        stage: "tts",
+        provider: "cartesia",
+        model: "sonic-3",
+        characters: text.length,
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  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("honors add_timestamps, output encoding/container overrides, and generation_config passthrough on speak frames", async () => {
+    const protocol = new CartesiaWireProtocol({
+      modelId: "sonic-3",
+      voiceId: "voice-x",
+      sampleRate: 16000,
+      language: "en",
+      audioFormat: { encoding: "pcm_s16le", sampleRateHz: 16000, channels: 1 },
+      addTimestamps: false,
+      outputContainer: "raw",
+      outputEncoding: "pcm_f32le",
+      generationConfig: { speed: 1.2, volume: 0.9 },
+    });
+    const key = attributionKey("turn-cfg");
+    const frames = protocol.encodeText(key, "Hello.").map((f) => JSON.parse(String(f)));
+    expect(frames).toEqual([
+      expect.objectContaining({
+        model_id: "sonic-3",
+        transcript: "Hello.",
+        context_id: key,
+        continue: true,
+        add_timestamps: false,
+        speed: 1.2,
+        volume: 0.9,
+        output_format: {
+          container: "raw",
+          encoding: "pcm_f32le",
+          sample_rate: 16000,
+        },
+      }),
+    ]);
+  });
+
+  it("defaults add_timestamps true and pcm_s16le/raw on speak frames when unset", async () => {
+    const received: Array<Record<string, unknown>> = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(data.toString()) as Record<string, unknown>;
+        received.push(msg);
+        if (msg["transcript"] === "Hi.") {
+          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["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 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",
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, { kind: "tts.text", contextId: "turn-default-cfg", timestampMs: Date.now(), text: "Hi." });
+    bus.push(Route.Main, { kind: "tts.done", contextId: "turn-default-cfg", timestampMs: Date.now() });
+    await waitForCondition(() => ends.length >= 1);
+
+    expect(received[0]).toEqual(
+      expect.objectContaining({
+        add_timestamps: true,
+        output_format: { container: "raw", encoding: "pcm_s16le", sample_rate: 16000 },
+      }),
+    );
+
+    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;
+  });
+
+});