@kuralle-syrinx/tts-core 3.0.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,21 @@
+{
+  "name": "@kuralle-syrinx/tts-core",
+  "version": "3.0.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@kuralle-syrinx/core": "3.0.0",
+    "@kuralle-syrinx/ws": "3.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/engine.test.ts

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { Route, type AudioFormat } from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+import { createTtsEngine } from "./engine.js";
+import { attributionKey, type AttributionKey, type TimerHandle, type TimerPort, type Transport, type WireEvent, type WireProtocol } from "./types.js";
+
+const FORMAT: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 24000, channels: 1 };
+const SESSION = attributionKey("session");
+
+class FakeTimer implements TimerPort {
+  private readonly timers = new Map<number, () => void>();
+  private next = 0;
+  set(_ms: number, fn: () => void): TimerHandle {
+    const handle = this.next++;
+    this.timers.set(handle, fn);
+    return handle;
+  }
+  clear(handle: TimerHandle): void {
+    this.timers.delete(handle as number);
+  }
+  fire(): void {
+    for (const [handle, fn] of [...this.timers]) {
+      this.timers.delete(handle);
+      fn();
+    }
+  }
+}
+
+/** grok-shape: one constant key per session. */
+class SingleProtocol implements WireProtocol {
+  attributionFor(contextId: string) {
+    return { key: SESSION, contextId };
+  }
+  encodeText(_key: AttributionKey, text: string): SocketData[] {
+    return [JSON.stringify({ op: "text", text })];
+  }
+  encodeFinish(): SocketData[] {
+    return [JSON.stringify({ op: "finish" })];
+  }
+  encodeCancel(): SocketData[] {
+    return [JSON.stringify({ op: "clear" })];
+  }
+  encodeClose(): SocketData[] {
+    return [];
+  }
+  decode(data: SocketData): WireEvent[] {
+    return decodeTestFrame(data, SESSION);
+  }
+}
+
+/** epsilon-shape: per-request key `${ctx}:${seq}`, refcount-driven end (no finish frame). */
+class MultiplexProtocol implements WireProtocol {
+  private readonly seq = new Map<string, number>();
+  attributionFor(contextId: string) {
+    const n = this.seq.get(contextId) ?? 0;
+    this.seq.set(contextId, n + 1);
+    return { key: attributionKey(`${contextId}:${n}`), contextId };
+  }
+  encodeText(key: AttributionKey, text: string): SocketData[] {
+    return [JSON.stringify({ op: "speak", key, text })];
+  }
+  encodeFinish(): SocketData[] {
+    return [];
+  }
+  encodeCancel(key: AttributionKey): SocketData[] {
+    return [JSON.stringify({ op: "cancel", key })];
+  }
+  encodeClose(): SocketData[] {
+    return [JSON.stringify({ op: "eos" })];
+  }
+  decode(data: SocketData): WireEvent[] {
+    return decodeTestFrame(data, null);
+  }
+}
+
+function decodeTestFrame(data: SocketData, fixedKey: AttributionKey | null): WireEvent[] {
+  const m = JSON.parse(data as string) as { t?: string; key?: string; pcm?: number[]; msg?: string };
+  const key = (m.key !== undefined ? attributionKey(m.key) : fixedKey) ?? SESSION;
+  switch (m.t) {
+    case "audio":
+      return [{ type: "audio", key, pcm: Uint8Array.from(m.pcm ?? []) }];
+    case "done":
+      return [{ type: "utterance_end", key }];
+    case "end":
+      return [{ type: "context_end", key }];
+    case "err":
+      return [{ type: "error", key: m.key !== undefined ? key : null, error: new Error(m.msg ?? "err") }];
+    case "boom":
+      throw new Error("decode failure");
+    default:
+      return [];
+  }
+}
+
+function harness(protocol: WireProtocol, finishTimeoutMs = 2000, opts: { sendThrows?: boolean } = {}) {
+  const sent: SocketData[] = [];
+  const pushed: Array<{ route: Route; packet: Record<string, unknown> }> = [];
+  const timer = new FakeTimer();
+  const transport: Transport = {
+    ensureReady: async () => {},
+    send: (frame) => {
+      if (opts.sendThrows) throw new Error("WebSocket is not open");
+      sent.push(frame);
+    },
+    close: async () => {},
+  };
+  const engine = createTtsEngine({
+    protocol,
+    transport,
+    sink: { push: (route, packet) => pushed.push({ route, packet: packet as Record<string, unknown> }) },
+    format: FORMAT,
+    sampleRateHz: 24000,
+    provider: { name: "fake", model: "m" },
+    finishTimeoutMs,
+    metricPrefix: "tts.fake",
+    timer,
+    now: () => 1000,
+  });
+  const byKind = (kind: string) => pushed.filter((p) => p.packet["kind"] === kind).map((p) => p.packet);
+  return { engine, sent, pushed, timer, audio: () => byKind("tts.audio"), ends: () => byKind("tts.end"), errors: () => byKind("tts.error"), metrics: () => byKind("metric.conversation") };
+}
+
+describe("TtsEngine — single-context (grok-shape)", () => {
+  it("carries an odd trailing byte across frames, then emits aligned PCM and ends on utterance_end", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("hello", "ctx1");
+    expect(h.sent).toEqual([JSON.stringify({ op: "text", text: "hello" })]);
+
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [1] }), false);
+    expect(h.audio()).toHaveLength(0); // 1 byte → odd, fully carried, nothing aligned yet
+
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [2, 3] }), false);
+    expect(h.audio()).toHaveLength(1); // [1] + [2,3] = [1,2,3] → emit [1,2], carry [3]
+    expect([...(h.audio()[0]!["audio"] as Uint8Array)]).toEqual([1, 2]);
+
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [4] }), false);
+    expect(h.audio()).toHaveLength(2); // [3] + [4] = [3,4] → emit [3,4]
+    expect([...(h.audio()[1]!["audio"] as Uint8Array)]).toEqual([3, 4]);
+
+    await h.engine.onDone("ctx1");
+    expect(h.sent).toContainEqual(JSON.stringify({ op: "finish" }));
+    expect(h.ends()).toHaveLength(0); // still streaming
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1);
+  });
+
+  it("emits tts.end immediately on a provider context_end, with no prior tts.done", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxCE");
+    h.engine.onMessage(JSON.stringify({ t: "end", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1); // single-stream providers end on the provider's own done signal
+  });
+
+  it("drops audio after interrupt and sends the cancel frame", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxC");
+    await h.engine.onInterrupt();
+    expect(h.sent).toContainEqual(JSON.stringify({ op: "clear" }));
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "session", pcm: [1, 2] }), false);
+    expect(h.audio()).toHaveLength(0);
+  });
+});
+
+describe("TtsEngine — multiplex (epsilon-shape)", () => {
+  it("emits tts.end only after every per-request key for a context completes", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxM"); // ctxM:0
+    await h.engine.onText("b", "ctxM"); // ctxM:1
+    expect(h.sent).toHaveLength(2);
+
+    await h.engine.onDone("ctxM"); // no finish frame; both requests still active
+    expect(h.ends()).toHaveLength(0);
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "ctxM:0" }), false);
+    expect(h.ends()).toHaveLength(0); // one still streaming
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "ctxM:1" }), false);
+    expect(h.ends()).toHaveLength(1); // refcount hit zero
+  });
+
+  it("attributes audio per request key independently", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxM"); // ctxM:0
+    await h.engine.onText("b", "ctxM"); // ctxM:1
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "ctxM:0", pcm: [1, 2] }), false);
+    h.engine.onMessage(JSON.stringify({ t: "audio", key: "ctxM:1", pcm: [3, 4] }), false);
+    const audio = h.audio();
+    expect(audio).toHaveLength(2);
+    expect(audio.every((p) => p["contextId"] === "ctxM")).toBe(true);
+  });
+});
+
+describe("TtsEngine — fallbacks and failures", () => {
+  it("fires the finish-timeout: emits a metric and tts.end when the provider never reports done", async () => {
+    const h = harness(new SingleProtocol(), 2000);
+    await h.engine.onText("a", "ctxD");
+    await h.engine.onDone("ctxD");
+    expect(h.ends()).toHaveLength(0);
+    h.timer.fire();
+    expect(h.ends()).toHaveLength(1);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(true);
+  });
+
+  it("maps a provider error frame to a categorized tts.error", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxE");
+    h.engine.onMessage(JSON.stringify({ t: "err", key: "session", msg: "provider boom" }), false);
+    const errors = h.errors();
+    expect(errors).toHaveLength(1);
+    expect((errors[0]!["cause"] as Error).message).toBe("provider boom");
+    expect(typeof errors[0]!["isRecoverable"]).toBe("boolean");
+  });
+
+  it("treats a decode throw as fatal and fails all active contexts", async () => {
+    const h = harness(new SingleProtocol());
+    await h.engine.onText("a", "ctxF");
+    h.engine.onMessage(JSON.stringify({ t: "boom" }), false);
+    expect(h.errors().some((e) => e["contextId"] === "ctxF")).toBe(true);
+  });
+
+  it("emits tts.error and does not leave the context active when a send fails", async () => {
+    const h = harness(new SingleProtocol(), 2000, { sendThrows: true });
+    await h.engine.onText("a", "ctxSend");
+    expect(h.errors().some((e) => e["contextId"] === "ctxSend")).toBe(true); // send failure → typed error
+    await h.engine.onDone("ctxSend");
+    expect(h.ends().some((e) => e["contextId"] === "ctxSend")).toBe(true); // context drained, turn ends (no hang)
+  });
+
+  it("fails active contexts on connection loss", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxG");
+    h.engine.onConnectionLost(new Error("dropped"));
+    expect(h.errors().some((e) => e["contextId"] === "ctxG")).toBe(true);
+  });
+
+  it("does not error a cancelled context when the connection then drops (barge-in race)", async () => {
+    const h = harness(new MultiplexProtocol());
+    await h.engine.onText("a", "ctxCancelled");
+    await h.engine.onInterrupt(); // cancel sent; key still tracked pending the provider ack
+    h.engine.onConnectionLost(new Error("dropped"));
+    expect(h.errors().some((e) => e["contextId"] === "ctxCancelled")).toBe(false);
+  });
+});

package/src/engine.ts

@@ -0,0 +1,410 @@
+// SPDX-License-Identifier: MIT
+//
+// The streaming-TTS deep module. Owns the entire lifecycle that the cartesia/grok/epsilon
+// plugins each used to duplicate: per-key PCM16 carry, active/cancelled/pending-end
+// bookkeeping keyed on the provider's opaque attribution key, finish-timeout, error
+// categorization, packet emission, and connection-loss failure. Socket-free: depends only
+// on the injected ports (`WireProtocol`, `Transport`, `PacketSink`, `TimerPort`), so the
+// tricky behavior (odd-byte carry, multiplex refcount, cancel races, finish-timeout) is
+// unit-testable without a real WebSocket.
+
+import {
+  Route,
+  assertAudioPayload,
+  categorizeTtsError,
+  isRecoverable,
+  type AudioFormat,
+  type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
+  type TtsErrorPacket,
+} from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+
+import type { AttributionKey, PacketSink, TimerHandle, TimerPort, Transport, WireEvent, WireProtocol } from "./types.js";
+
+const EMPTY = new Uint8Array(0);
+
+const defaultTimer: TimerPort = {
+  set: (ms, fn) => setTimeout(fn, ms),
+  clear: (handle) => {
+    clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+export interface TtsEngineDeps {
+  readonly protocol: WireProtocol;
+  readonly transport: Transport;
+  readonly sink: PacketSink;
+  readonly format: AudioFormat;
+  readonly sampleRateHz: number;
+  readonly provider: { readonly name: string; readonly model: string; readonly region?: string };
+  /** 0 disables the finish-timeout fallback. */
+  readonly finishTimeoutMs: number;
+  /** Namespace for engine-emitted metrics, e.g. "tts.epsilon". */
+  readonly metricPrefix: string;
+  readonly timer?: TimerPort;
+  readonly now?: () => number;
+}
+
+export interface TtsEngine {
+  onText(text: string, contextId: string): Promise<void>;
+  onDone(contextId: string): Promise<void>;
+  onInterrupt(): Promise<void>;
+  onMessage(data: SocketData, isBinary: boolean): void;
+  onConnectionLost(error: Error): void;
+  close(): Promise<void>;
+}
+
+export function createTtsEngine(deps: TtsEngineDeps): TtsEngine {
+  return new TtsEngineImpl(deps);
+}
+
+class TtsEngineImpl implements TtsEngine {
+  private readonly keyToContext = new Map<AttributionKey, string>();
+  private readonly contextKeys = new Map<string, Set<AttributionKey>>();
+  private readonly cancelledContexts = new Set<string>();
+  private readonly carry = new Map<AttributionKey, Uint8Array>();
+  private readonly pendingEnd = new Set<string>();
+  private readonly finishTimers = new Map<string, TimerHandle>();
+  private readonly timer: TimerPort;
+  private readonly now: () => number;
+
+  constructor(private readonly deps: TtsEngineDeps) {
+    this.timer = deps.timer ?? defaultTimer;
+    this.now = deps.now ?? (() => Date.now());
+  }
+
+  async onText(text: string, contextId: string): Promise<void> {
+    if (!text.trim()) return;
+    if (this.cancelledContexts.has(contextId)) return;
+    const { key } = this.deps.protocol.attributionFor(contextId);
+    this.track(key, contextId);
+    const frames = this.deps.protocol.encodeText(key, text);
+    if (frames.length === 0) {
+      this.untrack(key);
+      return;
+    }
+    for (const frame of frames) {
+      if (!(await this.trySend(frame, contextId))) {
+        this.untrack(key);
+        return;
+      }
+    }
+  }
+
+  async onDone(contextId: string): Promise<void> {
+    if (this.cancelledContexts.has(contextId)) return;
+    const activeKeys = [...(this.contextKeys.get(contextId) ?? [])];
+    for (const frame of this.deps.protocol.encodeFinish(contextId, activeKeys)) {
+      await this.trySend(frame, contextId);
+    }
+    this.pendingEnd.add(contextId);
+    if (this.deps.finishTimeoutMs > 0 && this.hasActiveKeys(contextId)) {
+      this.scheduleFinishTimeout(contextId);
+    }
+    this.tryEmitEnd(contextId);
+  }
+
+  async onInterrupt(): Promise<void> {
+    const contexts = new Set<string>([...this.contextKeys.keys(), ...this.pendingEnd]);
+    for (const contextId of contexts) await this.cancelContext(contextId);
+  }
+
+  onMessage(data: SocketData, isBinary: boolean): void {
+    let events: readonly WireEvent[];
+    try {
+      events = this.deps.protocol.decode(data, isBinary);
+    } catch (err) {
+      this.failAll(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    for (const event of events) this.dispatch(event);
+  }
+
+  private dispatch(event: WireEvent): void {
+    switch (event.type) {
+      case "audio":
+        this.handleAudio(event.key, event.pcm);
+        return;
+      case "utterance_end":
+        this.handleUtteranceEnd(event.key);
+        return;
+      case "context_end":
+        this.handleContextEnd(event.key);
+        return;
+      case "cancelled":
+        this.handleCancelled(event.key);
+        return;
+      case "error":
+        this.handleError(event.key, event.error, event.endsContext ?? false);
+        return;
+      case "sideband": {
+        const contextId = this.keyToContext.get(event.key);
+        if (contextId === undefined) return;
+        this.deps.sink.push(event.route, event.build(contextId, this.now()));
+        return;
+      }
+      case "ignore":
+        return;
+    }
+  }
+
+  onConnectionLost(error: Error): void {
+    this.failAll(error);
+  }
+
+  async close(): Promise<void> {
+    this.pendingEnd.clear();
+    this.cancelledContexts.clear();
+    this.keyToContext.clear();
+    this.contextKeys.clear();
+    this.carry.clear();
+    for (const handle of this.finishTimers.values()) this.timer.clear(handle);
+    this.finishTimers.clear();
+    try {
+      for (const frame of this.deps.protocol.encodeClose()) {
+        await this.deps.transport.ensureReady();
+        this.deps.transport.send(frame);
+      }
+    } catch {
+      // Best-effort session shutdown.
+    }
+    await this.deps.transport.close();
+  }
+
+  // ── inbound handling ──────────────────────────────────────────────────────
+
+  private handleAudio(key: AttributionKey, pcm: Uint8Array): void {
+    const contextId = this.keyToContext.get(key);
+    if (contextId === undefined || this.cancelledContexts.has(contextId)) return;
+    if (pcm.byteLength === 0) return;
+
+    const prev = this.carry.get(key) ?? EMPTY;
+    const buf = prev.byteLength === 0 ? pcm : concatBytes(prev, pcm);
+    const evenLen = buf.byteLength - (buf.byteLength % 2);
+    if (evenLen > 0) {
+      const audio = buf.subarray(0, evenLen);
+      try {
+        assertAudioPayload(this.deps.format, audio);
+      } catch (err) {
+        this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+      const packet: TextToSpeechAudioPacket = {
+        kind: "tts.audio",
+        contextId,
+        timestampMs: this.now(),
+        audio,
+        sampleRateHz: this.deps.sampleRateHz,
+        provider: {
+          name: this.deps.provider.name,
+          model: this.deps.provider.model,
+          region: this.deps.provider.region ?? "global",
+          cancelled: false,
+        },
+      };
+      this.deps.sink.push(Route.Main, packet);
+    }
+    this.carry.set(key, evenLen < buf.byteLength ? buf.subarray(evenLen) : EMPTY);
+  }
+
+  // One attribution unit finished. The context ends only when all its units are done AND
+  // `tts.done` has been seen (the refcount/multiplex model, e.g. epsilon).
+  private handleUtteranceEnd(key: AttributionKey): void {
+    const contextId = this.keyToContext.get(key);
+    this.untrack(key);
+    if (contextId === undefined) return;
+    if (this.cancelledContexts.has(contextId)) {
+      this.clearCancelledIfDrained(contextId);
+      return;
+    }
+    this.tryEmitEnd(contextId);
+  }
+
+  // The provider declared the whole context complete — end now, regardless of `tts.done`
+  // (the single-stream model: cartesia `done:true`, grok `audio.done`).
+  private handleContextEnd(key: AttributionKey): void {
+    const contextId = this.keyToContext.get(key);
+    this.untrack(key);
+    if (contextId === undefined) return;
+    if (this.cancelledContexts.has(contextId)) {
+      this.clearCancelledIfDrained(contextId);
+      return;
+    }
+    this.endContextNow(contextId);
+  }
+
+  private handleCancelled(key: AttributionKey): void {
+    const contextId = this.keyToContext.get(key);
+    this.untrack(key);
+    if (contextId !== undefined && this.cancelledContexts.has(contextId)) this.clearCancelledIfDrained(contextId);
+  }
+
+  private handleError(key: AttributionKey | null, error: Error, endsContext: boolean): void {
+    const contextId = key !== null ? this.keyToContext.get(key) : undefined;
+    if (key !== null) this.untrack(key);
+    if (contextId !== undefined && this.cancelledContexts.has(contextId)) {
+      this.clearCancelledIfDrained(contextId);
+      return;
+    }
+    this.emitError(contextId ?? "", error);
+    if (contextId === undefined) return;
+    // A terminal error (provider coupled it with `done`) ends the context now, using the
+    // contextId captured above before untrack; otherwise end only if the refcount allows.
+    if (endsContext) this.endContextNow(contextId);
+    else this.tryEmitEnd(contextId);
+  }
+
+  /** Once a cancelled context fully drains, drop the cancelled flag so the id can be reused. */
+  private clearCancelledIfDrained(contextId: string): void {
+    if (!this.hasActiveKeys(contextId)) this.cancelledContexts.delete(contextId);
+  }
+
+  /** Emit `tts.end` for a context immediately and clear its pending/timeout state. */
+  private endContextNow(contextId: string): void {
+    this.pendingEnd.delete(contextId);
+    this.clearFinishTimeout(contextId);
+    this.emitEnd(contextId);
+  }
+
+  // ── bookkeeping ───────────────────────────────────────────────────────────
+
+  private track(key: AttributionKey, contextId: string): void {
+    this.keyToContext.set(key, contextId);
+    let keys = this.contextKeys.get(contextId);
+    if (!keys) {
+      keys = new Set();
+      this.contextKeys.set(contextId, keys);
+    }
+    keys.add(key);
+  }
+
+  private untrack(key: AttributionKey): void {
+    const contextId = this.keyToContext.get(key);
+    this.keyToContext.delete(key);
+    this.carry.delete(key);
+    if (contextId === undefined) return;
+    const keys = this.contextKeys.get(contextId);
+    if (!keys) return;
+    keys.delete(key);
+    if (keys.size === 0) this.contextKeys.delete(contextId);
+  }
+
+  private hasActiveKeys(contextId: string): boolean {
+    return (this.contextKeys.get(contextId)?.size ?? 0) > 0;
+  }
+
+  private async cancelContext(contextId: string): Promise<void> {
+    this.cancelledContexts.add(contextId);
+    this.pendingEnd.delete(contextId);
+    this.clearFinishTimeout(contextId);
+    for (const key of [...(this.contextKeys.get(contextId) ?? [])]) {
+      for (const frame of this.deps.protocol.encodeCancel(key, contextId)) {
+        await this.trySend(frame, contextId);
+      }
+    }
+  }
+
+  private tryEmitEnd(contextId: string): void {
+    if (!this.pendingEnd.has(contextId)) return;
+    if (this.hasActiveKeys(contextId)) return;
+    this.pendingEnd.delete(contextId);
+    this.clearFinishTimeout(contextId);
+    this.cancelledContexts.delete(contextId);
+    this.emitEnd(contextId);
+  }
+
+  private failAll(error: Error): void {
+    const contexts = new Set<string>([...this.contextKeys.keys(), ...this.pendingEnd]);
+    this.pendingEnd.clear();
+    this.contextKeys.clear();
+    this.keyToContext.clear();
+    this.carry.clear();
+    let emitted = 0;
+    for (const contextId of contexts) {
+      this.clearFinishTimeout(contextId);
+      // Don't surface an error for a context the caller deliberately cancelled (e.g. a
+      // barge-in) when the socket drops before the provider acks the cancel.
+      if (this.cancelledContexts.has(contextId)) continue;
+      this.emitError(contextId, error);
+      emitted += 1;
+    }
+    this.cancelledContexts.clear();
+    if (emitted === 0 && contexts.size === 0) this.emitError("", error);
+  }
+
+  // ── timers ────────────────────────────────────────────────────────────────
+
+  private scheduleFinishTimeout(contextId: string): void {
+    this.clearFinishTimeout(contextId);
+    const handle = this.timer.set(this.deps.finishTimeoutMs, () => {
+      this.finishTimers.delete(contextId);
+      if (!this.pendingEnd.has(contextId) && !this.hasActiveKeys(contextId)) return;
+      this.emitMetric(contextId, `${this.deps.metricPrefix}.finish_timeout`, String(this.deps.finishTimeoutMs));
+      this.pendingEnd.delete(contextId);
+      for (const key of [...(this.contextKeys.get(contextId) ?? [])]) this.untrack(key);
+      this.cancelledContexts.delete(contextId);
+      this.emitEnd(contextId);
+    });
+    this.finishTimers.set(contextId, handle);
+  }
+
+  private clearFinishTimeout(contextId: string): void {
+    const handle = this.finishTimers.get(contextId);
+    if (handle === undefined) return;
+    this.timer.clear(handle);
+    this.finishTimers.delete(contextId);
+  }
+
+  // ── emission ──────────────────────────────────────────────────────────────
+
+  private async trySend(frame: SocketData, contextId: string): Promise<boolean> {
+    try {
+      await this.deps.transport.ensureReady();
+      this.deps.transport.send(frame);
+      return true;
+    } catch (err) {
+      this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
+      return false;
+    }
+  }
+
+  private emitEnd(contextId: string): void {
+    this.deps.sink.push(Route.Main, {
+      kind: "tts.end",
+      contextId,
+      timestampMs: this.now(),
+    } satisfies TextToSpeechEndPacket);
+  }
+
+  private emitError(contextId: string, err: Error): void {
+    const category = categorizeTtsError(err);
+    const packet: TtsErrorPacket = {
+      kind: "tts.error",
+      contextId,
+      timestampMs: this.now(),
+      component: "tts",
+      category,
+      cause: err,
+      isRecoverable: isRecoverable(category),
+    };
+    this.deps.sink.push(Route.Critical, packet);
+  }
+
+  private emitMetric(contextId: string, name: string, value: string): void {
+    this.deps.sink.push(Route.Background, {
+      kind: "metric.conversation",
+      contextId,
+      timestampMs: this.now(),
+      name,
+      value,
+    });
+  }
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.byteLength + b.byteLength);
+  out.set(a, 0);
+  out.set(b, a.byteLength);
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+
+export { createTtsEngine, type TtsEngine, type TtsEngineDeps } from "./engine.js";
+export {
+  startStreamingTtsSession,
+  defaultNodeSocketFactory,
+  type StreamingTtsSpec,
+  type StreamingTtsSession,
+} from "./plugin.js";
+export {
+  attributionKey,
+  type AttributionKey,
+  type WireEvent,
+  type WireProtocol,
+  type Transport,
+  type TimerPort,
+  type TimerHandle,
+  type PacketSink,
+} from "./types.js";

package/src/plugin.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+//
+// Ergonomic factory: wires a provider `WireProtocol` into a running streaming-TTS session
+// over a `WebSocketConnection`-backed transport, with the standard PipelineBus wiring
+// (tts.text→onText / tts.done→onDone / interrupt.tts→onInterrupt). A provider's published
+// `*TTSPlugin` class delegates `initialize`/`close` to this — its public surface is unchanged.
+
+import { Route, type AudioFormat, type PipelineBus, type RetryConfig } from "@kuralle-syrinx/core";
+import { WebSocketConnection, type SocketData, type SocketFactory } from "@kuralle-syrinx/ws";
+
+import { createTtsEngine } from "./engine.js";
+import type { WireProtocol } from "./types.js";
+
+export interface StreamingTtsSpec {
+  readonly protocol: WireProtocol;
+  readonly provider: { readonly name: string; readonly model: string; readonly region?: string };
+  readonly format: AudioFormat;
+  readonly sampleRateHz: number;
+  readonly url: () => string;
+  readonly headers?: Record<string, string>;
+  readonly retry: RetryConfig;
+  readonly finishTimeoutMs: number;
+  readonly metricPrefix: string;
+  readonly socketFactory: SocketFactory;
+  readonly maxReconnectAttempts?: number;
+  readonly connectTimeoutMs?: number;
+  readonly replayBufferSize?: number;
+  readonly keepAliveIntervalMs?: number;
+  readonly keepAliveMessage?: () => SocketData;
+}
+
+export interface StreamingTtsSession {
+  dispose(): Promise<void>;
+}
+
+/** Open the provider socket, wire the bus, and return a handle whose `dispose()` tears it all down. */
+export async function startStreamingTtsSession(
+  bus: PipelineBus,
+  spec: StreamingTtsSpec,
+): Promise<StreamingTtsSession> {
+  let conn: WebSocketConnection;
+  const engine = createTtsEngine({
+    protocol: spec.protocol,
+    transport: {
+      ensureReady: () => conn.ensureReady(),
+      send: (frame) => conn.send(frame),
+      close: () => conn.close(),
+    },
+    sink: { push: (route, packet) => bus.push(route, packet as Parameters<PipelineBus["push"]>[1]) },
+    format: spec.format,
+    sampleRateHz: spec.sampleRateHz,
+    provider: spec.provider,
+    finishTimeoutMs: spec.finishTimeoutMs,
+    metricPrefix: spec.metricPrefix,
+  });
+
+  conn = new WebSocketConnection({
+    url: spec.url,
+    headers: spec.headers,
+    socketFactory: spec.socketFactory,
+    retry: spec.retry,
+    maxReconnectAttempts: spec.maxReconnectAttempts,
+    connectTimeoutMs: spec.connectTimeoutMs,
+    replayBufferSize: spec.replayBufferSize,
+    keepAliveIntervalMs: spec.keepAliveIntervalMs,
+    keepAliveMessage: spec.keepAliveMessage,
+    onMessage: (data, isBinary) => engine.onMessage(data, isBinary),
+    onConnectionLost: (err) => engine.onConnectionLost(err),
+    onUnrecoverable: (err) => engine.onConnectionLost(err),
+    onReplay: (event, count) =>
+      bus.push(Route.Background, {
+        kind: "metric.conversation",
+        contextId: "",
+        timestampMs: Date.now(),
+        name: `${spec.metricPrefix}.reconnect_replay_${event}`,
+        value: String(count),
+      }),
+  });
+  await conn.connect();
+
+  const disposers: Array<() => void> = [
+    bus.on("tts.text", async (pkt: unknown) => {
+      const textPkt = pkt as { text: string; contextId: string };
+      await engine.onText(textPkt.text, textPkt.contextId);
+    }),
+    bus.on("tts.done", async (pkt: unknown) => {
+      const donePkt = pkt as { contextId: string };
+      await engine.onDone(donePkt.contextId);
+    }),
+    bus.on("interrupt.tts", () => {
+      engine.onInterrupt().catch(() => {
+        // Best-effort interruption.
+      });
+    }),
+  ];
+
+  return {
+    dispose: async () => {
+      for (const dispose of disposers.splice(0)) dispose();
+      await engine.close();
+    },
+  };
+}
+
+/** Default Node socket factory — lazily imported so the heavy `ws` dep only loads when used. */
+export async function defaultNodeSocketFactory(): Promise<SocketFactory> {
+  const mod = await import("@kuralle-syrinx/ws/node");
+  return mod.createNodeWsSocket;
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MIT
+//
+// Ports for the shared streaming-TTS deep module. The domain core (`engine.ts`) depends
+// only on these interfaces — never on a concrete socket or a specific provider. Each
+// provider supplies a `WireProtocol`; the runtime supplies a `Transport`.
+
+import type { Route } from "@kuralle-syrinx/core";
+import type { SocketData } from "@kuralle-syrinx/ws";
+
+/**
+ * Opaque attribution key. The engine NEVER parses it — it only uses it as a map key for
+ * carry/active/cancel bookkeeping. Providers mint it: a per-context provider returns the
+ * contextId; a single-stream provider returns a constant; a multiplexed provider returns
+ * `${contextId}:${seq}`. The single/per-context/per-request distinction is entirely a
+ * function of what key `WireProtocol.attributionFor` returns — there is no mode flag.
+ */
+export type AttributionKey = string & { readonly __brand: "TtsAttributionKey" };
+
+export function attributionKey(value: string): AttributionKey {
+  return value as AttributionKey;
+}
+
+/**
+ * Decoded result of one inbound provider frame — a list, because a single frame can carry
+ * several aspects (e.g. cartesia ships audio + word-timestamps + a done flag together).
+ *
+ * `utterance_end` vs `context_end` is the one real semantic split between providers:
+ * - `utterance_end` — one attribution unit finished; the context ends only once every unit
+ *   is done AND the engine has seen `tts.done` (the multiplexed/refcount model, e.g. epsilon).
+ * - `context_end` — the provider declares the whole context complete; emit `tts.end` now,
+ *   regardless of `tts.done` (the single-stream model, e.g. cartesia `done:true`, grok `audio.done`).
+ */
+export type WireEvent =
+  | { readonly type: "audio"; readonly key: AttributionKey; readonly pcm: Uint8Array }
+  | { readonly type: "utterance_end"; readonly key: AttributionKey }
+  | { readonly type: "context_end"; readonly key: AttributionKey }
+  | { readonly type: "cancelled"; readonly key: AttributionKey }
+  | {
+      readonly type: "error";
+      readonly key: AttributionKey | null;
+      readonly error: Error;
+      /** When true, this error is also the context's terminal signal → emit `tts.end` too
+       *  (e.g. cartesia's `{type:"error", done:true}`). Default false: report the error only. */
+      readonly endsContext?: boolean;
+    }
+  | {
+      readonly type: "sideband";
+      readonly key: AttributionKey;
+      readonly route: Route;
+      readonly build: (contextId: string, timestampMs: number) => unknown;
+    }
+  | { readonly type: "ignore" };
+
+/**
+ * DRIVEN PORT — the provider wire protocol. Pure of sockets, timers, and the bus. This is the
+ * only surface a provider implements; everything else lives in the engine.
+ */
+export interface WireProtocol {
+  /** Mint the attribution key (and echo the contextId) for a new utterance request. */
+  attributionFor(contextId: string): { readonly key: AttributionKey; readonly contextId: string };
+  /** Encode a text chunk into the exact wire frame(s) to send. Return `[]` to send nothing. */
+  encodeText(key: AttributionKey, text: string): readonly SocketData[];
+  /** Encode the "no more text for this context" frame(s). `[]` if the provider has none. */
+  encodeFinish(contextId: string, activeKeys: readonly AttributionKey[]): readonly SocketData[];
+  /** Encode the cancel frame(s) for one attribution key. `[]` if the provider has no cancel. */
+  encodeCancel(key: AttributionKey, contextId: string): readonly SocketData[];
+  /** Optional session-teardown frame(s) sent best-effort on close (e.g. `{type:"eos"}`). */
+  encodeClose(): readonly SocketData[];
+  /** Decode one inbound socket frame into domain events (0+). Throwing is treated as fatal. */
+  decode(data: SocketData, isBinary: boolean): readonly WireEvent[];
+}
+
+/** DRIVEN PORT — transport. Production wraps a `WebSocketConnection`; tests pass a fake. */
+export interface Transport {
+  ensureReady(): Promise<void>;
+  send(frame: SocketData): void;
+  close(): Promise<void>;
+}
+
+export type TimerHandle = unknown;
+
+/** Injectable timers so finish-timeout behavior is deterministic in tests. */
+export interface TimerPort {
+  set(ms: number, fn: () => void): TimerHandle;
+  clear(handle: TimerHandle): void;
+}
+
+/** The bus, narrowed to the one method the engine needs. Injectable for socket-free tests. */
+export interface PacketSink {
+  push(route: Route, packet: unknown): void;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["vitest/globals"],
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}