@vellumai/assistant 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/__tests__/media-stream-output.test.ts

@@ -4,15 +4,6 @@ import { afterEach, describe, expect, jest, mock, test } from "bun:test";
 // Module mocks
 // ---------------------------------------------------------------------------
 
-mock.module("../util/logger.js", () => ({
-  getLogger: () => ({
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    debug: () => {},
-  }),
-}));
-
 // Mock TTS provider for synthesis tests
 const mockSynthesize = jest.fn();
 const mockProvider = {
@@ -25,11 +16,14 @@ mock.module("../calls/resolve-call-tts-provider.js", () => ({
   resolveCallTtsProvider: jest.fn(() => ({
     provider: mockProvider,
     useSynthesizedPath: false,
-    audioFormat: "wav" as const,
+    audioFormat: "pcm" as const,
   })),
 }));
 
-import { mulawToPcm16 } from "../calls/media-stream-audio-transcode.js";
+import {
+  mulawToPcm16,
+  pcm16ToMulaw,
+} from "../calls/media-stream-audio-transcode.js";
 import { MediaStreamOutput } from "../calls/media-stream-output.js";
 import { resolveCallTtsProvider } from "../calls/resolve-call-tts-provider.js";
 
@@ -78,10 +72,22 @@ function createMockWs() {
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Wait for async playback queue to drain. */
-async function drain(): Promise<void> {
-  // Allow microtasks and the drain loop to run
-  await new Promise((resolve) => setTimeout(resolve, 10));
+/**
+ * Wait for async playback to progress. With `until`, polls (up to 2 s) for
+ * the condition so assertions don't race the queue on slow CI machines;
+ * without it, a single fixed tick (for negative assertions).
+ */
+async function drain(until?: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2000;
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    if (!until || until() || Date.now() > deadline) return;
+  }
+}
+
+/** Number of sent messages with the given event type. */
+function countEvents(sent: string[], event: string): number {
+  return sent.filter((s) => JSON.parse(s).event === event).length;
 }
 
 /** Generate a minimal valid WAV buffer with PCM data. */
@@ -144,6 +150,47 @@ function concatMulawPayloads(sent: string[]): Buffer {
   );
 }
 
+/** Encode samples as a raw PCM16 LE buffer. */
+function pcm16Buffer(samples: number[]): Buffer {
+  const buf = Buffer.alloc(samples.length * 2);
+  for (let i = 0; i < samples.length; i++) {
+    buf.writeInt16LE(samples[i], i * 2);
+  }
+  return buf;
+}
+
+/** Keep every other PCM16 sample (16 kHz -> 8 kHz decimation). */
+function decimateByTwo(pcm: Buffer): Buffer {
+  const outCount = Math.floor(pcm.length / 2 / 2);
+  const out = Buffer.alloc(outCount * 2);
+  for (let i = 0; i < outCount; i++) {
+    out.writeInt16LE(pcm.readInt16LE(i * 4), i * 2);
+  }
+  return out;
+}
+
+/** Outputs created during the current test, closed in afterEach. */
+const activeOutputs: MediaStreamOutput[] = [];
+
+/** Construct a MediaStreamOutput tracked for afterEach teardown. */
+function makeOutput(
+  ws: import("bun").ServerWebSocket<unknown>,
+  streamSid: string,
+): MediaStreamOutput {
+  const output = new MediaStreamOutput(ws, streamSid);
+  activeOutputs.push(output);
+  return output;
+}
+
+/** Install a resolveCallTtsProvider mock returning the given provider. */
+function useProvider(provider: unknown): void {
+  mockResolveCallTtsProvider.mockImplementation(() => ({
+    provider,
+    useSynthesizedPath: false,
+    audioFormat: "pcm" as const,
+  }));
+}
+
 /** Count sign changes in a PCM16 LE buffer (proxy for tone frequency). */
 function countZeroCrossings(pcm: Buffer): number {
   const samples = Math.floor(pcm.length / 2);
@@ -162,12 +209,19 @@ function countZeroCrossings(pcm: Buffer): number {
 // ---------------------------------------------------------------------------
 
 afterEach(() => {
+  // Close every output so an in-flight synthesize item from a slow test
+  // bails on its staleness check instead of calling the next test's
+  // (re-)mocked provider.
+  for (const output of activeOutputs) {
+    output.markClosed();
+  }
+  activeOutputs.length = 0;
   mockSynthesize.mockReset();
   // Restore the default resolveCallTtsProvider mock
   mockResolveCallTtsProvider.mockImplementation(() => ({
     provider: mockProvider,
     useSynthesizedPath: false,
-    audioFormat: "wav" as const,
+    audioFormat: "pcm" as const,
   }));
 });
 
@@ -185,11 +239,11 @@ describe("MediaStreamOutput", () => {
       });
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("hello ", false);
       output.sendTextToken("world", true);
 
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       // Should have sent media frames (from synthesis) and a mark
       const events = sent.map((s) => JSON.parse(s).event);
@@ -203,10 +257,10 @@ describe("MediaStreamOutput", () => {
 
     test("empty token with last: true sends only end-of-turn mark (no synthesis)", async () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("", true);
 
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       // Should send only a mark, no media frames
       expect(sent).toHaveLength(1);
@@ -220,7 +274,7 @@ describe("MediaStreamOutput", () => {
 
     test("non-last tokens accumulate without sending", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("hello ", false);
       output.sendTextToken("world ", false);
       expect(sent).toHaveLength(0);
@@ -228,7 +282,7 @@ describe("MediaStreamOutput", () => {
 
     test("does not send when closed", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.endSession();
       output.sendTextToken("hello", true);
       expect(sent).toHaveLength(0);
@@ -238,7 +292,7 @@ describe("MediaStreamOutput", () => {
   describe("CallTransport interface — sendPlayUrl", () => {
     test("enqueues a fetch-url item in the playback queue", () => {
       const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendPlayUrl("https://example.com/audio.mp3");
       // The queue should have one item (the fetch will fail since
       // there's no real server, but the enqueueing is synchronous)
@@ -247,7 +301,7 @@ describe("MediaStreamOutput", () => {
 
     test("does not enqueue when closed", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.endSession();
       output.sendPlayUrl("https://example.com/audio.mp3");
       expect(sent).toHaveLength(0);
@@ -257,7 +311,7 @@ describe("MediaStreamOutput", () => {
   describe("CallTransport interface — endSession", () => {
     test("closes the WebSocket with code 1000", () => {
       const mock = createMockWs();
-      const output = new MediaStreamOutput(mock.ws, "stream-1");
+      const output = makeOutput(mock.ws, "stream-1");
       output.endSession("test-reason");
       expect(mock.closed).toBe(true);
       expect(mock.closeCode).toBe(1000);
@@ -266,7 +320,7 @@ describe("MediaStreamOutput", () => {
 
     test("uses default reason when none provided", () => {
       const mock = createMockWs();
-      const output = new MediaStreamOutput(mock.ws, "stream-1");
+      const output = makeOutput(mock.ws, "stream-1");
       output.endSession();
       expect(mock.closed).toBe(true);
       expect(mock.closeReason).toBe("session-ended");
@@ -274,7 +328,7 @@ describe("MediaStreamOutput", () => {
 
     test("is idempotent", () => {
       const mock = createMockWs();
-      const output = new MediaStreamOutput(mock.ws, "stream-1");
+      const output = makeOutput(mock.ws, "stream-1");
       output.endSession("first");
       // Second call should not throw (ws.close would throw on already-closed)
       output.endSession("second");
@@ -285,7 +339,7 @@ describe("MediaStreamOutput", () => {
   describe("sendAudioPayload", () => {
     test("sends a media command with the base64 payload", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.sendAudioPayload("dGVzdA==");
 
       expect(sent).toHaveLength(1);
@@ -299,7 +353,7 @@ describe("MediaStreamOutput", () => {
 
     test("does not send when closed", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.endSession();
       output.sendAudioPayload("dGVzdA==");
       // Only the close would have happened, no media sent
@@ -310,7 +364,7 @@ describe("MediaStreamOutput", () => {
   describe("sendMark", () => {
     test("sends a mark command with the given name", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.sendMark("end-of-turn");
 
       expect(sent).toHaveLength(1);
@@ -324,7 +378,7 @@ describe("MediaStreamOutput", () => {
 
     test("does not send when closed", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.endSession();
       output.sendMark("end-of-turn");
       expect(sent).toHaveLength(0);
@@ -334,7 +388,7 @@ describe("MediaStreamOutput", () => {
   describe("clearAudio — barge-in", () => {
     test("sends a clear command to Twilio", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.clearAudio();
 
       expect(sent).toHaveLength(1);
@@ -359,7 +413,7 @@ describe("MediaStreamOutput", () => {
       );
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
 
       // Queue synthesis
       output.sendTextToken("hello world", true);
@@ -379,7 +433,7 @@ describe("MediaStreamOutput", () => {
 
     test("does not send when closed", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.endSession();
       output.clearAudio();
       expect(sent).toHaveLength(0);
@@ -389,7 +443,7 @@ describe("MediaStreamOutput", () => {
   describe("clearBufferedAudio — rejected barge-in", () => {
     test("sends a clear command to Twilio", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.clearBufferedAudio();
 
       expect(sent).toHaveLength(1);
@@ -413,12 +467,12 @@ describe("MediaStreamOutput", () => {
       );
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
 
       output.sendTextToken("hello world", true);
       output.clearBufferedAudio();
 
-      await new Promise((resolve) => setTimeout(resolve, 60));
+      await drain(() => countEvents(sent, "media") > 0);
 
       // Unlike clearAudio, the in-flight synthesis is not aborted:
       // its frames go out once ready.
@@ -439,7 +493,7 @@ describe("MediaStreamOutput", () => {
       );
 
       const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
 
       let fired = 0;
       output.setAudioStartCallback(() => {
@@ -448,20 +502,76 @@ describe("MediaStreamOutput", () => {
       output.sendTextToken("hello world", true);
       output.clearBufferedAudio();
 
-      await new Promise((resolve) => setTimeout(resolve, 60));
+      await drain(() => fired === 1);
 
       expect(fired).toBe(1);
     });
 
     test("does not send when closed", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "MZ-stream-1");
+      const output = makeOutput(ws, "MZ-stream-1");
       output.endSession();
       output.clearBufferedAudio();
       expect(sent).toHaveLength(0);
     });
   });
 
+  describe("cancelPendingSpeech — turn abort", () => {
+    test("queued-but-unplayed synthesis never produces frames; the next turn plays normally", async () => {
+      const wav = makeWavBuffer(sineSamples(400, 440, 8000));
+      // Slow synthesis so the abort lands while the first segment is
+      // in flight and the second is still queued.
+      mockSynthesize.mockImplementation(
+        () =>
+          new Promise((resolve) =>
+            setTimeout(
+              () => resolve({ audio: wav, contentType: "audio/wav" }),
+              200,
+            ),
+          ),
+      );
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "MZ-stream-1");
+
+      // Aborted turn: first segment in flight, second still queued.
+      output.sendTextToken("Sentence one. Sentence two.", true);
+      await drain(() => mockSynthesize.mock.calls.length === 1);
+      expect(output.getPlaybackQueueLength()).toBeGreaterThan(0);
+
+      output.cancelPendingSpeech();
+
+      // Twilio's buffered audio was flushed too.
+      expect(countEvents(sent, "clear")).toBe(1);
+
+      // Next turn: fast synthesis so its audio goes out.
+      mockSynthesize.mockResolvedValue({
+        audio: wav,
+        contentType: "audio/wav",
+      });
+      output.sendTextToken("Next turn reply.", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      // The aborted turn's queued segment never synthesized, its
+      // in-flight segment produced no frames, and the next turn's
+      // audio is the only audio sent.
+      const synthesizedTexts = mockSynthesize.mock.calls.map(
+        (c) => (c[0] as { text: string }).text,
+      );
+      expect(synthesizedTexts).toEqual(["Sentence one.", "Next turn reply."]);
+      expect(countEvents(sent, "media")).toBeGreaterThan(0);
+      expect(totalMulawBytes(sent)).toBe(400);
+    });
+
+    test("does not send when closed", () => {
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "MZ-stream-1");
+      output.endSession();
+      output.cancelPendingSpeech();
+      expect(sent).toHaveLength(0);
+    });
+  });
+
   describe("audio-start signal", () => {
     function makePlayableWav(): Buffer {
       const samples = Array.from({ length: 400 }, (_, i) =>
@@ -477,7 +587,7 @@ describe("MediaStreamOutput", () => {
       });
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
 
       let fired = 0;
       let mediaSentWhenFired = -1;
@@ -489,7 +599,7 @@ describe("MediaStreamOutput", () => {
       });
 
       output.sendTextToken("hello world", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       const mediaMessages = sent.filter((s) => JSON.parse(s).event === "media");
       expect(mediaMessages.length).toBeGreaterThan(1);
@@ -504,25 +614,25 @@ describe("MediaStreamOutput", () => {
         contentType: "audio/wav",
       });
 
-      const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
 
       let fired = 0;
       output.setAudioStartCallback(() => fired++);
 
       output.sendTextToken("first", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") >= 1);
       expect(fired).toBe(1);
 
       // Second item without re-arming — signal already consumed.
       output.sendTextToken("second", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") >= 2);
       expect(fired).toBe(1);
 
       // Re-armed — fires again for the next item.
       output.setAudioStartCallback(() => fired++);
       output.sendTextToken("third", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") >= 3);
       expect(fired).toBe(2);
     });
 
@@ -540,7 +650,7 @@ describe("MediaStreamOutput", () => {
       );
 
       const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
 
       let fired = 0;
       output.setAudioStartCallback(() => fired++);
@@ -553,14 +663,14 @@ describe("MediaStreamOutput", () => {
     });
 
     test("an empty end-of-turn (mark only) does not fire the signal", async () => {
-      const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
 
       let fired = 0;
       output.setAudioStartCallback(() => fired++);
 
       output.sendTextToken("", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
       expect(fired).toBe(0);
     });
   });
@@ -573,8 +683,8 @@ describe("MediaStreamOutput", () => {
         contentType: "audio/wav",
       });
 
-      const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
 
       // Tokens buffered mid-turn; a barge-in signal the controller ignores
       // (turn still processing) flushes queued audio but must not truncate
@@ -582,7 +692,7 @@ describe("MediaStreamOutput", () => {
       output.sendTextToken("hello ", false);
       output.clearAudio();
       output.sendTextToken("world", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       expect(mockSynthesize).toHaveBeenCalledTimes(1);
       expect(mockSynthesize.mock.calls[0][0].text).toBe("hello world");
@@ -590,12 +700,12 @@ describe("MediaStreamOutput", () => {
 
     test("discardPendingText drops accumulated text so no synthesis occurs", async () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
 
       output.sendTextToken("stale partial response", false);
       output.discardPendingText();
       output.sendTextToken("", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       expect(mockSynthesize).not.toHaveBeenCalled();
       // Only the end-of-turn mark goes out.
@@ -607,7 +717,7 @@ describe("MediaStreamOutput", () => {
   describe("setStreamSid / getStreamSid", () => {
     test("updates the stream SID used in subsequent commands", () => {
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "old-sid");
+      const output = makeOutput(ws, "old-sid");
       expect(output.getStreamSid()).toBe("old-sid");
 
       output.setStreamSid("new-sid");
@@ -622,7 +732,7 @@ describe("MediaStreamOutput", () => {
   describe("markClosed", () => {
     test("transitions to closed state without sending a close frame", () => {
       const mock = createMockWs();
-      const output = new MediaStreamOutput(mock.ws, "stream-1");
+      const output = makeOutput(mock.ws, "stream-1");
       output.markClosed();
       expect(mock.closed).toBe(false); // WebSocket not actually closed
       output.sendAudioPayload("dGVzdA=="); // Should be suppressed
@@ -639,7 +749,7 @@ describe("MediaStreamOutput", () => {
         close() {},
       } as unknown as import("bun").ServerWebSocket<unknown>;
 
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       // Should not throw
       expect(() => output.sendAudioPayload("dGVzdA==")).not.toThrow();
     });
@@ -652,7 +762,7 @@ describe("MediaStreamOutput", () => {
         },
       } as unknown as import("bun").ServerWebSocket<unknown>;
 
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       // Should not throw
       expect(() => output.endSession()).not.toThrow();
     });
@@ -671,10 +781,10 @@ describe("MediaStreamOutput", () => {
       });
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("test synthesis", true);
 
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       // Should have sent at least one media frame and an end-of-turn mark
       const mediaMessages = sent.filter((s) => JSON.parse(s).event === "media");
@@ -693,7 +803,7 @@ describe("MediaStreamOutput", () => {
 
     test("getPlaybackQueueLength reflects queue state", () => {
       const { ws } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       // Initially empty
       expect(output.getPlaybackQueueLength()).toBe(0);
     });
@@ -721,10 +831,10 @@ describe("MediaStreamOutput", () => {
       });
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("test", true);
 
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       // The audioBufferToFrames magic-byte detection should detect mp3
       // sync bytes when format is "wav" and return silence (no media
@@ -754,10 +864,10 @@ describe("MediaStreamOutput", () => {
       });
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("test", true);
 
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       // processSynthesizeItem derives actualFormat from content-type:
       // "audio/pcm" -> "pcm". audioBufferToFrames handles raw PCM by
@@ -789,10 +899,10 @@ describe("MediaStreamOutput", () => {
       });
 
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("test", true);
 
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
 
       // processSynthesizeItem detects "audio/x-raw" -> "pcm" format.
       // audioBufferToFrames converts raw PCM to mu-law frames.
@@ -818,9 +928,9 @@ describe("MediaStreamOutput", () => {
         contentType: "audio/wav",
       });
       const { ws, sent } = createMockWs();
-      const output = new MediaStreamOutput(ws, "stream-1");
+      const output = makeOutput(ws, "stream-1");
       output.sendTextToken("test", true);
-      await drain();
+      await drain(() => countEvents(sent, "mark") > 0);
       return sent;
     }
 
@@ -883,4 +993,578 @@ describe("MediaStreamOutput", () => {
       expect(totalMulawBytes(sent)).toBe(400);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Incremental sentence-bounded synthesis
+  // ---------------------------------------------------------------------------
+
+  describe("incremental sentence-bounded synthesis", () => {
+    test("complete sentences synthesize and play before last: true arrives", async () => {
+      const wav = makeWavBuffer(sineSamples(400, 440, 8000));
+      mockSynthesize.mockResolvedValue({
+        audio: wav,
+        contentType: "audio/wav",
+      });
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+
+      output.sendTextToken("First sentence. Sec", false);
+      await drain(() => countEvents(sent, "media") > 0);
+
+      // The completed first sentence synthesizes (and its frames go out)
+      // while the turn is still streaming.
+      expect(mockSynthesize).toHaveBeenCalledTimes(1);
+      expect(mockSynthesize.mock.calls[0][0].text).toBe("First sentence.");
+      expect(countEvents(sent, "media")).toBeGreaterThan(0);
+
+      output.sendTextToken("ond sentence.", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      expect(mockSynthesize).toHaveBeenCalledTimes(2);
+      expect(mockSynthesize.mock.calls[1][0].text).toBe("Second sentence.");
+    });
+
+    test("end-of-turn mark follows the final segment's frames", async () => {
+      const wav = makeWavBuffer(sineSamples(400, 440, 8000));
+      mockSynthesize.mockResolvedValue({
+        audio: wav,
+        contentType: "audio/wav",
+      });
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendTextToken("One. Two.", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      expect(mockSynthesize).toHaveBeenCalledTimes(2);
+      const events = sent.map((s) => JSON.parse(s).event);
+      const markIndex = events.indexOf("mark");
+      const lastMediaIndex = events.lastIndexOf("media");
+      expect(lastMediaIndex).toBeGreaterThanOrEqual(0);
+      expect(markIndex).toBeGreaterThan(lastMediaIndex);
+    });
+  });
+
+  describe("eager first segment", () => {
+    function usePlayableWav(): void {
+      mockSynthesize.mockResolvedValue({
+        audio: makeWavBuffer([1000, 2000, 3000, 4000]),
+        contentType: "audio/wav",
+      });
+    }
+
+    test("the turn's first segment synthesizes at a clause boundary before any sentence ends", async () => {
+      usePlayableWav();
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+
+      // No sentence has ended yet — full-sentence rules would still be
+      // buffering, but the clause-bounded prefix synthesizes immediately.
+      output.sendTextToken("Let me take a look at that, ", false);
+      await drain(() => mockSynthesize.mock.calls.length > 0);
+
+      expect(mockSynthesize).toHaveBeenCalledTimes(1);
+      expect(mockSynthesize.mock.calls[0][0].text).toBe(
+        "Let me take a look at that,",
+      );
+
+      output.sendTextToken("and get right back to you.", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      expect(mockSynthesize).toHaveBeenCalledTimes(2);
+      expect(mockSynthesize.mock.calls[1][0].text).toBe(
+        "and get right back to you.",
+      );
+    });
+
+    test("eager mode applies only to the first segment — later clauses wait for sentence ends", async () => {
+      usePlayableWav();
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+
+      output.sendTextToken(
+        "Let me take a look at that, and then, after checking, I will confirm.",
+        false,
+      );
+      output.sendTextToken("", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      expect(mockSynthesize.mock.calls.map((c) => c[0].text)).toEqual([
+        "Let me take a look at that,",
+        "and then, after checking, I will confirm.",
+      ]);
+    });
+
+    test("a long unpunctuated opening flushes at the eager 60-char cap", async () => {
+      usePlayableWav();
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+
+      // 69 chars, no punctuation: below the default 180-char cap but past
+      // the eager 60-char cap, so the opening splits at the last whitespace
+      // under 60 chars.
+      output.sendTextToken(
+        "The quick brown fox jumps over the lazy dog near the quiet river bank",
+        false,
+      );
+      await drain(() => mockSynthesize.mock.calls.length > 0);
+
+      expect(mockSynthesize).toHaveBeenCalledTimes(1);
+      expect(mockSynthesize.mock.calls[0][0].text).toBe(
+        "The quick brown fox jumps over the lazy dog near the quiet",
+      );
+
+      output.sendTextToken("", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      // The short remainder never reaches a boundary and force-flushes on
+      // last: true.
+      expect(mockSynthesize).toHaveBeenCalledTimes(2);
+      expect(mockSynthesize.mock.calls[1][0].text).toBe("river bank");
+    });
+
+    test("the next turn's first segment is eager again", async () => {
+      usePlayableWav();
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+
+      output.sendTextToken("Let me take a look at that, one moment.", true);
+      await drain(() => countEvents(sent, "mark") >= 1);
+
+      output.sendTextToken("Here is the second answer, coming right up.", true);
+      await drain(() => countEvents(sent, "mark") >= 2);
+
+      expect(mockSynthesize.mock.calls.map((c) => c[0].text)).toEqual([
+        "Let me take a look at that,",
+        "one moment.",
+        "Here is the second answer,",
+        "coming right up.",
+      ]);
+    });
+
+    test("discardPendingText re-arms eager segmentation for the next turn", async () => {
+      usePlayableWav();
+      const { ws } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+
+      output.sendTextToken("Let me take a look at that, plus extra", false);
+      await drain(() => mockSynthesize.mock.calls.length > 0);
+
+      // Turn aborted: the unsegmented remainder is dropped and the next
+      // turn's first segment is eager again.
+      output.discardPendingText();
+      output.sendTextToken("Here is the second answer, plus more", false);
+      await drain(() => mockSynthesize.mock.calls.length > 1);
+
+      expect(mockSynthesize.mock.calls.map((c) => c[0].text)).toEqual([
+        "Let me take a look at that,",
+        "Here is the second answer,",
+      ]);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Streaming PCM synthesis (incremental transcode)
+  // ---------------------------------------------------------------------------
+
+  describe("streaming PCM synthesis", () => {
+    test("frames are sent before the provider stream completes", async () => {
+      let releaseStream!: () => void;
+      const gate = new Promise<void>((resolve) => {
+        releaseStream = resolve;
+      });
+      // 640 samples at 16 kHz -> 320 samples at 8 kHz = two whole frames.
+      const chunk = pcm16Buffer(sineSamples(640, 440, 16000));
+      useProvider({
+        id: "streaming-pcm",
+        capabilities: { supportsStreaming: true, supportedFormats: ["pcm"] },
+        synthesize: jest.fn(),
+        async synthesizeStream(
+          _request: unknown,
+          onChunk: (c: Uint8Array) => void,
+        ) {
+          onChunk(chunk);
+          await gate;
+          onChunk(chunk);
+          return {
+            audio: Buffer.concat([chunk, chunk]),
+            contentType: "audio/pcm",
+          };
+        },
+      });
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendTextToken("Hello there.", true);
+      await drain(() => countEvents(sent, "media") >= 2);
+
+      // First chunk's frames went out while the stream is still open,
+      // and the end-of-turn mark has not been sent yet.
+      const framesBefore = countEvents(sent, "media");
+      expect(framesBefore).toBe(2);
+      expect(sent.some((s) => JSON.parse(s).event === "mark")).toBe(false);
+
+      releaseStream();
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      expect(countEvents(sent, "media")).toBe(4);
+      expect(sent.some((s) => JSON.parse(s).event === "mark")).toBe(true);
+    });
+
+    test("odd-byte and partial-frame chunk boundaries produce well-formed frames", async () => {
+      // 800 samples at 16 kHz (1600 bytes), split at deliberately awkward
+      // boundaries: odd bytes, non-frame-aligned sizes.
+      const full = pcm16Buffer(sineSamples(800, 440, 16000));
+      const cuts = [0, 3, 251, 640, 1001, full.length];
+      const chunks = cuts
+        .slice(0, -1)
+        .map((start, i) => full.subarray(start, cuts[i + 1]));
+      useProvider({
+        id: "streaming-pcm",
+        capabilities: { supportsStreaming: true, supportedFormats: ["pcm"] },
+        synthesize: jest.fn(),
+        async synthesizeStream(
+          _request: unknown,
+          onChunk: (c: Uint8Array) => void,
+        ) {
+          for (const c of chunks) {
+            onChunk(c);
+          }
+          return { audio: full, contentType: "audio/pcm" };
+        },
+      });
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendTextToken("Test.", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      // The concatenated mu-law output must be byte-identical to a
+      // whole-buffer transcode: no dropped or torn samples at chunk seams.
+      const expected = pcm16ToMulaw(decimateByTwo(full));
+      expect(expected.length).toBe(400);
+      expect(concatMulawPayloads(sent).equals(expected)).toBe(true);
+    });
+
+    test("playbackVersion bump mid-stream stops further frames", async () => {
+      let releaseStream!: () => void;
+      const gate = new Promise<void>((resolve) => {
+        releaseStream = resolve;
+      });
+      const chunk = pcm16Buffer(sineSamples(640, 440, 16000));
+      useProvider({
+        id: "streaming-pcm",
+        capabilities: { supportsStreaming: true, supportedFormats: ["pcm"] },
+        synthesize: jest.fn(),
+        async synthesizeStream(
+          _request: unknown,
+          onChunk: (c: Uint8Array) => void,
+        ) {
+          onChunk(chunk);
+          await gate;
+          // Stale chunk emitted after barge-in must never become frames.
+          onChunk(chunk);
+          return {
+            audio: Buffer.concat([chunk, chunk]),
+            contentType: "audio/pcm",
+          };
+        },
+      });
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendTextToken("Hello there.", true);
+      await drain(() => countEvents(sent, "media") > 0);
+
+      const framesBefore = countEvents(sent, "media");
+      expect(framesBefore).toBeGreaterThan(0);
+
+      output.clearAudio();
+      releaseStream();
+      await drain();
+
+      expect(countEvents(sent, "media")).toBe(framesBefore);
+    });
+
+    test("streaming provider without PCM support falls back to the whole-buffer path", async () => {
+      const wav = makeWavBuffer(sineSamples(400, 440, 8000));
+      const half = Math.floor(wav.length / 2);
+      let midStreamFrames = -1;
+      const sentRef: { sent: string[] } = { sent: [] };
+      useProvider({
+        id: "streaming-wav",
+        capabilities: { supportsStreaming: true, supportedFormats: ["wav"] },
+        synthesize: jest.fn(),
+        async synthesizeStream(
+          _request: unknown,
+          onChunk: (c: Uint8Array) => void,
+        ) {
+          onChunk(wav.subarray(0, half));
+          await new Promise((resolve) => setTimeout(resolve, 5));
+          midStreamFrames = countEvents(sentRef.sent, "media");
+          onChunk(wav.subarray(half));
+          return { audio: wav, contentType: "audio/wav" };
+        },
+      });
+
+      const { ws, sent } = createMockWs();
+      sentRef.sent = sent;
+      const output = makeOutput(ws, "stream-1");
+      output.sendTextToken("Hello.", true);
+      await drain(() => countEvents(sent, "mark") > 0);
+
+      // Nothing streamed mid-flight; the whole accumulated WAV is
+      // transcoded once at the end.
+      expect(midStreamFrames).toBe(0);
+      expect(totalMulawBytes(sent)).toBe(400);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Streaming play-URL playback (processFetchUrlItem)
+  // ---------------------------------------------------------------------------
+
+  describe("sendPlayUrl streaming", () => {
+    const originalFetch = globalThis.fetch;
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+    });
+
+    /** Mock global fetch to resolve with the given response for any URL. */
+    function mockFetch(response: Response): void {
+      globalThis.fetch = (async () => response) as unknown as typeof fetch;
+    }
+
+    /**
+     * A fetch response whose body is a manually driven stream, so tests
+     * control exactly when bytes arrive and when the body completes.
+     * `arrayBuffer()` throws: the streaming path must never buffer the
+     * response wholesale.
+     */
+    function fakeStreamingResponse(contentType: string): {
+      response: Response;
+      push: (bytes: Buffer) => void;
+      close: () => void;
+      cancelled: () => boolean;
+    } {
+      let controller!: ReadableStreamDefaultController<Uint8Array>;
+      let cancelled = false;
+      const stream = new ReadableStream<Uint8Array>({
+        start(c) {
+          controller = c;
+        },
+        cancel() {
+          cancelled = true;
+        },
+      });
+      const response = {
+        ok: true,
+        headers: new Headers({ "content-type": contentType }),
+        body: stream,
+        arrayBuffer: () => {
+          throw new Error(
+            "arrayBuffer must not be called on the streaming path",
+          );
+        },
+      } as unknown as Response;
+      return {
+        response,
+        push: (bytes) => {
+          try {
+            controller.enqueue(new Uint8Array(bytes));
+          } catch {
+            // Stream already cancelled/closed — stale producer push.
+          }
+        },
+        close: () => {
+          try {
+            controller.close();
+          } catch {
+            // Already cancelled.
+          }
+        },
+        cancelled: () => cancelled,
+      };
+    }
+
+    test("WAV play-URL frames go out before the response stream completes", async () => {
+      // 1280 samples at 16 kHz -> 640 at 8 kHz = four whole frames.
+      const wav = makeWavBuffer(sineSamples(1280, 440, 16000), {
+        sampleRate: 16000,
+      });
+      // Header + 320 samples: exactly one 20 ms frame after 2x decimation.
+      const firstPart = wav.subarray(0, 44 + 320 * 2);
+      const rest = wav.subarray(44 + 320 * 2);
+
+      const fake = fakeStreamingResponse("audio/wav");
+      mockFetch(fake.response);
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendPlayUrl("http://127.0.0.1/audio/test.wav");
+
+      fake.push(firstPart);
+      await drain(() => countEvents(sent, "media") >= 1);
+
+      // The first frame went out while the body is still open.
+      expect(countEvents(sent, "media")).toBe(1);
+
+      fake.push(rest);
+      fake.close();
+      await drain(() => countEvents(sent, "media") >= 4);
+
+      // Byte-identical to the whole-buffer transcode.
+      const expected = pcm16ToMulaw(decimateByTwo(wav.subarray(44)));
+      expect(concatMulawPayloads(sent).equals(expected)).toBe(true);
+    });
+
+    test("audio/pcm play-URL streams raw PCM incrementally", async () => {
+      const pcm = pcm16Buffer(sineSamples(1280, 440, 16000));
+      const fake = fakeStreamingResponse("audio/pcm");
+      mockFetch(fake.response);
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendPlayUrl("http://127.0.0.1/audio/test.pcm");
+
+      fake.push(pcm.subarray(0, 320 * 2)); // 320 samples -> one whole frame
+      await drain(() => countEvents(sent, "media") >= 1);
+      expect(countEvents(sent, "media")).toBe(1);
+
+      fake.push(pcm.subarray(320 * 2));
+      fake.close();
+      await drain(() => countEvents(sent, "media") >= 4);
+
+      const expected = pcm16ToMulaw(decimateByTwo(pcm));
+      expect(concatMulawPayloads(sent).equals(expected)).toBe(true);
+    });
+
+    test("clearAudio mid-stream cancels the body read and sends clear", async () => {
+      const wav = makeWavBuffer(sineSamples(1280, 440, 16000), {
+        sampleRate: 16000,
+      });
+      const fake = fakeStreamingResponse("audio/wav");
+      mockFetch(fake.response);
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendPlayUrl("http://127.0.0.1/audio/test.wav");
+
+      fake.push(wav.subarray(0, 44 + 320 * 2));
+      await drain(() => countEvents(sent, "media") >= 1);
+      const framesBefore = countEvents(sent, "media");
+      expect(framesBefore).toBeGreaterThan(0);
+
+      output.clearAudio();
+      await drain(() => fake.cancelled());
+
+      // The in-flight body read was cancelled and Twilio's buffer cleared.
+      expect(fake.cancelled()).toBe(true);
+      expect(countEvents(sent, "clear")).toBe(1);
+
+      // Bytes arriving after the abort never become frames.
+      fake.push(wav.subarray(44 + 320 * 2));
+      await drain();
+      expect(countEvents(sent, "media")).toBe(framesBefore);
+    });
+
+    test("audio/mpeg keeps the whole-buffer path (no body streaming)", async () => {
+      const mp3Bytes = Buffer.alloc(256, 0x80);
+      mp3Bytes[0] = 0xff; // MPEG sync
+      mp3Bytes[1] = 0xfb; // MPEG Layer 3
+
+      let bodyAccessed = false;
+      let arrayBufferCalled = false;
+      const response = {
+        ok: true,
+        headers: new Headers({ "content-type": "audio/mpeg" }),
+        get body(): ReadableStream<Uint8Array> {
+          bodyAccessed = true;
+          throw new Error("body must not be streamed for compressed formats");
+        },
+        arrayBuffer: async () => {
+          arrayBufferCalled = true;
+          return mp3Bytes.buffer.slice(
+            mp3Bytes.byteOffset,
+            mp3Bytes.byteOffset + mp3Bytes.byteLength,
+          );
+        },
+      } as unknown as Response;
+      mockFetch(response);
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendPlayUrl("http://127.0.0.1/audio/test.mp3");
+
+      await drain(() => arrayBufferCalled);
+
+      expect(arrayBufferCalled).toBe(true);
+      expect(bodyAccessed).toBe(false);
+      // mp3 cannot be transcoded in this path, so no media frames go out.
+      expect(countEvents(sent, "media")).toBe(0);
+    });
+
+    test("non-canonical WAV (stereo) falls back to the whole-buffer path", async () => {
+      // Stereo is not streamable; the buffered path keeps the left channel.
+      const left = sineSamples(400, 440, 8000);
+      const interleaved: number[] = [];
+      for (const s of left) {
+        interleaved.push(s, -s);
+      }
+      const wav = makeWavBuffer(interleaved, { sampleRate: 8000, channels: 2 });
+
+      const fake = fakeStreamingResponse("audio/wav");
+      mockFetch(fake.response);
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendPlayUrl("http://127.0.0.1/audio/stereo.wav");
+
+      fake.push(wav.subarray(0, 100));
+      // No frames while the fallback drains the body.
+      await drain();
+      expect(countEvents(sent, "media")).toBe(0);
+
+      fake.push(wav.subarray(100));
+      fake.close();
+      await drain(() => countEvents(sent, "media") > 0);
+
+      // Left channel of 400 pairs at 8 kHz -> 400 mu-law bytes.
+      expect(totalMulawBytes(sent)).toBe(400);
+    });
+
+    test("malformed WAV header falls back without throwing", async () => {
+      // RIFF magic but garbage after it: not streamable, and the buffered
+      // path's fixed-offset reads produce no usable frames.
+      const junk = Buffer.alloc(64, 0x42);
+      junk.write("RIFF", 0);
+
+      const fake = fakeStreamingResponse("audio/wav");
+      mockFetch(fake.response);
+
+      const { ws, sent } = createMockWs();
+      const output = makeOutput(ws, "stream-1");
+      output.sendPlayUrl("http://127.0.0.1/audio/junk.wav");
+
+      fake.push(junk);
+      fake.close();
+      await drain(() => output.getPlaybackQueueLength() === 0);
+      await drain();
+
+      // No crash; a malformed WAV yields no usable frames from the
+      // buffered transcode's fixed-offset reads.
+      expect(countEvents(sent, "media")).toBe(0);
+
+      // The output still works for a subsequent playable item.
+      const good = fakeStreamingResponse("audio/pcm");
+      mockFetch(good.response);
+      output.sendPlayUrl("http://127.0.0.1/audio/good.pcm");
+      good.push(pcm16Buffer(sineSamples(320, 440, 16000)));
+      good.close();
+      await drain(() => countEvents(sent, "media") > 0);
+      expect(countEvents(sent, "media")).toBe(1);
+    });
+  });
 });