@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/providers/speech-to-text/__tests__/resolve.test.ts

@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { setConfig } from "../../../__tests__/helpers/set-config.js";
 import { getConfig } from "../../../config/loader.js";
+import { SttError } from "../../../stt/types.js";
 
 // ---------------------------------------------------------------------------
 // Mocks — must be declared before any subject imports
@@ -491,7 +492,12 @@ describe("resolveTelephonySttCapability", () => {
 // Tests — telephony capability alignment with provider catalog
 // ---------------------------------------------------------------------------
 
-import { getProviderEntry, listProviderIds } from "../provider-catalog.js";
+import type { SttProviderId } from "../../../stt/types.js";
+import {
+  getProviderEntry,
+  listProviderIds,
+  supportsBoundary,
+} from "../provider-catalog.js";
 
 describe("telephony capability catalog alignment", () => {
   /**
@@ -502,6 +508,16 @@ describe("telephony capability catalog alignment", () => {
    * misalignment early.
    */
 
+  /**
+   * Providers that deliberately sit out telephony (`telephonyMode: "none"`).
+   * `deepgram-flux` is a streaming-only spike, and telephony is out of its
+   * scope. Nothing reroutes a call to another provider, so opting out here
+   * means a Flux-configured assistant does not transcribe calls.
+   */
+  const TELEPHONY_OPT_OUT: ReadonlySet<SttProviderId> = new Set([
+    "deepgram-flux",
+  ]);
+
   test("deepgram catalog entry has realtime-ws telephonyMode", () => {
     const entry = getProviderEntry("deepgram");
     expect(entry).toBeDefined();
@@ -535,18 +551,34 @@ describe("telephony capability catalog alignment", () => {
     expect(entry!.credentialProvider).toBe("openai");
   });
 
-  test("every catalog provider has a non-none telephonyMode", () => {
-    // The telephony capability resolver assumes all known providers
-    // participate in telephony over the media-stream transport. If a
-    // provider with telephonyMode: "none" is added, the resolver reports
-    // it as unsupported.
+  test("every catalog provider has a non-none telephonyMode unless it opts out", () => {
+    // The telephony capability resolver assumes known providers participate
+    // in telephony over the media-stream transport. A provider with
+    // telephonyMode: "none" is reported as unsupported, so opting out has to
+    // be a deliberate, listed choice rather than an oversight.
     for (const id of listProviderIds()) {
       const entry = getProviderEntry(id);
       expect(entry).toBeDefined();
+      if (TELEPHONY_OPT_OUT.has(id)) {
+        expect(entry!.telephonyMode).toBe("none");
+        continue;
+      }
       expect(entry!.telephonyMode).not.toBe("none");
     }
   });
 
+  test("telephony opt-out providers resolve as unsupported", async () => {
+    for (const id of TELEPHONY_OPT_OUT) {
+      const entry = getProviderEntry(id);
+      mockVellumAvailable = false;
+      mockProviderKeys = { [entry!.credentialProvider]: `test-key-${id}` };
+      applyConfig({ provider: id });
+
+      const result = await resolveTelephonySttCapability();
+      expect(result.status).toBe("unsupported");
+    }
+  });
+
   // -----------------------------------------------------------------------
   // Stable provider identity
   // -----------------------------------------------------------------------
@@ -574,6 +606,9 @@ describe("telephony capability catalog alignment", () => {
     };
 
     for (const id of listProviderIds()) {
+      if (TELEPHONY_OPT_OUT.has(id)) {
+        continue;
+      }
       const credKey = credentialMap[id];
       expect(credKey).toBeDefined();
 
@@ -1383,6 +1418,250 @@ describe("resolveStreamingTranscriber language plumbing", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests: advertised streaming capability vs. what the factory can build
+// ---------------------------------------------------------------------------
+
+describe("streaming capability matches the streaming factory", () => {
+  /**
+   * The catalog's `daemon-streaming` boundary is load-bearing in three
+   * places that must never disagree:
+   *
+   * 1. `resolveConversationStreamingSttCapability`, which preflight reports
+   *    as `supported`.
+   * 2. `resolveStreamingTranscriber`, which has to actually build an adapter.
+   * 3. The two user-facing "streaming-capable providers" strings, which list
+   *    exactly `listProviderIds().filter(id => supportsBoundary(id,
+   *    "daemon-streaming"))`: `stt/stt-stream-session.ts` and
+   *    `live-voice/live-voice-session.ts`.
+   *
+   * A provider that is advertised by (1) and (3) but resolves to `null` in
+   * (2) makes preflight lie and sends the session down the provider-error
+   * path, and the error message it lands on names the very provider that
+   * just failed as a supported alternative. This suite is the guard: every
+   * advertised provider must build.
+   *
+   * `deepgram-flux-realtime.js` is deliberately NOT mocked in this file, so
+   * the Flux case constructs the real adapter.
+   */
+  const STREAMING_CREDENTIAL: Record<string, string> = {
+    deepgram: "deepgram",
+    "deepgram-flux": "deepgram",
+    "google-gemini": "gemini",
+    "openai-whisper": "openai",
+    xai: "xai",
+    // vellum's credential is the platform connection, mocked below.
+    vellum: "vellum",
+  };
+
+  /** The exact list both user-facing error strings advertise. */
+  function advertisedStreamingProviders(): readonly SttProviderId[] {
+    return listProviderIds().filter((id) =>
+      supportsBoundary(id, "daemon-streaming"),
+    );
+  }
+
+  function seedCredentialsFor(id: SttProviderId): void {
+    const credential = STREAMING_CREDENTIAL[id];
+    expect(credential).toBeDefined();
+    mockVellumAvailable = id === "vellum";
+    mockVelayConnection =
+      id === "vellum"
+        ? {
+            wsBaseUrl: "ws://gateway.test",
+            httpBaseUrl: "http://gateway.test",
+            mintServiceToken: () => "vk-test",
+          }
+        : null;
+    mockProviderKeys = id === "vellum" ? {} : { [credential!]: `key-${id}` };
+    applyConfig({ provider: id });
+  }
+
+  beforeEach(() => {
+    mockVellumAvailable = false;
+    mockVelayConnection = null;
+    mockProviderKeys = {};
+    loggerWarnings.length = 0;
+  });
+
+  test("the advertised list includes deepgram-flux", () => {
+    // Guards the suite below against passing vacuously: if Flux dropped out of
+    // the advertised list, those loops would assert nothing about it.
+    expect(advertisedStreamingProviders()).toContain("deepgram-flux");
+  });
+
+  test("every advertised provider reports supported AND builds a transcriber", async () => {
+    for (const id of advertisedStreamingProviders()) {
+      seedCredentialsFor(id);
+
+      const capability = await resolveConversationStreamingSttCapability();
+      expect(capability.status).toBe("supported");
+
+      const transcriber = await resolveStreamingTranscriber();
+      expect(transcriber).not.toBeNull();
+      expect(transcriber!.boundaryId).toBe("daemon-streaming");
+    }
+  });
+
+  test("every advertised provider reports missing credentials AND builds nothing without them", async () => {
+    for (const id of advertisedStreamingProviders()) {
+      mockVellumAvailable = false;
+      mockVelayConnection = null;
+      mockProviderKeys = {};
+      applyConfig({ provider: id });
+
+      const capability = await resolveConversationStreamingSttCapability();
+      expect(capability.status).toBe("missing-credentials");
+      expect(await resolveStreamingTranscriber()).toBeNull();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: deepgram-flux streaming resolution
+// ---------------------------------------------------------------------------
+
+describe("deepgram-flux streaming resolution", () => {
+  beforeEach(() => {
+    mockVellumAvailable = false;
+    mockVelayConnection = null;
+    mockProviderKeys = {};
+    loggerWarnings.length = 0;
+  });
+
+  test("resolves a real Flux transcriber on the shared Deepgram key", async () => {
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      sampleRate: 16_000,
+    });
+
+    expect(transcriber).not.toBeNull();
+    expect(transcriber!.providerId).toBe("deepgram-flux");
+    expect(transcriber!.boundaryId).toBe("daemon-streaming");
+    // Flux owns turn boundaries, so callers feature-detecting this method
+    // must fall back to stop().
+    expect(transcriber!.finalizeUtterance).toBeUndefined();
+  });
+
+  test("resolves from an explicit providerId, the way live voice asks", async () => {
+    // Live voice derives its provider itself and passes it in rather than
+    // letting the resolver re-read config.
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "openai-whisper" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      providerId: "deepgram-flux",
+    });
+
+    expect(transcriber?.providerId).toBe("deepgram-flux");
+  });
+
+  test("resolves null without a Deepgram key", async () => {
+    mockProviderKeys = { openai: "sk-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    expect(await resolveStreamingTranscriber()).toBeNull();
+  });
+
+  test("telephony callers resolve to null without a Flux-specific conditional", async () => {
+    // The catalog's telephonyMode: "none" is the only gate. Boundary-
+    // requiring callers fall back to per-turn batch transcription.
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      utteranceBoundaryFinals: true,
+    });
+
+    expect(transcriber).toBeNull();
+    expect(loggerWarnings).toHaveLength(1);
+    expect(
+      (loggerWarnings[0]!.data as { providerId?: unknown }).providerId,
+    ).toBe("deepgram-flux");
+  });
+
+  test("telephony capability reports Flux as unsupported", async () => {
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    const result = await resolveTelephonySttCapability();
+
+    expect(result.status).toBe("unsupported");
+  });
+
+  test("diarize: 'required' rejects Flux rather than silently dropping labels", async () => {
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      diarize: "required",
+    });
+
+    expect(transcriber).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: batch resolution against a streaming-only provider
+// ---------------------------------------------------------------------------
+
+describe("deepgram-flux batch resolution", () => {
+  beforeEach(() => {
+    mockVellumAvailable = false;
+    mockVelayConnection = null;
+    mockProviderKeys = {};
+    loggerWarnings.length = 0;
+  });
+
+  /**
+   * Every batch caller pairs a `null` resolve with "no speech-to-text
+   * provider is configured". Flux is configured, and the operator who set it
+   * needs to be told which of the two Deepgram entries batch runs on, so the
+   * resolver raises a typed error instead of returning that `null`.
+   */
+  test("throws a named error rather than resolving null", async () => {
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    await expect(resolveBatchTranscriber()).rejects.toThrow(
+      'Deepgram Flux is streaming-only. Batch transcription requires the deepgram provider: set services.stt.provider to "deepgram".',
+    );
+  });
+
+  test("marks the error user-facing so friendly copy does not overwrite it", async () => {
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    const err = await resolveBatchTranscriber().catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(SttError);
+    expect((err as SttError).category).toBe("provider-error");
+    expect((err as SttError).userFacing).toBe(true);
+  });
+
+  test("logs the gap so a degrading caller still leaves a daemon-side trace", async () => {
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({ provider: "deepgram-flux" });
+
+    await resolveBatchTranscriber().catch(() => undefined);
+
+    expect(loggerWarnings).toHaveLength(1);
+    expect(
+      (loggerWarnings[0]!.data as { providerId?: unknown }).providerId,
+    ).toBe("deepgram-flux");
+  });
+
+  test("a provider that is absent from the catalog still resolves null", async () => {
+    // "Unknown provider" is a different situation from "known provider,
+    // wrong boundary", and only the latter has a fix worth naming.
+    applyConfig({ provider: "not-a-provider" });
+
+    expect(await resolveBatchTranscriber()).toBeNull();
+  });
+});
+
 describe("sttCredentialGapReason", () => {
   test("vellum gets connection copy; API-key providers keep key copy", () => {
     expect(sttCredentialGapReason("vellum")).toContain("platform connect");