@kuralle-syrinx/server-websocket 4.4.1 → 4.5.0

package/src/browser-pacing.test.ts

@@ -0,0 +1,440 @@
+// SPDX-License-Identifier: MIT
+// WT-03: Browser outbound pacing + playout clock + client jitter buffer
+
+import { createServer } from "node:http";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import WebSocket from "ws";
+import { Route, VoiceAgentSession } from "@kuralle-syrinx/core";
+import { pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
+import { createVoiceWebSocketServer, type VoiceWebSocketServer } from "./index.js";
+
+function browserUrl(port: number): string {
+  return `ws://127.0.0.1:${port}/ws`;
+}
+
+async function openBrowserSocketReady(url: string): Promise<WebSocket> {
+  const socket = new WebSocket(url);
+  await new Promise<void>((resolve, reject) => {
+    const onMessage = (data: WebSocket.RawData, isBinary: boolean): void => {
+      if (isBinary) return;
+      try {
+        const parsed = JSON.parse(data.toString()) as { type?: string };
+        if (parsed.type === "ready") {
+          socket.off("message", onMessage);
+          resolve();
+        }
+      } catch {
+        // Ignore parsing errors
+      }
+    };
+    socket.on("message", onMessage);
+    socket.once("error", reject);
+  });
+  return socket;
+}
+
+function waitMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForCondition(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (predicate()) return;
+    await waitMs(10);
+  }
+  throw new Error("Timed out waiting for browser pacing condition");
+}
+
+async function readJsonMatching(socket: WebSocket, predicate: (m: unknown) => boolean): Promise<unknown> {
+  return new Promise((resolve) => {
+    const onMessage = (data: WebSocket.RawData, isBinary: boolean) => {
+      if (isBinary) return;
+      const message = JSON.parse(data.toString()) as unknown;
+      if (!predicate(message)) return;
+      socket.off("message", onMessage);
+      resolve(message);
+    };
+    socket.on("message", onMessage);
+  });
+}
+
+function collectMessagesMatching(
+  socket: WebSocket, 
+  predicate: (m: unknown) => boolean, 
+  timeoutMs: number
+): Promise<unknown[]> {
+  return new Promise((resolve) => {
+    const messages: unknown[] = [];
+    const timeout = setTimeout(() => {
+      socket.off("message", onMessage);
+      resolve(messages);
+    }, timeoutMs);
+
+    const onMessage = (data: WebSocket.RawData, isBinary: boolean) => {
+      if (isBinary) return;
+      try {
+        const message = JSON.parse(data.toString()) as unknown;
+        if (predicate(message)) {
+          messages.push(message);
+        }
+      } catch {
+        // Ignore parsing errors
+      }
+    };
+    socket.on("message", onMessage);
+  });
+}
+
+// Track servers so we can force-close them in afterEach even if test fails
+let activeServers: VoiceWebSocketServer[] = [];
+let activeHttpServers: ReturnType<typeof createServer>[] = [];
+
+beforeEach(() => {
+  activeServers = [];
+  activeHttpServers = [];
+});
+
+afterEach(async () => {
+  for (const server of activeServers) {
+    await server.close().catch(() => undefined);
+  }
+  for (const httpServer of activeHttpServers) {
+    httpServer.close();
+  }
+  activeServers = [];
+  activeHttpServers = [];
+});
+
+describe("WT-03 Browser outbound pacing", () => {
+  it("browser adapter enqueues paced frames with consistent timing", async () => {
+    const httpServer = createServer();
+    activeHttpServers.push(httpServer);
+    
+    let session: VoiceAgentSession | null = null;
+    const server = await createVoiceWebSocketServer({
+      server: httpServer,
+      port: 0, // Let the system assign a port
+      createSession: () => {
+        session = new VoiceAgentSession({ plugins: {} });
+        return session;
+      },
+      outboundFrameDurationMs: 20,
+    });
+    activeServers.push(server);
+
+    const port = (server.address() as any).port;
+    const socket = await openBrowserSocketReady(browserUrl(port));
+
+    // Session is already started by the websocket server
+
+    // Send TTS audio - 160ms of 16kHz PCM16 (should be split into ~8 frames of 20ms each)
+    const sampleCount = Math.floor(0.16 * 16000); // 160ms at 16kHz
+    const audioSamples = new Int16Array(sampleCount).fill(1000); // Simple sine-like values
+    const audioBytes = pcm16SamplesToBytes(audioSamples);
+
+    // Collect tts_chunk messages over 200ms to ensure all frames arrive
+    const ttsChunksPromise = collectMessagesMatching(
+      socket,
+      (m: any) => m.type === "tts_chunk",
+      300
+    );
+
+    // Send TTS audio
+    session!.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+      audio: audioBytes,
+      sampleRateHz: 16000,
+    });
+
+    // End TTS
+    session!.bus.push(Route.Main, {
+      kind: "tts.end",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+    });
+
+    const ttsChunks = await ttsChunksPromise;
+    socket.close();
+
+    // Verify we got multiple frames (pacing is working)
+    expect(ttsChunks.length).toBeGreaterThan(1);
+    
+    // Verify each frame has expected structure
+    for (const chunk of ttsChunks) {
+      const c = chunk as any;
+      expect(c.type).toBe("tts_chunk");
+      expect(c.turnId).toBe("test-turn");
+      expect(c.sequence).toBeGreaterThan(0);
+      expect(c.sampleRateHz).toBe(48000); // opus frames carry the 48 kHz codec rate
+      expect(c.encoding).toBe("opus");
+      expect(c.channels).toBe(1);
+      expect(c.byteLength).toBeGreaterThan(0);
+      expect(c.durationMs).toBeGreaterThan(0);
+    }
+
+    // Verify sequence numbers increment
+    const sequences = ttsChunks.map((c: any) => c.sequence);
+    for (let i = 1; i < sequences.length; i++) {
+      expect(sequences[i]).toBe(sequences[i - 1] + 1);
+    }
+  });
+
+  it("emits tts.playout_progress events during paced playback", async () => {
+    const httpServer = createServer();
+    activeHttpServers.push(httpServer);
+    
+    let session: VoiceAgentSession | null = null;
+    const server = await createVoiceWebSocketServer({
+      server: httpServer,
+      port: 0,
+      createSession: () => {
+        session = new VoiceAgentSession({ plugins: {} });
+        return session;
+      },
+      outboundFrameDurationMs: 20,
+    });
+    activeServers.push(server);
+
+    const port = (server.address() as any).port;
+    const socket = await openBrowserSocketReady(browserUrl(port));
+
+    // Session is already started by the websocket server
+
+    // Track playout progress events
+    const progressEvents: any[] = [];
+    const removeProgressHandler = session!.bus.on("tts.playout_progress", (pkt: any) => {
+      if (pkt.contextId === "test-turn") {
+        progressEvents.push(pkt);
+      }
+    });
+
+    // Send TTS audio - 80ms worth
+    const sampleCount = Math.floor(0.08 * 16000);
+    const audioSamples = new Int16Array(sampleCount).fill(1000);
+    const audioBytes = pcm16SamplesToBytes(audioSamples);
+
+    session!.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+      audio: audioBytes,
+      sampleRateHz: 16000,
+    });
+
+    session!.bus.push(Route.Main, {
+      kind: "tts.end",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+    });
+
+    // Wait for playout to complete
+    await waitMs(150);
+
+    socket.close();
+    removeProgressHandler();
+
+    // Should have received playout progress events
+    expect(progressEvents.length).toBeGreaterThan(0);
+
+    // Last event should be completion
+    const lastEvent = progressEvents[progressEvents.length - 1];
+    expect(lastEvent.complete).toBe(true);
+  });
+
+  it("handles interrupt.tts by clearing playout queue and sending audio_clear", async () => {
+    const httpServer = createServer();
+    activeHttpServers.push(httpServer);
+    
+    let session: VoiceAgentSession | null = null;
+    const server = await createVoiceWebSocketServer({
+      server: httpServer,
+      port: 0,
+      createSession: () => {
+        session = new VoiceAgentSession({ plugins: {} });
+        return session;
+      },
+      outboundFrameDurationMs: 20,
+    });
+    activeServers.push(server);
+
+    const port = (server.address() as any).port;
+    const socket = await openBrowserSocketReady(browserUrl(port));
+
+    // Session is already started by the websocket server
+
+    // Send a longer TTS audio burst
+    const sampleCount = Math.floor(0.2 * 16000); // 200ms
+    const audioSamples = new Int16Array(sampleCount).fill(1000);
+    const audioBytes = pcm16SamplesToBytes(audioSamples);
+
+    session!.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+      audio: audioBytes,
+      sampleRateHz: 16000,
+    });
+
+    // Wait a bit for some frames to be queued
+    await waitMs(10);
+
+    // Listen for audio_clear message
+    const audioClearPromise = readJsonMatching(socket, (m: any) => m.type === "audio_clear");
+
+    // Send interrupt
+    session!.bus.push(Route.Main, {
+      kind: "interrupt.tts",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+    });
+
+    const audioClear = await audioClearPromise;
+    socket.close();
+
+    expect((audioClear as any).type).toBe("audio_clear");
+    expect((audioClear as any).turnId).toBe("test-turn");
+    expect((audioClear as any).reason).toBe("barge_in");
+  });
+
+  it("respects custom outbound frame duration and queue limits", async () => {
+    const httpServer = createServer();
+    activeHttpServers.push(httpServer);
+    
+    let session: VoiceAgentSession | null = null;
+    const server = await createVoiceWebSocketServer({
+      server: httpServer,
+      port: 0,
+      createSession: () => {
+        session = new VoiceAgentSession({ plugins: {} });
+        return session;
+      },
+      outboundFrameDurationMs: 40, // Larger frames
+      maxQueuedOutputAudioMs: 100, // Small queue to trigger overflow
+    });
+    activeServers.push(server);
+
+    const port = (server.address() as any).port;
+    const socket = await openBrowserSocketReady(browserUrl(port));
+
+    // Session is already started by the websocket server
+
+    // Send large audio burst to trigger overflow
+    const sampleCount = Math.floor(1.0 * 16000); // 1 second
+    const audioSamples = new Int16Array(sampleCount).fill(1000);
+    const audioBytes = pcm16SamplesToBytes(audioSamples);
+
+    const ttsChunksPromise = collectMessagesMatching(
+      socket,
+      (m: any) => m.type === "tts_chunk",
+      200
+    );
+
+    session!.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "test-turn",
+      timestampMs: Date.now(),
+      audio: audioBytes,
+      sampleRateHz: 16000,
+    });
+
+    const ttsChunks = await ttsChunksPromise;
+    socket.close();
+
+    // Tail-drop overflow: the head of the burst (up to the 100ms cap) still
+    // plays out — a tiny cap must never silence the stream entirely.
+    expect(ttsChunks.length).toBeGreaterThan(0);
+    expect(ttsChunks.length).toBeLessThan(20);
+    const firstChunk = ttsChunks[0] as any;
+    expect(firstChunk.durationMs).toBeGreaterThan(0);
+  });
+
+  it("delivers a long reply in full under the default playout bound (no overflow)", async () => {
+    const httpServer = createServer();
+    activeHttpServers.push(httpServer);
+
+    let session: VoiceAgentSession | null = null;
+    const metrics: Array<{ name: string; value: string }> = [];
+    const server = await createVoiceWebSocketServer({
+      server: httpServer,
+      port: 0,
+      createSession: () => {
+        session = new VoiceAgentSession({ plugins: {} });
+        return session;
+      },
+    });
+    activeServers.push(server);
+
+    const port = (server.address() as any).port;
+    const socket = await openBrowserSocketReady(browserUrl(port));
+    session!.bus.on("metric.conversation", (pkt) => {
+      const metric = pkt as unknown as { name: string; value: string };
+      metrics.push(metric);
+    });
+
+    const ttsChunksPromise = collectMessagesMatching(
+      socket,
+      (m: any) => m.type === "tts_chunk",
+      1_200, // collect for the full paced second
+    );
+    // A 1s burst — far beyond the old 200ms cap that used to clear-and-stop.
+    session!.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "default-bound-turn",
+      timestampMs: Date.now(),
+      audio: pcm16SamplesToBytes(new Int16Array(16000)),
+      sampleRateHz: 16000,
+    });
+
+    const ttsChunks = await ttsChunksPromise;
+    socket.close();
+
+    expect(ttsChunks.length).toBeGreaterThanOrEqual(40); // ≥800ms of the reply paced out
+    expect(metrics.some((m) => m.name.includes("overflow"))).toBe(false);
+  });
+
+  it("allows long playout queues only through an explicit override", async () => {
+    const httpServer = createServer();
+    activeHttpServers.push(httpServer);
+
+    let session: VoiceAgentSession | null = null;
+    const server = await createVoiceWebSocketServer({
+      server: httpServer,
+      port: 0,
+      createSession: () => {
+        session = new VoiceAgentSession({ plugins: {} });
+        return session;
+      },
+      maxQueuedOutputAudioMs: 1000,
+    });
+    activeServers.push(server);
+
+    const port = (server.address() as any).port;
+    const socket = await openBrowserSocketReady(browserUrl(port));
+    let closed = false;
+    socket.once("close", () => {
+      closed = true;
+    });
+
+    const ttsChunksPromise = collectMessagesMatching(
+      socket,
+      (m: any) => m.type === "tts_chunk",
+      150,
+    );
+    session!.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "explicit-long-queue-turn",
+      timestampMs: Date.now(),
+      audio: pcm16SamplesToBytes(new Int16Array(6400)),
+      sampleRateHz: 16000,
+    });
+
+    const chunks = await ttsChunksPromise;
+    socket.close();
+
+    expect(chunks.length).toBeGreaterThan(0);
+    expect(closed).toBe(false);
+  });
+});

package/src/carrier-commands.test.ts

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: MIT
+//
+// Unit tests for pure carrier command constructors + mockable dispatch.
+// Live carrier HTTP is NOT exercised (no credentials).
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  buildTelnyxSendDtmf,
+  buildTelnyxTransfer,
+  buildTwilioSendDigits,
+  buildTwilioTransfer,
+  dispatchTelnyxCommand,
+  dispatchTwilioCommand,
+  resolveTransferSummary,
+  type FetchLike,
+} from "./carrier-commands.js";
+
+describe("buildTwilioSendDigits", () => {
+  it("maps digits + pause syntax into SendDigits and TwiML Play", () => {
+    const cmd = buildTwilioSendDigits("CAxxx", { digits: "1w2W9*#" });
+    expect(cmd.carrier).toBe("twilio");
+    expect(cmd.path).toBe("/Calls/CAxxx.json");
+    expect(cmd.form.SendDigits).toBe("1w2W9*#");
+    expect(cmd.twiml).toBe('<Response><Play digits="1w2W9*#"/></Response>');
+  });
+
+  it("URL-encodes call SID in the path", () => {
+    const cmd = buildTwilioSendDigits("CA/special", { digits: "0" });
+    expect(cmd.path).toBe("/Calls/CA%2Fspecial.json");
+  });
+});
+
+describe("buildTelnyxSendDtmf", () => {
+  it("builds Call Control send_dtmf payload with pause letters retained", () => {
+    const cmd = buildTelnyxSendDtmf("v3:abc", { digits: "9w0W#" }, { durationMillis: 250 });
+    expect(cmd.carrier).toBe("telnyx");
+    expect(cmd.path).toBe("/v2/calls/v3%3Aabc/actions/send_dtmf");
+    expect(cmd.json).toEqual({ digits: "9w0W#", duration_millis: 250 });
+  });
+});
+
+describe("buildTwilioTransfer", () => {
+  it("cold transfer emits Dial TwiML for E.164", () => {
+    const cmd = buildTwilioTransfer("CAcall", {
+      mode: "cold",
+      target: "+15551234567",
+    });
+    expect(cmd.twiml).toBe("<Response><Dial>+15551234567</Dial></Response>");
+    expect(cmd.form.Twiml).toContain("<Dial>");
+  });
+
+  it("warm transfer carries summary in a TwiML comment and command field", () => {
+    const cmd = buildTwilioTransfer("CAcall", {
+      mode: "warm",
+      target: "+15557654321",
+      summary: "Caller asked about billing",
+    });
+    expect(cmd.summary).toBe("Caller asked about billing");
+    expect(cmd.twiml).toContain("<!-- warm-handoff: Caller asked about billing -->");
+    expect(cmd.twiml).toContain("<Dial>+15557654321</Dial>");
+  });
+
+  it("sip_refer still uses Dial/Sip (not raw REFER) for answer-rate", () => {
+    const cmd = buildTwilioTransfer("CAcall", {
+      mode: "sip_refer",
+      target: "sip:agent@example.com",
+    });
+    expect(cmd.twiml).toBe("<Response><Dial><Sip>sip:agent@example.com</Sip></Dial></Response>");
+  });
+
+  it("redirectUrl mode posts Url instead of inline Twiml", () => {
+    const cmd = buildTwilioTransfer(
+      "CAcall",
+      { mode: "cold", target: "+15550001111" },
+      { redirectUrl: "https://example.com/twiml" },
+    );
+    expect(cmd.form).toEqual({ Url: "https://example.com/twiml", Method: "POST" });
+  });
+});
+
+describe("buildTelnyxTransfer", () => {
+  it("cold transfer posts to Call Control transfer action", () => {
+    const cmd = buildTelnyxTransfer("v3:id", { mode: "cold", target: "+15551234567" });
+    expect(cmd.path).toBe("/v2/calls/v3%3Aid/actions/transfer");
+    expect(cmd.json.to).toBe("+15551234567");
+    expect(cmd.json.client_state).toBeUndefined();
+  });
+
+  it("warm transfer encodes summary into client_state", () => {
+    const cmd = buildTelnyxTransfer("v3:id", {
+      mode: "warm",
+      target: "+15550001111",
+      summary: "Needs refund help",
+    });
+    expect(cmd.summary).toBe("Needs refund help");
+    expect(cmd.json.client_state).toBeTypeOf("string");
+    const raw = cmd.json.client_state!;
+    // base64url → standard base64 with correct padding
+    let b64 = raw.replace(/-/g, "+").replace(/_/g, "/");
+    while (b64.length % 4 !== 0) b64 += "=";
+    const json = JSON.parse(atob(b64)) as { summary: string; mode: string };
+    expect(json).toEqual({ summary: "Needs refund help", mode: "warm" });
+  });
+
+  it("sip_refer mode still uses transfer action with SIP URI as to", () => {
+    const cmd = buildTelnyxTransfer("v3:id", {
+      mode: "sip_refer",
+      target: "sip:desk@pbx.example",
+    });
+    expect(cmd.path).toContain("/actions/transfer");
+    expect(cmd.json.to).toBe("sip:desk@pbx.example");
+  });
+});
+
+describe("resolveTransferSummary (warm seam)", () => {
+  it("uses packet.summary when provided", async () => {
+    const summary = await resolveTransferSummary({
+      kind: "call.transfer",
+      contextId: "c1",
+      timestampMs: 1,
+      mode: "warm",
+      target: "+1",
+      summary: "from packet",
+    });
+    expect(summary).toBe("from packet");
+  });
+
+  it("calls injectable summarizer when warm and summary missing", async () => {
+    const summarizer = vi.fn(async () => "from seam");
+    const summary = await resolveTransferSummary(
+      {
+        kind: "call.transfer",
+        contextId: "c1",
+        timestampMs: 1,
+        mode: "warm",
+        target: "+1555",
+      },
+      summarizer,
+    );
+    expect(summarizer).toHaveBeenCalledWith({ contextId: "c1", target: "+1555" });
+    expect(summary).toBe("from seam");
+  });
+
+  it("does not call summarizer for cold transfer", async () => {
+    const summarizer = vi.fn(async () => "nope");
+    const summary = await resolveTransferSummary(
+      {
+        kind: "call.transfer",
+        contextId: "c1",
+        timestampMs: 1,
+        mode: "cold",
+        target: "+1555",
+      },
+      summarizer,
+    );
+    expect(summarizer).not.toHaveBeenCalled();
+    expect(summary).toBeUndefined();
+  });
+});
+
+describe("dispatch via fetch (mockable, no live carrier)", () => {
+  it("dispatchTwilioCommand posts form body with Basic auth", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchImpl: FetchLike = async (url, init) => {
+      calls.push({ url, init });
+      return new Response("{}", { status: 200 });
+    };
+    const cmd = buildTwilioSendDigits("CAsid", { digits: "12" });
+    await dispatchTwilioCommand(
+      { accountSid: "ACacct", authToken: "secret" },
+      cmd,
+      fetchImpl,
+    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toContain("/2010-04-01/Accounts/ACacct/Calls/CAsid.json");
+    expect(calls[0]!.init?.method).toBe("POST");
+    const headers = calls[0]!.init?.headers as Record<string, string>;
+    expect(headers.Authorization).toMatch(/^Basic /);
+    expect(headers["Content-Type"]).toBe("application/x-www-form-urlencoded");
+    expect(calls[0]!.init?.body).toBe("SendDigits=12");
+  });
+
+  it("dispatchTelnyxCommand posts JSON with Bearer auth", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchImpl: FetchLike = async (url, init) => {
+      calls.push({ url, init });
+      return new Response("{}", { status: 200 });
+    };
+    const cmd = buildTelnyxTransfer("v3:x", { mode: "cold", target: "+1555" });
+    await dispatchTelnyxCommand({ apiKey: "KEY" }, cmd, fetchImpl);
+    expect(calls[0]!.url).toBe("https://api.telnyx.com/v2/calls/v3%3Ax/actions/transfer");
+    expect(calls[0]!.init?.headers).toMatchObject({
+      Authorization: "Bearer KEY",
+      "Content-Type": "application/json",
+    });
+    expect(JSON.parse(String(calls[0]!.init?.body))).toEqual({ to: "+1555" });
+  });
+});