@kuralle-syrinx/server-websocket 4.2.0 → 4.3.0

package/src/outbound-playout-pipeline.test.ts

@@ -1,314 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { EventEmitter } from "node:events";
-import { describe, expect, it } from "vitest";
-import WebSocket from "ws";
-import { Route, VoiceAgentSession } from "@kuralle-syrinx/core";
-import { pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
-import { BackgroundAudioMixer } from "./background-audio.js";
-import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation, type RotatableTurnContext } from "./outbound-playout-pipeline.js";
-
-function createMockSocket(): WebSocket {
-  const emitter = new EventEmitter();
-  let readyState: number = WebSocket.OPEN;
-  return {
-    get readyState() {
-      return readyState;
-    },
-    close: () => {
-      readyState = WebSocket.CLOSED;
-      emitter.emit("close");
-    },
-    terminate: () => {
-      readyState = WebSocket.CLOSED;
-      emitter.emit("close");
-    },
-    once: (event: string, handler: () => void) => {
-      emitter.once(event, handler);
-    },
-    off: (event: string, handler: () => void) => {
-      emitter.off(event, handler);
-    },
-  } as WebSocket;
-}
-
-function wireTestPipeline(socket: WebSocket): {
-  readonly session: VoiceAgentSession;
-  readonly handle: ReturnType<typeof wireTelephonyOutboundPipeline>;
-  readonly disposers: Array<() => void>;
-} {
-  const session = new VoiceAgentSession({ plugins: {} });
-  void session.start();
-  const disposers: Array<() => void> = [];
-  const handle = wireTelephonyOutboundPipeline({
-    session,
-    socket,
-    disposers,
-    outboundFrameDurationMs: 20,
-    maxQueuedOutputAudioMs: 30_000,
-    callbacks: {
-      carrierLabel: "test",
-      getContextId: () => "turn-drain",
-      isActive: () => true,
-      encodeFrames: (audio) => [{
-        contextId: "turn-drain",
-        send: () => true,
-      }],
-      onInterrupt: () => undefined,
-      onDrain: () => undefined,
-      onStop: () => undefined,
-    },
-  });
-  return { session, handle, disposers };
-}
-
-function makeFrames(count: number): Array<{ contextId: string; send: () => boolean }> {
-  return Array.from({ length: count }, () => ({
-    contextId: "turn-drain",
-    send: () => true,
-  }));
-}
-
-describe("wireTelephonyOutboundPipeline.interrupt.tts", () => {
-  it("clears playout and emits interrupt_onset_to_media_silent_ms", async () => {
-    const socket = createMockSocket();
-    const { session, disposers } = wireTestPipeline(socket);
-    const mediaSilentMetrics: Array<{ name: string; value: string }> = [];
-
-    session.bus.on("metric.conversation", (pkt) => {
-      const metric = pkt as unknown as { name: string; value: string };
-      if (metric.name === "test.interrupt_onset_to_media_silent_ms") mediaSilentMetrics.push(metric);
-    });
-
-    const onset = Date.now() - 25;
-    session.bus.push(Route.Critical, {
-      kind: "interrupt.tts",
-      contextId: "turn-drain",
-      timestampMs: onset,
-    });
-    await new Promise((resolve) => setTimeout(resolve, 10));
-
-    expect(mediaSilentMetrics).toEqual([
-      expect.objectContaining({
-        name: "test.interrupt_onset_to_media_silent_ms",
-        value: expect.stringMatching(/^\d+$/),
-      }),
-    ]);
-    expect(Number(mediaSilentMetrics[0]!.value)).toBeGreaterThanOrEqual(0);
-
-    for (const dispose of disposers) dispose();
-  });
-});
-
-describe("wireTelephonyOutboundPipeline overflow", () => {
-  it("drops the overflow tail at the cap without stopping playout or closing the socket", async () => {
-    const socket = createMockSocket();
-    const session = new VoiceAgentSession({ plugins: {} });
-    await session.start();
-    const disposers: Array<() => void> = [];
-    const stops: string[] = [];
-    const discardedMetrics: Array<{ name: string; value: string }> = [];
-    let encodeCall = 0;
-
-    wireTelephonyOutboundPipeline({
-      session,
-      socket,
-      disposers,
-      outboundFrameDurationMs: 20,
-      maxQueuedOutputAudioMs: 200,
-      callbacks: {
-        carrierLabel: "test",
-        getContextId: () => "turn-drain",
-        isActive: () => true,
-        encodeFrames: () => {
-          encodeCall += 1;
-          return makeFrames(encodeCall === 1 ? 10 : 2);
-        },
-        onInterrupt: () => undefined,
-        onDrain: () => undefined,
-        onStop: (reason) => {
-          stops.push(reason);
-        },
-      },
-    });
-    session.bus.on("metric.conversation", (pkt) => {
-      const metric = pkt as unknown as { name: string; value: string };
-      if (metric.name === "test.overflow_playout_cleared_ms") {
-        discardedMetrics.push(metric);
-      }
-    });
-
-    session.bus.push(Route.Main, {
-      kind: "tts.audio",
-      contextId: "turn-drain",
-      timestampMs: Date.now(),
-      audio: new Uint8Array([1, 2, 3, 4]),
-      sampleRateHz: 8000,
-    });
-    await new Promise((resolve) => setTimeout(resolve, 5));
-    session.bus.push(Route.Main, {
-      kind: "tts.audio",
-      contextId: "turn-drain",
-      timestampMs: Date.now(),
-      audio: new Uint8Array([5, 6, 7, 8]),
-      sampleRateHz: 8000,
-    });
-    await new Promise((resolve) => setTimeout(resolve, 20));
-
-    expect(stops).toEqual([]); // overflow is non-fatal — playout continues
-    expect(discardedMetrics).toEqual([
-      expect.objectContaining({
-        name: "test.overflow_playout_cleared_ms",
-        value: expect.stringMatching(/^\d+$/),
-      }),
-    ]);
-    expect(Number(discardedMetrics[0]!.value)).toBeGreaterThan(0);
-    expect(socket.readyState).toBe(WebSocket.OPEN);
-
-    for (const dispose of disposers) dispose();
-    await session.close();
-  });
-});
-
-describe("wireTelephonyOutboundPipeline.drainAndClose", () => {
-  it("resolves immediately when the playout queue is idle", async () => {
-    const socket = createMockSocket();
-    const { handle, disposers } = wireTestPipeline(socket);
-
-    const startedAt = Date.now();
-    await handle.drainAndClose(socket, Date.now() + 30_000);
-    expect(Date.now() - startedAt).toBeLessThan(500);
-
-    for (const dispose of disposers) dispose();
-  });
-
-  it("settles promptly when the socket closes before queued playout control runs", async () => {
-    const socket = createMockSocket();
-    const { session, handle, disposers } = wireTestPipeline(socket);
-
-    const longAudio = pcm16SamplesToBytes(new Int16Array(8000 * 2));
-    session.bus.push(Route.Main, {
-      kind: "tts.audio",
-      contextId: "turn-drain",
-      timestampMs: Date.now(),
-      audio: longAudio,
-      sampleRateHz: 8000,
-    });
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    const startedAt = Date.now();
-    const drainPromise = handle.drainAndClose(socket, Date.now() + 30_000);
-    await new Promise((resolve) => setTimeout(resolve, 10));
-    socket.close();
-    await drainPromise;
-
-    expect(Date.now() - startedAt).toBeLessThan(500);
-
-    for (const dispose of disposers) dispose();
-  });
-});
-
-describe("installTelephonyTurnRotation", () => {
-  // Regression for the telephony "deaf after turn 1" P0: a carrier gives one
-  // stream per call, but STT/TTS retire a contextId once its turn completes, so
-  // reusing a single callSid id muted the agent after turn 1. Every turn must get
-  // a fresh per-turn id with a turn.change boundary.
-  it("rotates a per-turn contextId and emits turn.change on each completed turn", async () => {
-    const session = new VoiceAgentSession({ plugins: {} });
-    void session.start();
-    const disposers: Array<() => void> = [];
-    const state: RotatableTurnContext = {
-      contextId: "twilio-CA123",
-      contextBase: "twilio-CA123",
-      turnCounter: 0,
-    };
-    const turnChanges: Array<{ contextId: string; previousContextId: string; reason: string }> = [];
-    session.bus.on("turn.change", (pkt) => {
-      const change = pkt as unknown as { contextId: string; previousContextId: string; reason: string };
-      turnChanges.push({ contextId: change.contextId, previousContextId: change.previousContextId, reason: change.reason });
-    });
-
-    installTelephonyTurnRotation(session, disposers, state);
-
-    // Turn 1 runs on the base id.
-    expect(state.contextId).toBe("twilio-CA123");
-
-    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "twilio-CA123", timestampMs: Date.now(), text: "one", transcripts: [] });
-    await new Promise((r) => setTimeout(r, 0));
-    expect(state.contextId).toBe("twilio-CA123-t1");
-
-    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "twilio-CA123-t1", timestampMs: Date.now(), text: "two", transcripts: [] });
-    await new Promise((r) => setTimeout(r, 0));
-    expect(state.contextId).toBe("twilio-CA123-t2");
-
-    expect(turnChanges).toEqual([
-      { contextId: "twilio-CA123-t1", previousContextId: "twilio-CA123", reason: "telephony_turn_complete" },
-      { contextId: "twilio-CA123-t2", previousContextId: "twilio-CA123-t1", reason: "telephony_turn_complete" },
-    ]);
-
-    for (const dispose of disposers) dispose();
-    await session.close();
-  });
-
-  it("no-ops until a base is set", async () => {
-    const session = new VoiceAgentSession({ plugins: {} });
-    void session.start();
-    const disposers: Array<() => void> = [];
-    const state: RotatableTurnContext = { contextId: "", contextBase: "", turnCounter: 0 };
-    installTelephonyTurnRotation(session, disposers, state);
-    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "", timestampMs: Date.now(), text: "", transcripts: [] });
-    await new Promise((r) => setTimeout(r, 0));
-    expect(state.contextId).toBe("");
-    expect(state.turnCounter).toBe(0);
-    for (const dispose of disposers) dispose();
-    await session.close();
-  });
-
-  it("mixes the background bed into speech before per-carrier encoding", async () => {
-    const socket = createMockSocket();
-    const session = new VoiceAgentSession({ plugins: {} });
-    void session.start();
-    const disposers: Array<() => void> = [];
-    const encodedChunks: Int16Array[] = [];
-    wireTelephonyOutboundPipeline({
-      session,
-      socket,
-      disposers,
-      outboundFrameDurationMs: 20,
-      maxQueuedOutputAudioMs: 30_000,
-      backgroundAudio: new BackgroundAudioMixer({
-        ambient: { pcm: new Int16Array(160).fill(1000), sampleRateHz: 16000, gain: 0.5 },
-        duckWhileSpeaking: 0.5,
-        fadeMs: 0,
-      }),
-      callbacks: {
-        carrierLabel: "test",
-        getContextId: () => "turn-mix",
-        isActive: () => true,
-        encodeFrames: (audio) => {
-          encodedChunks.push(new Int16Array(audio.buffer.slice(audio.byteOffset, audio.byteOffset + audio.byteLength)));
-          return [{ contextId: "turn-mix", send: () => true }];
-        },
-        onInterrupt: () => undefined,
-        onDrain: () => undefined,
-        onStop: () => undefined,
-      },
-    });
-
-    session.bus.push(Route.Main, {
-      kind: "tts.audio",
-      contextId: "turn-mix",
-      timestampMs: Date.now(),
-      audio: pcm16SamplesToBytes(new Int16Array(4)), // silence in → ambient-only out
-      sampleRateHz: 16000,
-    });
-    await new Promise((r) => setTimeout(r, 20));
-
-    expect(encodedChunks).toHaveLength(1);
-    // ambient 1000 × gain 0.5 × duck 0.5 = 250 layered under the (silent) speech
-    expect(Array.from(encodedChunks[0]!)).toEqual([250, 250, 250, 250]);
-
-    for (const dispose of disposers) dispose();
-    await session.close();
-  });
-});

package/src/paced-playout.test.ts

@@ -1,247 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { PacedPlayoutQueue, type PacedPlayoutFrame } from "./paced-playout.js";
-
-function makeFrame(onSend?: () => void): PacedPlayoutFrame {
-  return { send: () => { onSend?.(); } };
-}
-
-describe("PacedPlayoutQueue — drift-corrected scheduling", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("drift-locked cadence: second frame fires at T+FRAME_MS despite slow first send", () => {
-    vi.setSystemTime(0);
-    const FRAME_MS = 20;
-    const sendTimes: number[] = [];
-
-    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
-
-    // First send() runs outside tick() context (maybePump → pump is called
-    // synchronously from enqueue). Safe to call setSystemTime here.
-    // Simulates 8ms of work, so without drift-correction the second timer
-    // would be scheduled at callAt = 0+8+20 = 28 instead of 20.
-    queue.enqueue([
-      {
-        send: () => {
-          sendTimes.push(Date.now());
-          vi.setSystemTime(8);
-        },
-      },
-      { send: () => { sendTimes.push(Date.now()); } },
-    ]);
-
-    // With drift-correction: delay = max(0, 20 - 8) = 12, callAt = 8+12 = 20
-    // Without drift-correction: delay = 20, callAt = 8+20 = 28
-    vi.advanceTimersByTime(20); // covers [8, 28] — fires callAt=20 but NOT callAt=28
-
-    expect(sendTimes).toHaveLength(2);
-    expect(sendTimes[0]).toBe(0);
-    expect(sendTimes[1]).toBe(20); // wall-clock-locked
-  });
-
-  it("fires onDeadlineMiss with correct lateMs when pump wakes up past tolerance", () => {
-    vi.setSystemTime(0);
-    const FRAME_MS = 20;
-    const misses: number[] = [];
-
-    const queue = new PacedPlayoutQueue(
-      FRAME_MS,
-      10_000,
-      () => {},
-      () => {},
-      (lateMs) => misses.push(lateMs),
-    );
-
-    // First send() advances the clock to 30ms (past the T+20 next deadline).
-    // This causes the next timer to be scheduled with delay=0, callAt=30.
-    // When that timer fires, now=30 and nextDeadlineMs=20, so lateMs=10 > 5.
-    queue.enqueue([
-      {
-        send: () => {
-          vi.setSystemTime(30);
-        },
-      },
-      makeFrame(),
-    ]);
-
-    vi.advanceTimersByTime(1); // fire the 0ms timer (callAt=30, advances 30→31)
-
-    expect(misses).toHaveLength(1);
-    expect(misses[0]).toBe(10); // 30 - 20 = 10ms late
-  });
-
-  it("does NOT fire onDeadlineMiss when pump fires on time (within tolerance)", () => {
-    vi.setSystemTime(0);
-    const FRAME_MS = 20;
-    const misses: number[] = [];
-
-    const queue = new PacedPlayoutQueue(
-      FRAME_MS,
-      10_000,
-      () => {},
-      () => {},
-      (lateMs) => misses.push(lateMs),
-    );
-
-    queue.enqueue([makeFrame(), makeFrame(), makeFrame()]);
-
-    // Exact FRAME_MS advances — timers fire precisely on their deadlines.
-    vi.advanceTimersByTime(FRAME_MS);
-    vi.advanceTimersByTime(FRAME_MS);
-
-    expect(misses).toHaveLength(0);
-  });
-
-  it("resets deadline tracking after clear() so next burst starts fresh with no spurious misses", () => {
-    vi.setSystemTime(0);
-    const FRAME_MS = 20;
-    const misses: number[] = [];
-
-    const queue = new PacedPlayoutQueue(
-      FRAME_MS,
-      10_000,
-      () => {},
-      () => {},
-      (lateMs) => misses.push(lateMs),
-    );
-
-    queue.enqueue([makeFrame(), makeFrame()]);
-    vi.advanceTimersByTime(FRAME_MS);
-    queue.clear();
-
-    // Simulate a 5 s inter-utterance gap. Without clear() resetting the
-    // deadline, the next frame would appear ~5000ms late and trigger a miss.
-    vi.advanceTimersByTime(5_000);
-
-    // New burst with no simulated send overhead.
-    queue.enqueue([makeFrame(), makeFrame()]);
-
-    vi.advanceTimersByTime(FRAME_MS);
-
-    // The first frame of a new burst sets the baseline (nextDeadlineMs was 0),
-    // and the second frame fires on schedule — neither should miss.
-    expect(misses).toHaveLength(0);
-  });
-
-  it("re-baselines after a natural drain (no clear) so an inter-sentence gap is not a false miss", () => {
-    vi.setSystemTime(0);
-    const FRAME_MS = 20;
-    const misses: number[] = [];
-
-    const queue = new PacedPlayoutQueue(
-      FRAME_MS,
-      10_000,
-      () => {},
-      () => {},
-      (lateMs) => misses.push(lateMs),
-    );
-
-    // First burst of two frames drains naturally — the queue empties with NO
-    // clear() call (clear() only runs on overflow/send-failure/interrupt).
-    queue.enqueue([makeFrame(), makeFrame()]);
-    vi.advanceTimersByTime(FRAME_MS);
-
-    // Natural inter-sentence gap: no audio, no clear().
-    vi.advanceTimersByTime(2_000);
-
-    // Next burst. Its first frame must re-baseline rather than read the stale
-    // pre-gap deadline as a ~2000ms miss.
-    queue.enqueue([makeFrame(), makeFrame()]);
-    vi.advanceTimersByTime(FRAME_MS);
-
-    expect(misses).toHaveLength(0);
-  });
-
-  it("does not advance the playout deadline by frameDurationMs after a 0 ms control frame", () => {
-    const FRAME_MS = 20;
-    let sends = 0;
-    const misses: number[] = [];
-
-    const queue = new PacedPlayoutQueue(
-      FRAME_MS,
-      10_000,
-      () => {},
-      () => {},
-      (lateMs) => misses.push(lateMs),
-    );
-
-    queue.enqueue([{ send: () => { sends += 1; } }]);
-    expect(sends).toBe(1);
-    queue.enqueueControl(() => { sends += 1; });
-    queue.enqueue([{ send: () => { sends += 1; } }]);
-    vi.advanceTimersByTime(FRAME_MS);
-    expect(sends).toBe(3);
-    vi.advanceTimersByTime(FRAME_MS);
-    expect(sends).toBe(3);
-    expect(misses).toHaveLength(0);
-  });
-
-  it("backward-compatible: works without onDeadlineMiss callback", () => {
-    const queue = new PacedPlayoutQueue(20, 10_000, () => {});
-    expect(() => {
-      queue.enqueue([makeFrame(), makeFrame()]);
-      vi.advanceTimersByTime(40);
-    }).not.toThrow();
-  });
-
-  it("clearInterruptible drops audio but retains an uninterruptible control frame", () => {
-    const FRAME_MS = 20;
-    const sends: string[] = [];
-    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
-
-    // a1 sends synchronously on enqueue; a2 + a3 remain queued behind the pacer timer.
-    queue.enqueue([
-      { send: () => { sends.push("a1"); } },
-      { send: () => { sends.push("a2"); } },
-      { send: () => { sends.push("a3"); } },
-    ]);
-    expect(sends).toEqual(["a1"]);
-
-    queue.enqueueControl(() => { sends.push("ctrl"); }, { uninterruptible: true });
-
-    const discarded = queue.clearInterruptible();
-
-    // a2 + a3 (interruptible audio) dropped; the uninterruptible control survives and is pumped.
-    expect(discarded).toBe(2 * FRAME_MS);
-    expect(sends).toEqual(["a1", "ctrl"]);
-
-    // No dropped audio is ever replayed on later ticks.
-    vi.advanceTimersByTime(FRAME_MS * 5);
-    expect(sends).toEqual(["a1", "ctrl"]);
-  });
-
-  it("clearInterruptible never replays dropped audio frames", () => {
-    const FRAME_MS = 20;
-    const sends: string[] = [];
-    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
-    queue.enqueue([
-      { send: () => { sends.push("a1"); } },
-      { send: () => { sends.push("a2"); } },
-      { send: () => { sends.push("a3"); } },
-    ]);
-    queue.clearInterruptible();
-    vi.advanceTimersByTime(FRAME_MS * 5);
-    expect(sends).toEqual(["a1"]); // a2/a3 never sent — no speech replay after interrupt
-  });
-
-  it("clearInterruptible drops unmarked control frames (back-compat with clear)", () => {
-    const FRAME_MS = 20;
-    const sends: string[] = [];
-    const queue = new PacedPlayoutQueue(FRAME_MS, 10_000, () => {});
-    queue.enqueue([
-      { send: () => { sends.push("a1"); } },
-      { send: () => { sends.push("a2"); } },
-    ]);
-    queue.enqueueControl(() => { sends.push("ctrl"); }); // default = interruptible
-    queue.clearInterruptible();
-    vi.advanceTimersByTime(FRAME_MS * 5);
-    expect(sends).toEqual(["a1"]); // a2 + unmarked control both dropped
-  });
-});

package/src/playout-progress.test.ts

@@ -1,56 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it } from "vitest";
-import { PipelineBusImpl } from "@kuralle-syrinx/core";
-import { PlayoutProgressEmitter } from "./playout-progress.js";
-
-async function withRunningBus(fn: (bus: PipelineBusImpl) => void | Promise<void>): Promise<void> {
-  const bus = new PipelineBusImpl();
-  const startP = bus.start();
-  await new Promise((resolve) => setTimeout(resolve, 5));
-  await fn(bus);
-  await new Promise((resolve) => setTimeout(resolve, 5));
-  bus.stop();
-  await startP;
-}
-
-describe("PlayoutProgressEmitter", () => {
-  it("emits playout_started on the first paced audio frame and throttles progress", async () => {
-    const startedAt: number[] = [];
-    const progress: number[] = [];
-
-    await withRunningBus((bus) => {
-      bus.on("tts.playout_started", (pkt) => {
-        startedAt.push((pkt as { timestampMs: number }).timestampMs);
-      });
-      bus.on("tts.playout_progress", (pkt) => {
-        progress.push((pkt as unknown as { playedOutMs: number }).playedOutMs);
-      });
-
-      const emitter = new PlayoutProgressEmitter(bus);
-      emitter.onFramePlayed("turn-a", 20);
-      emitter.onFramePlayed("turn-a", 20);
-      emitter.onFramePlayed("turn-a", 200);
-    });
-
-    expect(startedAt).toHaveLength(1);
-    expect(progress).toEqual([240]);
-  });
-
-  it("re-emits playout_started after discard resets context tracking", async () => {
-    let startedCount = 0;
-
-    await withRunningBus((bus) => {
-      bus.on("tts.playout_started", () => {
-        startedCount += 1;
-      });
-
-      const emitter = new PlayoutProgressEmitter(bus);
-      emitter.onFramePlayed("turn-a", 20);
-      emitter.discard("turn-a");
-      emitter.onFramePlayed("turn-a", 20);
-    });
-
-    expect(startedCount).toBe(2);
-  });
-});