@kuralle-syrinx/deepgram 2.1.0

package/.handoff/finalize-contract-probe.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import { WebSocketServer, type WebSocket } from "ws";
+import {
+  PipelineBusImpl,
+  Route,
+  type ConversationMetricPacket,
+  type SttErrorPacket,
+  type SttResultPacket,
+} from "@kuralle-syrinx/core";
+import { DeepgramSTTPlugin } from "../src/index.js";
+
+async function createServer(onConnection: (socket: WebSocket) => void): Promise<{
+  url: string;
+  close: () => Promise<void>;
+}> {
+  const server = await new Promise<WebSocketServer>((resolve) => {
+    let nextServer: WebSocketServer;
+    nextServer = new WebSocketServer({ port: 0 }, () => resolve(nextServer));
+  });
+  server.on("connection", onConnection);
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("expected tcp address");
+  return {
+    url: `ws://127.0.0.1:${address.port}/listen`,
+    close: () => new Promise((resolve) => {
+      for (const client of server.clients) client.terminate();
+      server.close(() => resolve());
+    }),
+  };
+}
+
+async function waitUntil(predicate: () => boolean): Promise<void> {
+  for (let i = 0; i < 100; i += 1) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error("timed out waiting for probe condition");
+}
+
+describe("Deepgram finalize contract probe", () => {
+  it("keeps a delayed Finalize response correlated to the requested context after currentContextId moves", async () => {
+    const controlMessages: string[] = [];
+    const server = await createServer((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);
+        if (msg.type !== "Finalize") return;
+        setTimeout(() => {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            from_finalize: true,
+            channel: { alternatives: [{ transcript: "old turn confirmed", confidence: 0.91 }] },
+          }));
+        }, 10);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    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: server.url,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 40,
+      finalize_timeout_fallback: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "old-vad-fragment",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    bus.push(Route.Main, {
+      kind: "turn.change",
+      contextId: "new-vad-fragment",
+      previousContextId: "old-vad-fragment",
+      reason: "probe_vad_fragment_split",
+      timestampMs: Date.now(),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    plugin.forceFinalize("old-vad-fragment");
+    await waitUntil(() => finals.length > 0);
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    expect(controlMessages).toContain("Finalize");
+    expect(finals).toEqual([
+      expect.objectContaining({
+        contextId: "old-vad-fragment",
+        text: "old turn confirmed",
+      }),
+    ]);
+    expect(errors).toHaveLength(0);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_final_segment",
+        contextId: "old-vad-fragment",
+        value: expect.stringContaining("\"fromFinalize\":true"),
+      }),
+    ]));
+    expect(metrics).not.toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        name: "stt_provider_finalize_timeout",
+        contextId: "old-vad-fragment",
+      }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+    await server.close();
+  });
+
+  it("releases provider-final text without speech_final/from_finalize and does not need timeout fallback", async () => {
+    const controlMessages: string[] = [];
+    const server = await createServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          socket.send(JSON.stringify({
+            is_final: true,
+            speech_final: false,
+            channel: { alternatives: [{ transcript: "just want to complain again so", confidence: 0.84 }] },
+          }));
+          return;
+        }
+        const msg = JSON.parse(data.toString()) as { type?: string };
+        if (msg.type) controlMessages.push(msg.type);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    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: server.url,
+      sample_rate: 16000,
+      emit_eos_on_final: false,
+      finalize_on_speech_final: false,
+      provider_finalize_timeout_ms: 20,
+      finalize_timeout_fallback: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "messy-live-turn",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await waitUntil(() => metrics.some((m) => m.name === "stt_provider_final_segment"));
+    await waitUntil(() => finals.length > 0);
+    plugin.forceFinalize("messy-live-turn");
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    expect(controlMessages).toContain("Finalize");
+    expect(finals).toEqual([
+      expect.objectContaining({
+        contextId: "messy-live-turn",
+        text: "just want to complain again so",
+      }),
+    ]);
+    expect(errors).toHaveLength(0);
+    expect(metrics).toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "stt_provider_final_segment" }),
+    ]));
+    expect(metrics).not.toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: "stt_provider_finalize_timeout" }),
+    ]));
+
+    await plugin.close();
+    bus.stop();
+    await started;
+    await server.close();
+  });
+});

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@kuralle-syrinx/deepgram",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./stt": "./src/stt.ts",
+    "./tts": "./src/tts.ts"
+  },
+  "dependencies": {
+    "@kuralle-syrinx/core": "2.1.0",
+    "@kuralle-syrinx/ws": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+//
+// Deepgram provider plugins — speech-to-text and text-to-speech in one package.
+// Import from the barrel for both, or the `./stt` / `./tts` subpaths for one.
+
+export * from "./stt.js";
+export * from "./tts.js";