@kuralle-syrinx/deepgram 4.4.0 → 4.5.0

package/src/stt.test.ts

@@ -0,0 +1,1784 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, describe, expect, it } from "vitest";
+import { WebSocketServer, type WebSocket } from "ws";
+import {
+  PipelineBusImpl,
+  Route,
+  type ConversationMetricPacket,
+  type SttErrorPacket,
+  type SttInterimPacket,
+  type SttPartialPacket,
+  type SttResultPacket,
+  type UsageRecordedPacket,
+} from "@kuralle-syrinx/core";
+
+import { DeepgramSTTPlugin } from "./stt.js";
+
+let servers: WebSocketServer[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          for (const client of server.clients) client.terminate();
+          server.close(() => resolve());
+        }),
+    ),
+  );
+});
+
+async function createLocalServer(onConnection: (socket: WebSocket) => void): Promise<string> {
+  const server = await new Promise<WebSocketServer>((resolve) => {
+    let nextServer: WebSocketServer;
+    nextServer = new WebSocketServer({ port: 0 }, () => {
+      resolve(nextServer);
+    });
+  });
+  servers.push(server);
+  server.on("connection", onConnection);
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+  return `ws://127.0.0.1:${address.port}/listen`;
+}
+
+function startBus(bus: PipelineBusImpl): Promise<void> {
+  return bus.start();
+}
+
+async function waitFor<T>(items: T[], count = 1): Promise<void> {
+  for (let i = 0; i < 50; i += 1) {
+    if (items.length >= count) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+async function waitForValue<T>(items: T[], value: T): Promise<void> {
+  for (let i = 0; i < 50; i += 1) {
+    if (items.includes(value)) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+describe("DeepgramSTTPlugin", () => {
+  it("emits stt.partial with word timings alongside unchanged stt.interim", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: false,
+          channel: {
+            alternatives: [{
+              transcript: "hello there",
+              confidence: 0.91,
+              words: [
+                { word: "hello", start: 0.12, end: 0.48, confidence: 0.95 },
+                { word: "there", start: 0.5, end: 0.82, confidence: 0.88 },
+              ],
+            }],
+          },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const interims: SttInterimPacket[] = [];
+    const partials: SttPartialPacket[] = [];
+    bus.on("stt.interim", (pkt) => {
+      interims.push(pkt as SttInterimPacket);
+    });
+    bus.on("stt.partial", (pkt) => {
+      partials.push(pkt as SttPartialPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await waitFor(partials);
+
+    expect(interims).toEqual([
+      expect.objectContaining({ kind: "stt.interim", contextId: "turn-1", text: "hello there" }),
+    ]);
+    expect(partials).toEqual([
+      expect.objectContaining({
+        kind: "stt.partial",
+        contextId: "turn-1",
+        text: "hello there",
+        wordTimings: [
+          { word: "hello", startMs: 120, endMs: 480, confidence: 0.95 },
+          { word: "there", startMs: 500, endMs: 820, confidence: 0.88 },
+        ],
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("uses provider KeepAlive while idle and CloseStream on shutdown", async () => {
+    const controlMessages: string[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) return;
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type) controlMessages.push(msg.type);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      keep_alive_interval_ms: 10,
+    });
+    await waitFor(controlMessages);
+    await plugin.close();
+    await waitForValue(controlMessages, "CloseStream");
+    bus.stop();
+    await started;
+
+    expect(controlMessages).toContain("KeepAlive");
+    expect(controlMessages.at(-1)).toBe("CloseStream");
+  });
+
+  it("emits provider-final segments immediately while still allowing explicit finalization", async () => {
+    let finalizeMessages = 0;
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: true,
+            channel: { alternatives: [{ transcript: "premature", confidence: 0.8 }] },
+          }));
+          return;
+        }
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type !== "Finalize") return;
+        finalizeMessages += 1;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: false,
+          channel: { alternatives: [{ transcript: "partial", confidence: 0.7 }] },
+        }));
+        setTimeout(() => {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            from_finalize: true,
+            channel: { alternatives: [{ transcript: "confirmed", confidence: 0.95 }] },
+          }));
+        }, 5);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 0,
+      emit_eos_on_final: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(finals).toEqual([
+      expect.objectContaining({
+        kind: "stt.result",
+        contextId: "turn-1",
+        text: "premature",
+        confidence: 0.8,
+      }),
+    ]);
+
+    plugin.forceFinalize("turn-1");
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(finals).toEqual([
+      expect.objectContaining({ contextId: "turn-1", text: "premature", confidence: 0.8 }),
+      expect.objectContaining({ contextId: "turn-1", text: "partial", confidence: 0.7 }),
+      expect.objectContaining({ contextId: "turn-1", text: "confirmed", confidence: 0.95 }),
+    ]);
+    expect(finalizeMessages).toBe(1);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_finalize_requested",
+        contextId: "turn-1",
+        value: expect.stringContaining("\"bytes\":640"),
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("completes a wedged turn via UtteranceEnd when speech_final never fires (noisy-line backstop)", async () => {
+    // A noisy/continuous line: Deepgram sends an is_final segment but never
+    // speech_final. UtteranceEnd (gap-based) must complete the turn so it can't wedge.
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false, // never speech_final on this noisy line
+            channel: { alternatives: [{ transcript: "book a room", confidence: 0.9 }] },
+          }));
+          setTimeout(() => socket.send(JSON.stringify({ type: "UtteranceEnd", last_word_end: 1.2 })), 5);
+          return;
+        }
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const turnCompletes: Array<{ text: string; contextId: string }> = [];
+    bus.on("eos.turn_complete", (pkt) => {
+      const p = pkt as unknown as { text: string; contextId: string };
+      turnCompletes.push({ text: p.text, contextId: p.contextId });
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      utterance_end_ms: 1000,
+    });
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-1", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    expect(turnCompletes).toEqual([{ text: "book a room", contextId: "turn-1" }]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits usage.recorded with stage stt and audioSeconds when a turn completes", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: true,
+          channel: { alternatives: [{ transcript: "hello", confidence: 0.95 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+
+    // 640 bytes pcm_s16le @ 16kHz = 640 / 2 / 16000 = 0.02 s
+    const audio = new Uint8Array(640);
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      model: "nova-3",
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-usage",
+      timestampMs: Date.now(),
+      audio,
+    });
+    await waitFor(usage);
+
+    expect(usage).toEqual([
+      expect.objectContaining({
+        kind: "usage.recorded",
+        contextId: "turn-usage",
+        stage: "stt",
+        provider: "deepgram",
+        model: "nova-3",
+        audioSeconds: 0.02,
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits usage.recorded even under smart-turn endpointing (emit_eos_on_final=false, no speech_final)", async () => {
+    // Regression: the flagship cascade sets endpointingOwner=smart_turn / emit_eos_on_final=false,
+    // so Deepgram never calls pushTurnComplete/pushFinal — the final goes out via pushResult alone.
+    // Billing hooked only on the turn-complete methods silently no-ops in this (production) mode.
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: false,
+          channel: { alternatives: [{ transcript: "account number please", confidence: 0.95 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+
+    const audio = new Uint8Array(640); // 0.02s @ 16kHz pcm_s16le
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      model: "nova-3",
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-smartturn",
+      timestampMs: Date.now(),
+      audio,
+    });
+    await waitFor(usage);
+
+    expect(usage).toEqual([
+      expect.objectContaining({
+        kind: "usage.recorded",
+        contextId: "turn-smartturn",
+        stage: "stt",
+        provider: "deepgram",
+        model: "nova-3",
+        audioSeconds: 0.02,
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("bills each is_final segment's audio delta once (multi-segment turn sums, no double-count)", async () => {
+    // Two is_final segments in one turn: usage must sum the per-segment audio deltas, not
+    // re-bill the running total each time.
+    let sent = 0;
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) return;
+        sent += 1;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: false,
+          channel: { alternatives: [{ transcript: sent === 1 ? "one" : "one two", confidence: 0.9 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      model: "nova-3",
+      emit_eos_on_final: false,
+    });
+    // 320 bytes then another 320 bytes = 0.01s + 0.01s = 0.02s total.
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-multi", timestampMs: Date.now(), audio: new Uint8Array(320) });
+    await waitFor(usage);
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-multi", timestampMs: Date.now(), audio: new Uint8Array(320) });
+    await waitFor(usage, 2);
+
+    const total = usage.reduce((sum, u) => sum + (u.audioSeconds ?? 0), 0);
+    expect(total).toBeCloseTo(0.02, 6);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits trailing provider-final segments after Pipecat requests finalize", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            channel: { alternatives: [{ transcript: "first phrase", confidence: 0.8 }] },
+          }));
+          return;
+        }
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type !== "Finalize") return;
+        setTimeout(() => {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: true,
+            channel: { alternatives: [{ transcript: "trailing phrase", confidence: 0.9 }] },
+          }));
+        }, 10);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 100,
+      emit_eos_on_final: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-2",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await waitFor(finals, 1);
+    expect(finals).toEqual([
+      expect.objectContaining({
+        contextId: "turn-2",
+        text: "first phrase",
+        confidence: 0.8,
+      }),
+    ]);
+
+    plugin.forceFinalize("turn-2");
+    await waitFor(finals, 2);
+    expect(finals).toEqual([
+      expect.objectContaining({
+        contextId: "turn-2",
+        text: "first phrase",
+        confidence: 0.8,
+      }),
+      expect.objectContaining({
+        contextId: "turn-2",
+        text: "trailing phrase",
+        confidence: 0.9,
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("turns malformed provider messages into STT errors instead of dropping them", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (_data, isBinary) => {
+        if (isBinary) socket.send("{not-json");
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-malformed",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+
+    await waitFor(errors);
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "stt.error",
+        contextId: "turn-malformed",
+        component: "stt",
+        isRecoverable: false,
+        cause: expect.objectContaining({
+          message: expect.stringContaining("Deepgram STT provider sent malformed JSON"),
+        }),
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("surfaces Deepgram provider error frames as STT errors", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (_data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          type: "Error",
+          code: "FAILED_TO_START_LISTENING",
+          description: "Failed to open the listen connection.",
+          request_id: "req-1",
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-provider-error",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+
+    await waitFor(errors);
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "stt.error",
+        contextId: "turn-provider-error",
+        component: "stt",
+        cause: expect.objectContaining({
+          message: expect.stringContaining("FAILED_TO_START_LISTENING"),
+        }),
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("surfaces unexpected Deepgram websocket close frames as STT errors", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (_data, isBinary) => {
+        if (isBinary) socket.close(1011, "NET-0000");
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-close",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+
+    await waitFor(errors);
+    expect(errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        kind: "stt.error",
+        contextId: "turn-close",
+        component: "stt",
+        isRecoverable: true,
+        cause: expect.objectContaining({
+          message: expect.stringContaining("code=1011 reason=NET-0000"),
+        }),
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("discards unconfirmed provider transcript state across recoverable websocket reconnect", async () => {
+    const connections: WebSocket[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      connections.push(socket);
+      if (connections.length === 1) {
+        socket.on("message", (_data, isBinary) => {
+          if (!isBinary) return;
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            channel: { alternatives: [{ transcript: "stale pre reconnect", confidence: 0.8 }] },
+          }));
+          socket.close(1011, "NET-0000");
+        });
+        return;
+      }
+      socket.on("message", (_data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: true,
+          channel: { alternatives: [{ transcript: "fresh after reconnect", confidence: 0.9 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-before-reconnect",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await waitFor(connections, 2);
+
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-after-reconnect",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await waitFor(finals, 2);
+
+    expect(finals).toEqual([
+      expect.objectContaining({
+        contextId: "turn-before-reconnect",
+        text: "stale pre reconnect",
+      }),
+      expect.objectContaining({
+        contextId: "turn-after-reconnect",
+        text: "fresh after reconnect",
+      }),
+    ]);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_reconnect_discarded_state",
+        contextId: "turn-before-reconnect",
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("does not bill usage when no audio was successfully sent before finalize", async () => {
+    // No audio frames are delivered; finalize should still request provider Finalize with
+    // zero recorded audio-stats bytes (metrics), and no usage.recorded.
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", () => {
+        // swallow Finalize — no provider confirmation needed for this metric assertion
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const usage: UsageRecordedPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      provider_finalize_timeout_ms: 0,
+      emit_eos_on_final: false,
+    });
+    // Establish context without audio (turn.change only).
+    bus.push(Route.Main, {
+      kind: "turn.change",
+      contextId: "turn-unsent",
+      timestampMs: Date.now(),
+    });
+    plugin.forceFinalize("turn-unsent");
+    await waitFor(metrics);
+
+    expect(usage).toHaveLength(0);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_finalize_requested",
+        contextId: "turn-unsent",
+        value: expect.stringContaining("\"bytes\":0"),
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("times out interim-only provider text when Finalize is not confirmed", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: false,
+            speech_final: false,
+            channel: { alternatives: [{ transcript: "unconfirmed segment", confidence: 0.8 }] },
+          }));
+          return;
+        }
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type !== "Finalize") return;
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 10,
+      emit_eos_on_final: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-unconfirmed",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    plugin.forceFinalize("turn-unconfirmed");
+    await waitFor(errors);
+
+    expect(finals).toHaveLength(0);
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "stt.error",
+        contextId: "turn-unconfirmed",
+        isRecoverable: true,
+        cause: expect.objectContaining({
+          message: "Deepgram STT Finalize timed out before speech_final/from_finalize confirmation",
+        }),
+      }),
+    ]);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_finalize_timeout",
+        contextId: "turn-unconfirmed",
+        value: expect.stringContaining("\"bytes\":640"),
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits provider is_final text without waiting for speech_final or explicit Finalize confirmation", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (_data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: false,
+          channel: { alternatives: [{ transcript: "released provider text", confidence: 0.87 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("stt.result", (pkt) => { finals.push(pkt as SttResultPacket); });
+    bus.on("stt.error", (pkt) => { errors.push(pkt as SttErrorPacket); });
+    bus.on("metric.conversation", (pkt) => { metrics.push(pkt as ConversationMetricPacket); });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 10,
+    });
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-is-final", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await waitFor(finals);
+    plugin.forceFinalize("turn-is-final");
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(finals).toEqual([
+      expect.objectContaining({
+        kind: "stt.result",
+        contextId: "turn-is-final",
+        text: "released provider text",
+        confidence: 0.87,
+        provider: expect.objectContaining({
+          name: "deepgram",
+          speechFinal: false,
+          fromFinalize: false,
+          finalizeRequested: false,
+        }),
+      }),
+    ]);
+    expect(errors).toHaveLength(0);
+    expect(metrics).not.toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "stt_provider_finalize_timeout" }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("correlates a pending Finalize response to the requested context across turn.change", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) return;
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type !== "Finalize") return;
+        setTimeout(() => {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            from_finalize: true,
+            channel: { alternatives: [{ transcript: "old turn flushed", confidence: 0.91 }] },
+          }));
+        }, 5);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("stt.result", (pkt) => { finals.push(pkt as SttResultPacket); });
+    bus.on("stt.error", (pkt) => { errors.push(pkt as SttErrorPacket); });
+    bus.on("metric.conversation", (pkt) => { metrics.push(pkt as ConversationMetricPacket); });
+    bus.on("usage.recorded", (pkt) => { usage.push(pkt as UsageRecordedPacket); });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 25,
+    });
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-old", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    plugin.forceFinalize("turn-old");
+    bus.push(Route.Main, {
+      kind: "turn.change",
+      previousContextId: "turn-old",
+      contextId: "turn-new",
+      reason: "websocket_audio_turn",
+      timestampMs: Date.now(),
+    });
+
+    await waitFor(finals);
+    await new Promise((resolve) => setTimeout(resolve, 35));
+
+    expect(finals).toEqual([
+      expect.objectContaining({
+        kind: "stt.result",
+        contextId: "turn-old",
+        text: "old turn flushed",
+        provider: expect.objectContaining({
+          fromFinalize: true,
+          finalizeRequested: true,
+        }),
+      }),
+    ]);
+    expect(errors).toHaveLength(0);
+    expect(metrics).not.toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "stt_provider_finalize_timeout", contextId: "turn-old" }),
+    ]));
+    // The trailing audio of turn-old (640B = 0.02s @ 16kHz) must be billed even though the
+    // from_finalize final arrives AFTER turn.change rotated the context. (Regression guard:
+    // retiring billing on turn.change would bill this as 0s.)
+    expect(usage).toEqual([
+      expect.objectContaining({ stage: "stt", contextId: "turn-old", audioSeconds: 0.02 }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("keeps Finalize response correlation after already released final text crosses turn.change", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            channel: { alternatives: [{ transcript: "old released text", confidence: 0.88 }] },
+          }));
+          return;
+        }
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type !== "Finalize") return;
+        setTimeout(() => {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            from_finalize: true,
+            channel: { alternatives: [{ transcript: "old finalize tail", confidence: 0.93 }] },
+          }));
+        }, 5);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("stt.result", (pkt) => { finals.push(pkt as SttResultPacket); });
+    bus.on("stt.error", (pkt) => { errors.push(pkt as SttErrorPacket); });
+    bus.on("metric.conversation", (pkt) => { metrics.push(pkt as ConversationMetricPacket); });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 25,
+    });
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-old-released", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await waitFor(finals);
+    plugin.forceFinalize("turn-old-released");
+    bus.push(Route.Main, {
+      kind: "turn.change",
+      previousContextId: "turn-old-released",
+      contextId: "turn-new-after-release",
+      reason: "websocket_audio_turn",
+      timestampMs: Date.now(),
+    });
+
+    await waitFor(finals, 2);
+    await new Promise((resolve) => setTimeout(resolve, 35));
+
+    expect(finals).toEqual([
+      expect.objectContaining({ contextId: "turn-old-released", text: "old released text" }),
+      expect.objectContaining({
+        contextId: "turn-old-released",
+        text: "old finalize tail",
+        provider: expect.objectContaining({
+          fromFinalize: true,
+          finalizeRequested: true,
+        }),
+      }),
+    ]);
+    expect(errors).toHaveLength(0);
+    expect(metrics).not.toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "stt_provider_finalize_timeout" }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("keeps the live connection after a single unconfirmed Finalize timeout", async () => {
+    // A lone slow finalize must NOT tear down the socket — the next turn has to stream
+    // on the same connection, otherwise a reconnect stall cascades into more timeouts.
+    const connections: WebSocket[] = [];
+    let lastAudioContext = "";
+    const endpointUrl = await createLocalServer((socket) => {
+      connections.push(socket);
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          // Only the fresh turn gets final text; the stale turn's interim-only
+          // text is intentionally never confirmed so its Finalize times out.
+          const forFreshTurn = lastAudioContext === "turn-fresh";
+          socket.send(JSON.stringify({
+            is_final: forFreshTurn,
+            speech_final: forFreshTurn,
+            channel: { alternatives: [{ transcript: forFreshTurn ? "fresh confirmed text" : "stale interim", confidence: 0.9 }] },
+          }));
+          return;
+        }
+        // Swallow Finalize for the stale turn (no from_finalize) → provider timeout.
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.result", (pkt) => { finals.push(pkt as SttResultPacket); });
+    bus.on("stt.error", (pkt) => { errors.push(pkt as SttErrorPacket); });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      provider_finalize_timeout_ms: 10,
+    });
+
+    lastAudioContext = "turn-stale";
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-stale", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-stale");
+    await waitFor(errors);
+
+    // The single timeout surfaced an error but the socket stayed up (no reconnect).
+    expect(errors).toHaveLength(1);
+    expect(connections).toHaveLength(1);
+    expect(connections[0]?.readyState).toBe(connections[0]?.OPEN);
+
+    // Next turn streams on the SAME connection and completes normally.
+    lastAudioContext = "turn-fresh";
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-fresh", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await waitFor(finals);
+
+    expect(connections).toHaveLength(1);
+    expect(finals).toEqual([
+      expect.objectContaining({ contextId: "turn-fresh", text: "fresh confirmed text" }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("reconnects only after consecutive unconfirmed Finalize timeouts", async () => {
+    // Two finalize timeouts in a row with no confirmed final between them looks like a
+    // genuinely wedged stream → reconnect; the fresh socket then serves the next turn.
+    const connections: WebSocket[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      connections.push(socket);
+      const connIndex = connections.length;
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          if (connIndex >= 2) {
+            socket.send(JSON.stringify({
+              is_final: true,
+              speech_final: true,
+              channel: { alternatives: [{ transcript: "fresh confirmed text", confidence: 0.9 }] },
+            }));
+          } else {
+            socket.send(JSON.stringify({
+              is_final: false,
+              speech_final: false,
+              channel: { alternatives: [{ transcript: "wedged interim", confidence: 0.8 }] },
+            }));
+          }
+          return;
+        }
+        // First connection never confirms any Finalize → repeated timeouts.
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.result", (pkt) => { finals.push(pkt as SttResultPacket); });
+    bus.on("stt.error", (pkt) => { errors.push(pkt as SttErrorPacket); });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      provider_finalize_timeout_ms: 10,
+      finalize_reset_threshold: 2,
+    });
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-1", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-1");
+    await waitFor(errors, 1);
+    // First timeout: still one connection (no reconnect yet).
+    expect(connections).toHaveLength(1);
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-2", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-2");
+    await waitFor(errors, 2);
+    await waitFor(connections, 2);
+
+    // Second consecutive timeout: now it reconnects and abandons the wedged socket.
+    expect(connections[0]?.readyState).toBe(connections[0]?.CLOSED);
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-fresh", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await waitFor(finals);
+    expect(finals).toEqual([
+      expect.objectContaining({ contextId: "turn-fresh", text: "fresh confirmed text" }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("clears the consecutive-timeout counter across a real socket reconnect", async () => {
+    // A timeout (counter->1) followed by an unrelated socket-close reconnect must not leave
+    // the count stale: a single timeout after reconnecting should NOT force another reset.
+    const connections: WebSocket[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      connections.push(socket);
+      socket.on("message", (_data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: false,
+          channel: { alternatives: [{ transcript: "unconfirmed", confidence: 0.8 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const timeoutErrors: SttErrorPacket[] = [];
+    bus.on("stt.error", (pkt) => {
+      const p = pkt as SttErrorPacket;
+      if (String((p.cause as Error | undefined)?.message ?? "").includes("Finalize timed out")) {
+        timeoutErrors.push(p);
+      }
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      provider_finalize_timeout_ms: 10,
+      finalize_reset_threshold: 2,
+    });
+
+    // Turn 1: one finalize timeout → counter 1 (below threshold, no reset yet).
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-before-reconnect", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-before-reconnect");
+    await waitFor(timeoutErrors, 1);
+    expect(connections).toHaveLength(1);
+
+    // An unrelated socket-close reconnect happens.
+    connections[0]!.close(1011, "NET-0000");
+    await waitFor(connections, 2);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Turn 2: a single post-reconnect timeout must NOT reconnect again — the counter was
+    // cleared on the reconnect, so it is 1 (< threshold 2), not a stale 2.
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-after-reconnect", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-after-reconnect");
+    await waitFor(timeoutErrors, 2);
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    // Would be 3 without clearing the counter on reconnect.
+    expect(connections).toHaveLength(2);
+    expect(connections[1]?.readyState).toBe(connections[1]?.OPEN);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("completes a timed-out turn from buffered text when finalize_timeout_fallback is on", async () => {
+    // Provider sends a confirmed is_final segment but never speech_final/from_finalize, so the
+    // turn would normally time out and be dropped. With the fallback on it must still emit an
+    // stt.result (which drives the turn plugin → LLM) instead of a "Finalize timed out" error.
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (_data, isBinary) => {
+        if (!isBinary) return; // swallow Finalize → provider never confirms
+        socket.send(JSON.stringify({
+          is_final: true,
+          speech_final: false,
+          channel: { alternatives: [{ transcript: "buffered text", confidence: 0.82 }] },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.result", (pkt) => { finals.push(pkt as SttResultPacket); });
+    bus.on("stt.error", (pkt) => { errors.push(pkt as SttErrorPacket); });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 10,
+      finalize_timeout_fallback: true,
+    });
+
+    bus.push(Route.Main, { kind: "stt.audio", contextId: "turn-timeout-fallback", timestampMs: Date.now(), audio: new Uint8Array(640) });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-timeout-fallback");
+    await waitFor(finals);
+
+    expect(finals).toEqual([
+      expect.objectContaining({ kind: "stt.result", contextId: "turn-timeout-fallback", text: "buffered text" }),
+    ]);
+    expect(
+      errors.filter((e) => String((e.cause as Error | undefined)?.message ?? "").includes("Finalize timed out")),
+    ).toHaveLength(0);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("ignores the next late provider final after timeout-fallback promotion (ignoreNext dedupe)", async () => {
+    // Interim-only buffer so the finalize timeout path runs (not correlation-expiry).
+    // After fallback promotes, a late is_final must not double-emit (ignoreNext).
+    let finalizeSeen = false;
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: false,
+            speech_final: false,
+            channel: { alternatives: [{ transcript: "interim only buffer", confidence: 0.8 }] },
+          }));
+          return;
+        }
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type !== "Finalize") return;
+        finalizeSeen = true;
+        setTimeout(() => {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            from_finalize: true,
+            channel: { alternatives: [{ transcript: "late provider final", confidence: 0.99 }] },
+          }));
+        }, 50);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      // true → timeout timer (not correlation-expiry-only when a final segment exists)
+      emit_eos_on_final: true,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 15,
+      finalize_timeout_fallback: true,
+    });
+
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-ignore-next",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    plugin.forceFinalize("turn-ignore-next");
+    await waitFor(finals);
+    await new Promise((resolve) => setTimeout(resolve, 80));
+
+    expect(finalizeSeen).toBe(true);
+    expect(finals).toEqual([
+      expect.objectContaining({
+        kind: "stt.result",
+        contextId: "turn-ignore-next",
+        text: "interim only buffer",
+      }),
+    ]);
+    expect(finals.some((f) => f.text === "late provider final")).toBe(false);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("discards a silence-only timed-out turn when finalize_timeout_fallback has no buffered text", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", () => {
+        // No transcripts at all — empty discard path.
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const errors: SttErrorPacket[] = [];
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 10,
+      finalize_timeout_fallback: true,
+    });
+
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-empty-discard",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+    plugin.forceFinalize("turn-empty-discard");
+    await waitFor(metrics, 2);
+
+    expect(finals).toHaveLength(0);
+    expect(
+      errors.filter((e) => String((e.cause as Error | undefined)?.message ?? "").includes("Finalize timed out")),
+    ).toHaveLength(0);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_finalize_timeout_empty_discard",
+        contextId: "turn-empty-discard",
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits stt.error for odd-length PCM16 without throwing into the bus pump", async () => {
+    const receivedAudio: Buffer[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) receivedAudio.push(data as Buffer);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-bad-pcm",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([1, 2, 3]),
+    });
+    await waitFor(errors);
+
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "stt.error",
+        contextId: "turn-bad-pcm",
+        component: "stt",
+        cause: expect.objectContaining({
+          message: expect.stringMatching(/even number of bytes/i),
+        }),
+      }),
+    ]);
+    expect(receivedAudio).toEqual([]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+});
+
+describe("DeepgramSTTPlugin provider speech-start (vad_events)", () => {
+  it("emits vad.speech_started for the current context when the provider sends SpeechStarted", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.send(JSON.stringify({ type: "SpeechStarted", channel: [0, 1], timestamp: 0.42 }));
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const speechStarts: Array<{ contextId: string; confidence: number }> = [];
+    bus.on("vad.speech_started", (pkt) => {
+      speechStarts.push(pkt as unknown as { contextId: string; confidence: number });
+    });
+
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      vad_events: true,
+    });
+    bus.push(Route.Main, { kind: "turn.change", contextId: "turn-1", timestampMs: Date.now() });
+    await waitFor(speechStarts);
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    expect(speechStarts.length).toBeGreaterThanOrEqual(1);
+    expect(speechStarts[0]!.confidence).toBe(1);
+  });
+
+  it("does not emit vad.speech_started by default (opt-in for VAD-less deployments)", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.send(JSON.stringify({ type: "SpeechStarted", channel: [0, 1], timestamp: 0.42 }));
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const speechStarts: unknown[] = [];
+    bus.on("vad.speech_started", (pkt) => {
+      speechStarts.push(pkt);
+    });
+
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    expect(speechStarts).toHaveLength(0);
+  });
+
+  it("passes keyterm config as repeatable query params (nova-3 keyterm prompting)", async () => {
+    const connectionUrls: string[] = [];
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let nextServer: WebSocketServer;
+      nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+    });
+    servers.push(server);
+    server.on("connection", (_socket, req) => {
+      connectionUrls.push(req.url ?? "");
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+    const endpointUrl = `ws://127.0.0.1:${address.port}/listen`;
+
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      keyterm: ["Syrinx", "Kuralle Suite"],
+    });
+    await waitFor(connectionUrls);
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    const url = connectionUrls[0]!;
+    expect(url).toContain("keyterm=Syrinx");
+    expect(url).toContain("keyterm=Kuralle+Suite");
+  });
+
+  it("omits keyterm from the URL when not configured", async () => {
+    const connectionUrls: string[] = [];
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let nextServer: WebSocketServer;
+      nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+    });
+    servers.push(server);
+    server.on("connection", (_socket, req) => {
+      connectionUrls.push(req.url ?? "");
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+    const endpointUrl = `ws://127.0.0.1:${address.port}/listen`;
+
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    await waitFor(connectionUrls);
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    expect(connectionUrls[0]!).not.toContain("keyterm=");
+  });
+
+  it("reconfigure replaces keyterms + endpointing + hard language and reconnects with the new URL", async () => {
+    const connectionUrls: string[] = [];
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let nextServer: WebSocketServer;
+      nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+    });
+    servers.push(server);
+    server.on("connection", (_socket, req) => {
+      connectionUrls.push(req.url ?? "");
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+    const endpointUrl = `ws://127.0.0.1:${address.port}/listen`;
+
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      language: "en-US",
+      keyterm: ["Syrinx"],
+      endpointing: 300,
+    });
+    await waitFor(connectionUrls, 1);
+    expect(connectionUrls[0]!).toContain("keyterm=Syrinx");
+    expect(connectionUrls[0]!).toContain("endpointing=300");
+    expect(connectionUrls[0]!).toContain("language=en-US");
+
+    expect(plugin.sttReconfigure).toBe(plugin);
+    // Hard language switch (e.g. code-switch to Spanish, or Nova-3 "multi") + keyterms + endpointing.
+    plugin.reconfigure({ keyterms: ["account number"], endpointingMs: 120, language: "es-ES" });
+    await waitFor(connectionUrls, 2);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    const reconnected = connectionUrls[1]!;
+    expect(reconnected).toContain("keyterm=account+number");
+    expect(reconnected).toContain("endpointing=120");
+    expect(reconnected).toContain("language=es-ES");
+    expect(reconnected).not.toContain("keyterm=Syrinx");
+    expect(reconnected).not.toContain("language=en-US");
+  });
+
+  it("reconfigure ignores Flux-only fields and does not reconnect or corrupt the Nova URL", async () => {
+    const connectionUrls: string[] = [];
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let nextServer: WebSocketServer;
+      nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+    });
+    servers.push(server);
+    server.on("connection", (_socket, req) => {
+      connectionUrls.push(req.url ?? "");
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+    const endpointUrl = `ws://127.0.0.1:${address.port}/listen`;
+
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      keyterm: ["Syrinx"],
+      endpointing: 300,
+    });
+    await waitFor(connectionUrls, 1);
+
+    plugin.reconfigure({ eotThreshold: 0.95, eagerEotThreshold: 0.4, eotTimeoutMs: 2000, contextText: "noop" });
+    // Give reconnect a chance if it incorrectly fired.
+    await new Promise((resolve) => setTimeout(resolve, 80));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    expect(connectionUrls).toHaveLength(1);
+    const url = connectionUrls[0]!;
+    expect(url).toContain("keyterm=Syrinx");
+    expect(url).toContain("endpointing=300");
+    expect(url).not.toContain("eot_threshold");
+    expect(url).not.toContain("eager_eot");
+  });
+
+  it("defaults encoding/channels/no_delay and lets them be overridden on the listen URL", async () => {
+    const connectionUrls: string[] = [];
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let nextServer: WebSocketServer;
+      nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+    });
+    servers.push(server);
+    server.on("connection", (_socket, req) => {
+      connectionUrls.push(req.url ?? "");
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+    const endpointUrl = `ws://127.0.0.1:${address.port}/listen`;
+
+    const busDefault = new PipelineBusImpl();
+    const startedDefault = startBus(busDefault);
+    const pluginDefault = new DeepgramSTTPlugin();
+    await pluginDefault.initialize(busDefault, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    await waitFor(connectionUrls, 1);
+    await pluginDefault.close();
+    busDefault.stop();
+    await startedDefault;
+
+    expect(connectionUrls[0]!).toContain("encoding=linear16");
+    expect(connectionUrls[0]!).toContain("channels=1");
+    expect(connectionUrls[0]!).toContain("no_delay=true");
+
+    const busOverride = new PipelineBusImpl();
+    const startedOverride = startBus(busOverride);
+    const pluginOverride = new DeepgramSTTPlugin();
+    await pluginOverride.initialize(busOverride, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 8000,
+      encoding: "mulaw",
+      channels: 2,
+      no_delay: false,
+    });
+    await waitFor(connectionUrls, 2);
+    await pluginOverride.close();
+    busOverride.stop();
+    await startedOverride;
+
+    const overridden = connectionUrls[1]!;
+    expect(overridden).toContain("encoding=mulaw");
+    expect(overridden).toContain("channels=2");
+    expect(overridden).toContain("no_delay=false");
+  });
+
+  it("merges query_params into the Deepgram listen URL", async () => {
+    const connectionUrls: string[] = [];
+    const server = await new Promise<WebSocketServer>((resolve) => {
+      let nextServer: WebSocketServer;
+      nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+    });
+    servers.push(server);
+    server.on("connection", (_socket, req) => {
+      connectionUrls.push(req.url ?? "");
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+    const endpointUrl = `ws://127.0.0.1:${address.port}/listen`;
+
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+      query_params: {
+        punctuate: true,
+        diarize: "true",
+        numerals: false,
+        tag: ["voice", "prod"],
+      },
+    });
+    await waitFor(connectionUrls);
+    await plugin.close();
+    bus.stop();
+    await started;
+
+    const url = connectionUrls[0]!;
+    expect(url).toContain("punctuate=true");
+    expect(url).toContain("diarize=true");
+    expect(url).toContain("numerals=false");
+    expect(url).toContain("tag=voice");
+    expect(url).toContain("tag=prod");
+  });
+});