@kuralle-syrinx/cartesia 2.1.0 → 3.0.0

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@kuralle-syrinx/cartesia",
-  "version": "2.1.0",
+  "version": "3.0.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"
+    "@kuralle-syrinx/core": "3.0.0",
+    "@kuralle-syrinx/tts-core": "3.0.0",
+    "@kuralle-syrinx/ws": "3.0.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.0",

package/src/index.test.ts

@@ -695,67 +695,6 @@ describe("CartesiaTTSPlugin", () => {
     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) => {
@@ -814,71 +753,4 @@ describe("CartesiaTTSPlugin", () => {
     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

@@ -1,367 +1,178 @@
 // 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 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,
+  type AudioFormat,
+  type PipelineBus,
+  type PluginConfig,
+  type TextToSpeechWordTimestampsPacket,
+  type TtsWordTimestamp,
+  type VoicePlugin,
 } from "@kuralle-syrinx/core";
-import { WebSocketConnection, type SocketData, type SocketFactory } from "@kuralle-syrinx/ws";
+import {
+  attributionKey,
+  defaultNodeSocketFactory,
+  startStreamingTtsSession,
+  type AttributionKey,
+  type StreamingTtsSession,
+  type WireEvent,
+  type WireProtocol,
+} from "@kuralle-syrinx/tts-core";
+import type { SocketData, 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);
+interface CartesiaWireConfig {
+  readonly modelId: string;
+  readonly voiceId: string;
+  readonly sampleRate: number;
+  readonly language: string;
+  readonly audioFormat: 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();
+class CartesiaWireProtocol implements WireProtocol {
+  constructor(private readonly cfg: CartesiaWireConfig) {}
 
-    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.
-        });
-      }),
-    );
+  attributionFor(contextId: string): { key: AttributionKey; contextId: string } {
+    return { key: attributionKey(contextId), contextId };
   }
 
-  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(
+  encodeText(key: AttributionKey, text: string): SocketData[] {
+    return [
       JSON.stringify({
-        model_id: this.modelId,
+        model_id: this.cfg.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(),
+        voice: { mode: "id", id: this.cfg.voiceId },
+        output_format: { container: "raw", encoding: "pcm_s16le", sample_rate: this.cfg.sampleRate },
+        language: this.cfg.language,
+        context_id: key || 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(
+  encodeFinish(contextId: string, activeKeys: readonly AttributionKey[]): SocketData[] {
+    if (activeKeys.length === 0) return [];
+    return [
       JSON.stringify({
-        model_id: this.modelId,
+        model_id: this.cfg.modelId,
         transcript: "",
-        voice: { mode: "id", id: this.voiceId },
-        output_format: {
-          container: "raw",
-          encoding: "pcm_s16le",
-          sample_rate: this.sampleRate,
-        },
-        language: this.language,
+        voice: { mode: "id", id: this.cfg.voiceId },
+        output_format: { container: "raw", encoding: "pcm_s16le", sample_rate: this.cfg.sampleRate },
+        language: this.cfg.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;
+  encodeCancel(key: AttributionKey): SocketData[] {
+    return [JSON.stringify({ context_id: key, cancel: true })];
   }
 
-  /** 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;
-    }
+  encodeClose(): SocketData[] {
+    return [];
   }
 
-  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;
-    }
-
+  decode(data: SocketData): WireEvent[] {
+    if (typeof data !== "string") return []; // Cartesia frames are JSON text
+    const msg = JSON.parse(data) as Record<string, unknown>; // parse failure → engine fails all contexts
     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;
-    }
+    const key = attributionKey(contextId);
 
     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;
+      // 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: WireEvent[] = [];
     if (msg["type"] === "timestamps") {
-      this.emitWordTimestamps(contextId, msg["word_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 } satisfies TextToSpeechWordTimestampsPacket),
+        });
+      }
     }
-
-    // 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.
+    // 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 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);
+        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) {
-        this.activeContexts.delete(contextId);
-        this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+        events.push({ type: "error", key, error: err instanceof Error ? err : new Error(String(err)) });
       }
     }
-    if (msg["done"] === true) {
-      this.activeContexts.delete(contextId);
-      this.clearFinishTimeout(contextId);
-      this.emitEnd(contextId);
-    }
+    if (msg["done"] === true) events.push({ type: "context_end", key });
+    return events;
   }
+}
 
-  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);
-  }
+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 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 session: StreamingTtsSession | null = null;
 
-  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,
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    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"] as number) ?? 16000;
+    const language = optionalStringConfig(config, "language") ?? "en";
+    const audioFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: sampleRate, channels: 1 };
+    assertAudioFormat(audioFormat);
+
+    this.session = await startStreamingTtsSession(bus, {
+      protocol: new CartesiaWireProtocol({ modelId, voiceId, sampleRate, language, audioFormat }),
+      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"] as number) ?? 32,
+      keepAliveIntervalMs: KEEP_ALIVE_INTERVAL_MS,
     });
   }
 
-  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 close(): Promise<void> {
+    await this.session?.dispose();
+    this.session = null;
   }
 }
 
-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;
 }
@@ -388,6 +199,24 @@ function decodeStrictBase64(value: string, name: string): Buffer {
   return decoded;
 }
 
+function parseWordTimestamps(value: unknown): TtsWordTimestamp[] {
+  if (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) });
+  }
+  return words;
+}
+
 function readNonNegativeInteger(value: unknown, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
   const integer = Math.floor(value);