@kuralle-syrinx/tts-core 4.1.0 → 4.2.0

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "@kuralle-syrinx/tts-core",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "private": false,
-  "type": "module",
+  "description": "Shared streaming-TTS lifecycle engine for Syrinx TTS adapters — carry, refcount, finish-timeout, cancel",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "text-to-speech",
+    "streaming"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/tts-core"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@kuralle-syrinx/core": "4.1.0",
-    "@kuralle-syrinx/ws": "4.1.0"
+    "@kuralle-syrinx/core": "4.2.0",
+    "@kuralle-syrinx/ws": "4.2.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

package/src/engine.test.ts

@@ -10,20 +10,42 @@ const FORMAT: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 24000, channe
 const SESSION = attributionKey("session");
 
 class FakeTimer implements TimerPort {
-  private readonly timers = new Map<number, () => void>();
+  private readonly timers = new Map<number, { due: number; fn: () => void }>();
   private next = 0;
-  set(_ms: number, fn: () => void): TimerHandle {
+  private time = 0;
+  set(ms: number, fn: () => void): TimerHandle {
     const handle = this.next++;
-    this.timers.set(handle, fn);
+    this.timers.set(handle, { due: this.time + ms, fn });
     return handle;
   }
   clear(handle: TimerHandle): void {
     this.timers.delete(handle as number);
   }
+  /** Advance the fake clock; fire any timers whose due time is now reached. */
+  advance(ms: number): void {
+    this.time += ms;
+    this.fireDue();
+  }
+  /** Fire every pending timer immediately (legacy tests). */
   fire(): void {
-    for (const [handle, fn] of [...this.timers]) {
+    for (const [handle, entry] of [...this.timers]) {
       this.timers.delete(handle);
-      fn();
+      entry.fn();
+    }
+  }
+  private fireDue(): void {
+    let progressed = true;
+    while (progressed) {
+      progressed = false;
+      const due = [...this.timers.entries()]
+        .filter(([, e]) => e.due <= this.time)
+        .sort((a, b) => a[1].due - b[1].due);
+      for (const [handle, entry] of due) {
+        if (!this.timers.has(handle)) continue;
+        this.timers.delete(handle);
+        entry.fn();
+        progressed = true;
+      }
     }
   }
 }
@@ -190,6 +212,71 @@ describe("TtsEngine — multiplex (epsilon-shape)", () => {
   });
 });
 
+describe("TtsEngine — finish-timeout inactivity watchdog", () => {
+  const FINISH_MS = 2000;
+  const EPS = 500; // advance finishTimeoutMs - ε between audio frames
+
+  it("does not end while audio keeps arriving after flush (even past finishTimeoutMs total)", async () => {
+    const h = harness(new SingleProtocol(), FINISH_MS);
+    await h.engine.onText("long turn", "ctxStream");
+    await h.engine.onDone("ctxStream");
+    expect(h.ends()).toHaveLength(0);
+
+    // Three chunks spaced (FINISH_MS - ε) apart → wall time > FINISH_MS, but never silent that long.
+    const chunks = [
+      [1, 2],
+      [3, 4],
+      [5, 6],
+    ] as const;
+    for (let i = 0; i < chunks.length; i++) {
+      if (i > 0) h.timer.advance(FINISH_MS - EPS);
+      h.engine.onMessage(
+        JSON.stringify({ t: "audio", key: "session", pcm: [...chunks[i]!] }),
+        false,
+      );
+      expect(h.ends()).toHaveLength(0);
+    }
+
+    expect(h.audio()).toHaveLength(3);
+    expect([...(h.audio()[0]!["audio"] as Uint8Array)]).toEqual([1, 2]);
+    expect([...(h.audio()[1]!["audio"] as Uint8Array)]).toEqual([3, 4]);
+    expect([...(h.audio()[2]!["audio"] as Uint8Array)]).toEqual([5, 6]);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(false);
+
+    // Natural provider end still closes the turn.
+    h.engine.onMessage(JSON.stringify({ t: "done", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1);
+  });
+
+  it("still fires finish-timeout after finishTimeoutMs of silence post-flush (wedged provider)", async () => {
+    const h = harness(new SingleProtocol(), FINISH_MS);
+    await h.engine.onText("a", "ctxWedge");
+    await h.engine.onDone("ctxWedge");
+    expect(h.ends()).toHaveLength(0);
+
+    h.timer.advance(FINISH_MS - 1);
+    expect(h.ends()).toHaveLength(0);
+
+    h.timer.advance(1);
+    expect(h.ends()).toHaveLength(1);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(true);
+  });
+
+  it("ends immediately on natural context_end even if finish-timeout is armed", async () => {
+    const h = harness(new SingleProtocol(), FINISH_MS);
+    await h.engine.onText("a", "ctxNatural");
+    await h.engine.onDone("ctxNatural");
+    expect(h.ends()).toHaveLength(0);
+
+    h.engine.onMessage(JSON.stringify({ t: "end", key: "session" }), false);
+    expect(h.ends()).toHaveLength(1);
+    // Armed timer must not emit a second end or a finish_timeout metric.
+    h.timer.advance(FINISH_MS * 2);
+    expect(h.ends()).toHaveLength(1);
+    expect(h.metrics().some((m) => m["name"] === "tts.fake.finish_timeout")).toBe(false);
+  });
+});
+
 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);

package/src/engine.ts

@@ -191,6 +191,13 @@ class TtsEngineImpl implements TtsEngine {
     if (contextId === undefined || this.cancelledContexts.has(contextId)) return;
     if (pcm.byteLength === 0) return;
 
+    // After flush, finish-timeout is an inactivity watchdog: keep it armed only
+    // while the provider is silent. Active audio must reschedule so long turns
+    // (e.g. half-cascade dumping full text then tts.done early) are not cut mid-stream.
+    if (this.pendingEnd.has(contextId) && this.deps.finishTimeoutMs > 0) {
+      this.scheduleFinishTimeout(contextId);
+    }
+
     const prev = this.carry.get(key) ?? EMPTY;
     const buf = prev.byteLength === 0 ? pcm : concatBytes(prev, pcm);
     const evenLen = buf.byteLength - (buf.byteLength % 2);