@alexkroman1/aai 1.7.1 → 1.8.0

package/host/providers/stt/elevenlabs.ts

@@ -85,16 +85,17 @@ export function openElevenLabs(opts: ElevenLabsOptions = {}): SttOpener {
       const emitter: Emitter<SttEvents> = createNanoEvents<SttEvents>();
       let closed = false;
 
-      connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (msg) => {
+      function emitTranscript(event: "partial" | "final", text: string | undefined) {
         if (closed) return;
-        const text = msg.text ?? "";
-        if (text.length > 0) emitter.emit("partial", text);
+        if (text && text.length > 0) emitter.emit(event, text);
+      }
+
+      connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (msg) => {
+        emitTranscript("partial", msg.text);
       });
 
       connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (msg) => {
-        if (closed) return;
-        const text = msg.text ?? "";
-        if (text.length > 0) emitter.emit("final", text);
+        emitTranscript("final", msg.text);
       });
 
       connection.on(RealtimeEvents.ERROR, (payload) => {
@@ -111,15 +112,15 @@ export function openElevenLabs(opts: ElevenLabsOptions = {}): SttOpener {
         emitter.emit("error", makeSttError("stt_auth_failed", msg.error));
       });
 
-      const close = async (): Promise<void> => {
+      async function close(): Promise<void> {
         if (closed) return;
         closed = true;
         try {
           connection.close();
         } catch {
-          // Swallow: caller has already decided to tear down.
+          // Already tearing down — ignore close errors.
         }
-      };
+      }
 
       if (openOpts.signal.aborted) {
         void close();

package/host/providers/stt/soniox.test.ts

@@ -5,20 +5,6 @@ import { describe, expect, test, vi } from "vitest";
 import { flush } from "../../_test-utils.ts";
 import { openSoniox } from "./soniox.ts";
 
-// ---------------------------------------------------------------------------
-// Mock the `ws` package. Each FakeWS:
-//   - extends EventEmitter for `on`/`off`/`once` semantics that match the
-//     real `ws.WebSocket` API
-//   - exposes `readyState` initialised to OPEN once "open" fires
-//   - records sent frames so tests can assert on them
-//   - exposes `_fire(ev, data)` so tests inject incoming server frames
-//
-// Vitest hoists `vi.mock` to module top, so the factory can't reference
-// outer top-level declarations. `vi.hoisted` runs even earlier and lets
-// us share `FakeWS` + the `latest` capture between the factory and the
-// test bodies.
-// ---------------------------------------------------------------------------
-
 interface FakeWSInstance {
   readyState: number;
   sent: Array<string | Uint8Array>;
@@ -32,6 +18,7 @@ interface FakeWSInstance {
 
 type Listener = (...args: unknown[]) => void;
 
+// `vi.mock` is hoisted above top-level decls, so share state via `vi.hoisted`.
 const { latest, FakeWS } = vi.hoisted(() => {
   const latestRef: { ws: FakeWSInstance | undefined } = { ws: undefined };
   class FakeWSImpl implements FakeWSInstance {
@@ -87,37 +74,37 @@ const { latest, FakeWS } = vi.hoisted(() => {
 
 vi.mock("ws", () => ({ default: FakeWS, WebSocket: FakeWS }));
 
-async function openSession(
-  opts: { apiKey?: string; languageHints?: string[]; model?: string } = {},
-): Promise<{
+interface OpenSessionOpts {
+  apiKey?: string;
+  languageHints?: string[];
+  model?: string;
+}
+
+async function openSession(opts: OpenSessionOpts = {}): Promise<{
   session: import("../../../sdk/providers.ts").SttSession;
   ws: FakeWSInstance;
   controller: AbortController;
 }> {
   latest.ws = undefined;
-  const opener = openSoniox(
-    opts.languageHints || opts.model
-      ? {
-          ...(opts.model ? { model: opts.model } : {}),
-          ...(opts.languageHints ? { languageHints: opts.languageHints } : {}),
-        }
-      : {},
-  );
+  const openerOpts: { model?: string; languageHints?: string[] } = {};
+  if (opts.model) openerOpts.model = opts.model;
+  if (opts.languageHints) openerOpts.languageHints = opts.languageHints;
+  const opener = openSoniox(openerOpts);
   const controller = new AbortController();
   const session = await opener.open({
     sampleRate: 16_000,
     apiKey: opts.apiKey ?? "test-key",
     signal: controller.signal,
   });
-  // The constructor schedules an `open` event via setImmediate; the
-  // adapter's `await waitForOpen(ws)` already drained it, so `latest.ws`
-  // is fully wired by now. Capture into a local const so TS narrows the
-  // type — direct property access on a mutable ref keeps the union.
-  const ws: FakeWSInstance | undefined = latest.ws;
+  const ws = latest.ws;
   if (!ws) throw new Error("no fake ws captured");
   return { session, ws, controller };
 }
 
+function frame(payload: unknown): Buffer {
+  return Buffer.from(JSON.stringify(payload));
+}
+
 describe("Soniox real-time STT adapter", () => {
   test("openSoniox() returns an opener with name 'soniox'", () => {
     expect(openSoniox({}).name).toBe("soniox");
@@ -166,14 +153,12 @@ describe("Soniox real-time STT adapter", () => {
 
     ws._fire(
       "message",
-      Buffer.from(
-        JSON.stringify({
-          tokens: [
-            { text: "hel", is_final: false },
-            { text: "lo", is_final: false },
-          ],
-        }),
-      ),
+      frame({
+        tokens: [
+          { text: "hel", is_final: false },
+          { text: "lo", is_final: false },
+        ],
+      }),
     );
 
     await flush();
@@ -188,31 +173,19 @@ describe("Soniox real-time STT adapter", () => {
     session.on("final", (t) => finals.push(t));
     session.on("partial", (t) => partials.push(t));
 
-    // Frame 1: only final tokens — buffered, NOT yet emitted.
     ws._fire(
       "message",
-      Buffer.from(
-        JSON.stringify({
-          tokens: [
-            { text: "hello", is_final: true },
-            { text: " world", is_final: true },
-          ],
-        }),
-      ),
+      frame({
+        tokens: [
+          { text: "hello", is_final: true },
+          { text: " world", is_final: true },
+        ],
+      }),
     );
     await flush();
     expect(finals).toEqual([]);
 
-    // Frame 2: a non-final preview token — flushes the buffered final
-    // and emits the new partial.
-    ws._fire(
-      "message",
-      Buffer.from(
-        JSON.stringify({
-          tokens: [{ text: "how", is_final: false }],
-        }),
-      ),
-    );
+    ws._fire("message", frame({ tokens: [{ text: "how", is_final: false }] }));
     await flush();
     expect(finals).toEqual(["hello world"]);
     expect(partials).toEqual(["how"]);
@@ -224,15 +197,7 @@ describe("Soniox real-time STT adapter", () => {
     const finals: string[] = [];
     session.on("final", (t) => finals.push(t));
 
-    ws._fire(
-      "message",
-      Buffer.from(
-        JSON.stringify({
-          tokens: [{ text: "bye", is_final: true }],
-          finished: true,
-        }),
-      ),
-    );
+    ws._fire("message", frame({ tokens: [{ text: "bye", is_final: true }], finished: true }));
 
     await flush();
     expect(finals).toEqual(["bye"]);
@@ -244,16 +209,9 @@ describe("Soniox real-time STT adapter", () => {
     const finals: string[] = [];
     session.on("final", (t) => finals.push(t));
 
-    ws._fire(
-      "message",
-      Buffer.from(
-        JSON.stringify({
-          tokens: [{ text: "trailing", is_final: true }],
-        }),
-      ),
-    );
+    ws._fire("message", frame({ tokens: [{ text: "trailing", is_final: true }] }));
     await flush();
-    expect(finals).toEqual([]); // not flushed yet — no boundary
+    expect(finals).toEqual([]);
 
     await session.close();
     expect(finals).toEqual(["trailing"]);
@@ -264,10 +222,7 @@ describe("Soniox real-time STT adapter", () => {
     const errors: { code: string; message: string }[] = [];
     session.on("error", (e) => errors.push({ code: e.code, message: e.message }));
 
-    ws._fire(
-      "message",
-      Buffer.from(JSON.stringify({ error_code: 503, error_message: "service unavailable" })),
-    );
+    ws._fire("message", frame({ error_code: 503, error_message: "service unavailable" }));
 
     await flush();
     expect(errors).toHaveLength(1);
@@ -325,12 +280,7 @@ describe("Soniox real-time STT adapter", () => {
     await session.close();
     await session.close();
 
-    ws._fire(
-      "message",
-      Buffer.from(
-        JSON.stringify({ tokens: [{ text: "ignored", is_final: true }], finished: true }),
-      ),
-    );
+    ws._fire("message", frame({ tokens: [{ text: "ignored", is_final: true }], finished: true }));
 
     await flush();
     expect(finals).toEqual([]);

package/host/providers/stt/soniox.ts

@@ -1,25 +1,4 @@
 // Copyright 2026 the AAI authors. MIT license.
-/**
- * Soniox real-time STT opener (host-only).
- *
- * The user-facing descriptor factory (`soniox(...)`) lives in
- * `sdk/providers/stt/soniox.ts`. This module is the host-side
- * counterpart: it takes the descriptor options + an API key and
- * returns an {@link SttOpener} that the pipeline session drives.
- *
- * Soniox's published JS client (`@soniox/speech-to-text-web`) is
- * browser-only — it depends on `MediaRecorder` and `getUserMedia`. For
- * server-side use we talk to the WebSocket directly:
- *   `wss://stt-rt.soniox.com/transcribe-websocket`
- *
- * Wire format:
- *   - First text frame: JSON config with api_key, model, audio_format,
- *     sample_rate, num_channels (and optional language hints).
- *   - Subsequent binary frames: 16-bit signed little-endian PCM audio.
- *   - Server replies: JSON `{ tokens: [{ text, is_final }] }` messages.
- *     Final tokens accumulate; non-final tokens are a rolling preview.
- *   - On error: `{ error_code, error_message }`.
- */
 
 import { createNanoEvents, type Emitter } from "nanoevents";
 import WebSocket from "ws";
@@ -32,9 +11,10 @@ import {
   type SttSession,
 } from "../../../sdk/providers.ts";
 
+// `@soniox/speech-to-text-web` is browser-only (MediaRecorder/getUserMedia),
+// so we speak the WebSocket protocol directly.
 const SONIOX_WS_URL = "wss://stt-rt.soniox.com/transcribe-websocket";
 
-/** Soniox token shape from the wire protocol. */
 interface SonioxToken {
   text?: string;
   is_final?: boolean;
@@ -47,10 +27,6 @@ interface SonioxResponse {
   error_message?: string;
 }
 
-/**
- * Walk a batch of Soniox tokens, sending finals into `appendFinal` and
- * returning the concatenated non-finals as a rolling preview string.
- */
 function consumeTokens(tokens: SonioxToken[], appendFinal: (text: string) => void): string {
   let nonFinal = "";
   for (const tok of tokens) {
@@ -65,14 +41,13 @@ function consumeTokens(tokens: SonioxToken[], appendFinal: (text: string) => voi
   return nonFinal;
 }
 
-/** Resolve once the WebSocket opens; reject on the first error. */
 function waitForOpen(ws: WebSocket): Promise<void> {
   return new Promise((resolve, reject) => {
-    const onOpen = () => {
+    const onOpen = (): void => {
       ws.off("error", onErr);
       resolve();
     };
-    const onErr = (err: Error) => {
+    const onErr = (err: Error): void => {
       ws.off("open", onOpen);
       reject(err);
     };
@@ -81,7 +56,6 @@ function waitForOpen(ws: WebSocket): Promise<void> {
   });
 }
 
-/** Build the initial JSON config frame for a Soniox session. */
 function buildConfigFrame(
   apiKey: string,
   opts: SonioxOptions,
@@ -100,7 +74,6 @@ function buildConfigFrame(
   return config;
 }
 
-/** Parse a Soniox text frame into a {@link SonioxResponse}; returns null on garbage. */
 function parseFrame(raw: WebSocket.RawData): SonioxResponse | null {
   try {
     return JSON.parse(raw.toString()) as SonioxResponse;
@@ -109,12 +82,6 @@ function parseFrame(raw: WebSocket.RawData): SonioxResponse | null {
   }
 }
 
-/**
- * Handle one server response. Emits `error`, `final`, and `partial` events
- * onto `emitter` based on the token batch and the running `finalBuf`. The
- * caller owns `finalBuf` so it survives across messages and can be flushed
- * on close.
- */
 function handleResponse(
   res: SonioxResponse,
   emitter: Emitter<SttEvents>,
@@ -134,10 +101,8 @@ function handleResponse(
   const nonFinal = consumeTokens(res.tokens, (text) => {
     finalBuf.value += text;
   });
-  // Flush an accumulated final whenever the next batch's non-final preview
-  // begins (or when the session finishes). This batches contiguous final
-  // tokens into a single `final` event, matching what downstream pipeline
-  // session code expects.
+  // Batch contiguous finals into one `final` event by flushing only when
+  // a new non-final preview starts (or the session finishes).
   if (finalBuf.value.length > 0 && (nonFinal.length > 0 || res.finished)) {
     emitter.emit("final", finalBuf.value);
     finalBuf.value = "";
@@ -147,7 +112,6 @@ function handleResponse(
   }
 }
 
-/** Build an {@link SttOpener} from resolved Soniox descriptor options. */
 export function openSoniox(opts: SonioxOptions = {}): SttOpener {
   return {
     name: "soniox",
@@ -163,11 +127,6 @@ export function openSoniox(opts: SonioxOptions = {}): SttOpener {
       const ws = new WebSocket(SONIOX_WS_URL);
       const emitter: Emitter<SttEvents> = createNanoEvents<SttEvents>();
       let closed = false;
-      // Soniox emits final tokens once and non-final tokens repeatedly. We
-      // accumulate finals into a buffer flushed on each non-final boundary
-      // and forward non-finals as the rolling partial. Mirrors how the
-      // existing AssemblyAI/Deepgram openers map provider-specific token
-      // streams onto the SttEvents `partial`/`final` contract.
       const finalBuf = { value: "" };
 
       try {
@@ -179,7 +138,6 @@ export function openSoniox(opts: SonioxOptions = {}): SttOpener {
         );
       }
 
-      // Initial config frame (text). Sent first; audio binary frames follow.
       ws.send(JSON.stringify(buildConfigFrame(apiKey, opts, openOpts.sampleRate)));
 
       ws.on("message", (raw: WebSocket.RawData) => {
@@ -195,7 +153,6 @@ export function openSoniox(opts: SonioxOptions = {}): SttOpener {
 
       ws.on("close", (code: number) => {
         if (closed) return;
-        // 1000 = normal closure.
         if (code !== 1000) {
           emitter.emit("error", makeSttError("stt_stream_error", `socket closed ${code}`));
         }
@@ -204,7 +161,6 @@ export function openSoniox(opts: SonioxOptions = {}): SttOpener {
       const close = async (): Promise<void> => {
         if (closed) return;
         closed = true;
-        // Flush any trailing final tokens that arrived right before close.
         if (finalBuf.value.length > 0) {
           emitter.emit("final", finalBuf.value);
           finalBuf.value = "";
@@ -212,7 +168,7 @@ export function openSoniox(opts: SonioxOptions = {}): SttOpener {
         try {
           ws.close();
         } catch {
-          // Swallow: caller has already decided to tear down.
+          // Caller is tearing down; ws.close errors are not actionable.
         }
       };
 
@@ -225,8 +181,7 @@ export function openSoniox(opts: SonioxOptions = {}): SttOpener {
       return {
         sendAudio(pcm: Int16Array) {
           if (closed || ws.readyState !== WebSocket.OPEN) return;
-          // Sending the underlying buffer directly avoids a copy. ws will
-          // hand it to the OS as a binary frame.
+          // Pass the underlying buffer to avoid a copy.
           ws.send(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength), { binary: true });
         },
         on(event, fn) {

package/host/providers/tts/cartesia.test.ts

@@ -1,11 +1,9 @@
 // Copyright 2025 the AAI authors. MIT license.
-/** Unit test for the Cartesia TTS adapter. Mocks `@cartesia/cartesia-js`. */
 
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { flush } from "../../_test-utils.ts";
 import { type CartesiaSession, openCartesia } from "./cartesia.ts";
 
-// Recorded interactions on the fake `TTSWSContext` — one entry per method call.
 interface RecordedSend {
   kind: "send" | "cancel";
   contextId: string;
@@ -17,7 +15,6 @@ interface RecordedSend {
 
 const sends: RecordedSend[] = [];
 
-/** Minimal shape of the request the adapter sends to Cartesia. */
 interface FakeGenerationRequest {
   transcript: string;
   continue: boolean;
@@ -25,17 +22,12 @@ interface FakeGenerationRequest {
   model_id?: string;
 }
 
-/**
- * Fake `TTSWSContext`. Mirrors the fields the adapter touches:
- * `contextId`, `send`, `cancel`.
- */
 interface FakeContext {
   contextId: string;
   send(req: FakeGenerationRequest): Promise<void>;
   cancel(): Promise<void>;
 }
 
-/** Fake `TTSWS`. EventEmitter-ish with a `_fire` test hook. */
 interface FakeTTSWS {
   contexts: FakeContext[];
   context(opts: { contextId: string }): FakeContext;
@@ -45,7 +37,7 @@ interface FakeTTSWS {
 }
 
 vi.mock("@cartesia/cartesia-js", () => {
-  const makeWs = (): FakeTTSWS => {
+  function makeWs(): FakeTTSWS {
     const listeners = new Map<string, Array<(...args: unknown[]) => void>>();
     const ws: FakeTTSWS = {
       contexts: [],
@@ -75,7 +67,7 @@ vi.mock("@cartesia/cartesia-js", () => {
         listeners.set(event, arr);
         return ws;
       },
-      close(_props) {
+      close() {
         /* no-op */
       },
       _fire(event, payload) {
@@ -83,7 +75,7 @@ vi.mock("@cartesia/cartesia-js", () => {
       },
     };
     return ws;
-  };
+  }
   return {
     Cartesia: class {
       tts = {
@@ -93,6 +85,17 @@ vi.mock("@cartesia/cartesia-js", () => {
   };
 });
 
+function expectedSend(contextId: string, transcript: string, cont: boolean): RecordedSend {
+  return {
+    kind: "send",
+    contextId,
+    transcript,
+    continue: cont,
+    language: "en",
+    model_id: "sonic-2",
+  };
+}
+
 beforeEach(() => {
   sends.length = 0;
 });
@@ -121,34 +124,11 @@ describe("cartesia TTS adapter", () => {
     session.flush();
     await flush();
 
-    // All three sends for turn 1 carry the same contextId — two deltas with
-    // continue: true, then an empty-transcript send with continue: false.
     const turn1Sends = sends.filter((s) => s.contextId === turn1);
     expect(turn1Sends).toEqual([
-      {
-        kind: "send",
-        contextId: turn1,
-        transcript: "hello",
-        continue: true,
-        language: "en",
-        model_id: "sonic-2",
-      },
-      {
-        kind: "send",
-        contextId: turn1,
-        transcript: " world",
-        continue: true,
-        language: "en",
-        model_id: "sonic-2",
-      },
-      {
-        kind: "send",
-        contextId: turn1,
-        transcript: "",
-        continue: false,
-        language: "en",
-        model_id: "sonic-2",
-      },
+      expectedSend(turn1, "hello", true),
+      expectedSend(turn1, " world", true),
+      expectedSend(turn1, "", false),
     ]);
 
     // Rotation is deferred until the next sendText so Cartesia's late
@@ -156,21 +136,11 @@ describe("cartesia TTS adapter", () => {
     // pass the context-id filter.
     expect(session._currentContextId()).toBe(turn1);
 
-    // Subsequent sendText rotates to a fresh context.
     session.sendText("next");
     const turn2 = session._currentContextId();
     expect(turn2).not.toBe(turn1);
     await flush();
-    expect(sends.filter((s) => s.contextId === turn2)).toEqual([
-      {
-        kind: "send",
-        contextId: turn2,
-        transcript: "next",
-        continue: true,
-        language: "en",
-        model_id: "sonic-2",
-      },
-    ]);
+    expect(sends.filter((s) => s.contextId === turn2)).toEqual([expectedSend(turn2, "next", true)]);
 
     controller.abort();
     await session.close();
@@ -191,16 +161,8 @@ describe("cartesia TTS adapter", () => {
 
     await flush();
 
-    // We expect: send("hello", continue:true) on turn1, then cancel(turn1).
     expect(sends).toEqual([
-      {
-        kind: "send",
-        contextId: turn1,
-        transcript: "hello",
-        continue: true,
-        language: "en",
-        model_id: "sonic-2",
-      },
+      expectedSend(turn1, "hello", true),
       { kind: "cancel", contextId: turn1 },
     ]);
 
@@ -209,7 +171,6 @@ describe("cartesia TTS adapter", () => {
     // keep passing the filter until the next turn actually begins.
     expect(session._currentContextId()).toBe(turn1);
 
-    // A subsequent sendText mints a fresh context for turn2.
     session.sendText("again");
     const turn2 = session._currentContextId();
     expect(turn2).not.toBe(turn1);