@vellumai/assistant 0.6.3 → 0.6.4

package/src/tts/__tests__/provider-catalog-consistency.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Consistency guard: assistant catalog vs client artifact.
+ *
+ * The assistant-side canonical catalog (`provider-catalog.ts`) and the
+ * client-facing artifact (`meta/tts-provider-catalog.json`) must agree on
+ * provider IDs, ordering, and display names. This test fails when the two
+ * sources drift — for example, if a new provider is added to the assistant
+ * catalog but forgotten in the client artifact, or if display names diverge.
+ *
+ * These checks complement the full parity guard in
+ * `assistant/src/__tests__/tts-catalog-parity.test.ts`, which validates
+ * credential metadata and deeper structural invariants. This file focuses
+ * on fast, local assertions that live next to the catalog source.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  getCatalogProvider,
+  listCatalogProviderIds,
+  listCatalogProviders,
+} from "../provider-catalog.js";
+
+// ---------------------------------------------------------------------------
+// Load the client artifact
+// ---------------------------------------------------------------------------
+
+interface ClientCatalogProvider {
+  id: string;
+  displayName: string;
+  credentialMode?: string;
+  credentialsGuide?: { url: string };
+}
+
+interface ClientCatalog {
+  version: number;
+  providers: ClientCatalogProvider[];
+}
+
+/**
+ * Resolve the path to `meta/tts-provider-catalog.json` relative to the
+ * repo root. The test file lives at
+ * `assistant/src/tts/__tests__/provider-catalog-consistency.test.ts`,
+ * so the repo root is four directories up.
+ */
+const CLIENT_ARTIFACT_PATH = resolve(
+  __dirname,
+  "../../../../meta/tts-provider-catalog.json",
+);
+
+function loadClientArtifact(): ClientCatalog {
+  const raw = readFileSync(CLIENT_ARTIFACT_PATH, "utf-8");
+  return JSON.parse(raw) as ClientCatalog;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("TTS provider catalog / client artifact consistency", () => {
+  const assistantIds = listCatalogProviderIds();
+  const clientCatalog = loadClientArtifact();
+  const clientIds = clientCatalog.providers.map((p) => p.id);
+
+  // -- Loadability ----------------------------------------------------------
+
+  test("client artifact file is loadable and has providers", () => {
+    expect(clientCatalog.providers.length).toBeGreaterThan(0);
+  });
+
+  // -- Provider ID parity ---------------------------------------------------
+
+  test("assistant catalog and client artifact have the same provider IDs (sorted)", () => {
+    expect(assistantIds.slice().sort()).toEqual(clientIds.slice().sort());
+  });
+
+  test("no provider IDs in assistant catalog are missing from client artifact", () => {
+    const missingFromClient = assistantIds.filter(
+      (id) => !clientIds.includes(id),
+    );
+    if (missingFromClient.length > 0) {
+      const message = [
+        "Assistant catalog has provider IDs not present in meta/tts-provider-catalog.json.",
+        "",
+        "Missing from client artifact:",
+        ...missingFromClient.map((id) => `  - ${id}`),
+        "",
+        "Add entries for these providers to meta/tts-provider-catalog.json.",
+      ].join("\n");
+      expect(missingFromClient, message).toEqual([]);
+    }
+  });
+
+  test("no provider IDs in client artifact are missing from assistant catalog", () => {
+    const missingFromAssistant = clientIds.filter(
+      (id) => !assistantIds.includes(id),
+    );
+    if (missingFromAssistant.length > 0) {
+      const message = [
+        "Client artifact (meta/tts-provider-catalog.json) has provider IDs not present in assistant catalog.",
+        "",
+        "Missing from assistant catalog:",
+        ...missingFromAssistant.map((id) => `  - ${id}`),
+        "",
+        "Add entries for these providers to assistant/src/tts/provider-catalog.ts.",
+      ].join("\n");
+      expect(missingFromAssistant, message).toEqual([]);
+    }
+  });
+
+  // -- Ordering parity ------------------------------------------------------
+
+  test("assistant catalog and client artifact list providers in the same order", () => {
+    expect(clientIds).toEqual([...assistantIds]);
+  });
+
+  // -- Display name parity --------------------------------------------------
+
+  test("display names match between assistant catalog and client artifact", () => {
+    const violations: string[] = [];
+    for (const clientEntry of clientCatalog.providers) {
+      try {
+        const assistantEntry = getCatalogProvider(clientEntry.id as any);
+        if (clientEntry.displayName !== assistantEntry.displayName) {
+          violations.push(
+            `"${clientEntry.id}": client="${clientEntry.displayName}" vs assistant="${assistantEntry.displayName}"`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by provider ID parity tests above.
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "Display name mismatch between assistant catalog and client artifact.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // -- Structural sanity ----------------------------------------------------
+
+  test("client artifact version is a positive integer", () => {
+    expect(Number.isInteger(clientCatalog.version)).toBe(true);
+    expect(clientCatalog.version).toBeGreaterThan(0);
+  });
+
+  test("every client artifact entry has a non-empty id and displayName", () => {
+    for (const entry of clientCatalog.providers) {
+      expect(entry.id.length).toBeGreaterThan(0);
+      expect(entry.displayName.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every client artifact entry has a credentialMode and credentialsGuide", () => {
+    const violations: string[] = [];
+    for (const entry of clientCatalog.providers) {
+      if (
+        !entry.credentialMode ||
+        !["api-key", "credential"].includes(entry.credentialMode)
+      ) {
+        violations.push(
+          `${entry.id}: missing or invalid credentialMode (got "${entry.credentialMode}")`,
+        );
+      }
+      if (!entry.credentialsGuide?.url) {
+        violations.push(`${entry.id}: missing credentialsGuide.url`);
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "Client artifact entries have missing required fields.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // -- Catalog size guard ---------------------------------------------------
+
+  test("assistant catalog has at least as many providers as expected", () => {
+    const providers = listCatalogProviders();
+    // Guard: adding a provider to the catalog without updating this
+    // lower-bound forces the developer to acknowledge the growth.
+    expect(providers.length).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/tts/__tests__/provider-catalog.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  getCatalogProvider,
+  listCatalogProviderIds,
+  listCatalogProviders,
+} from "../provider-catalog.js";
+
+// ---------------------------------------------------------------------------
+// Catalog invariants
+// ---------------------------------------------------------------------------
+
+describe("TTS provider catalog", () => {
+  const entries = listCatalogProviders();
+  const ids = listCatalogProviderIds();
+
+  // -- Uniqueness -----------------------------------------------------------
+
+  test("all provider IDs are unique", () => {
+    const seen = new Set<string>();
+    for (const entry of entries) {
+      expect(seen.has(entry.id)).toBe(false);
+      seen.add(entry.id);
+    }
+  });
+
+  // -- Required fields ------------------------------------------------------
+
+  test("every entry has a non-empty id", () => {
+    for (const entry of entries) {
+      expect(entry.id.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry has a non-empty displayName", () => {
+    for (const entry of entries) {
+      expect(entry.displayName.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry has a valid callMode", () => {
+    const validModes = new Set(["native-twilio", "synthesized-play"]);
+    for (const entry of entries) {
+      expect(validModes.has(entry.callMode)).toBe(true);
+    }
+  });
+
+  test("every entry has a capabilities object with supportedFormats", () => {
+    for (const entry of entries) {
+      expect(entry.capabilities).toBeDefined();
+      expect(Array.isArray(entry.capabilities.supportedFormats)).toBe(true);
+      expect(entry.capabilities.supportedFormats.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry has at least one secret requirement", () => {
+    for (const entry of entries) {
+      expect(entry.secretRequirements.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every secret requirement has non-empty fields", () => {
+    for (const entry of entries) {
+      for (const secret of entry.secretRequirements) {
+        expect(secret.credentialStoreKey.length).toBeGreaterThan(0);
+        expect(secret.displayName.length).toBeGreaterThan(0);
+        expect(secret.setCommand.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  // -- Lookup helpers -------------------------------------------------------
+
+  test("listCatalogProviderIds returns IDs matching listCatalogProviders", () => {
+    expect(ids).toEqual(entries.map((e) => e.id));
+  });
+
+  test("getCatalogProvider returns the correct entry for each known ID", () => {
+    for (const entry of entries) {
+      const resolved = getCatalogProvider(entry.id);
+      expect(resolved).toBe(entry);
+    }
+  });
+
+  test("getCatalogProvider throws for unknown provider ID", () => {
+    expect(() => getCatalogProvider("nonexistent-provider")).toThrow(
+      /Unknown TTS provider "nonexistent-provider"/,
+    );
+  });
+
+  test("getCatalogProvider error message includes known provider IDs", () => {
+    try {
+      getCatalogProvider("nonexistent-provider");
+      throw new Error("Expected getCatalogProvider to throw");
+    } catch (err) {
+      const msg = (err as Error).message;
+      for (const id of ids) {
+        expect(msg).toContain(id);
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Provider-specific assertions
+// ---------------------------------------------------------------------------
+
+describe("ElevenLabs catalog entry", () => {
+  const entry = getCatalogProvider("elevenlabs");
+
+  test("uses native-twilio call mode", () => {
+    expect(entry.callMode).toBe("native-twilio");
+  });
+
+  test("does not support streaming", () => {
+    expect(entry.capabilities.supportsStreaming).toBe(false);
+  });
+
+  test("supports mp3 format", () => {
+    expect(entry.capabilities.supportedFormats).toContain("mp3");
+  });
+
+  test("requires a credential stored under 'credential/elevenlabs/api_key'", () => {
+    const apiKeySecret = entry.secretRequirements.find(
+      (s) => s.credentialStoreKey === "credential/elevenlabs/api_key",
+    );
+    expect(apiKeySecret).toBeDefined();
+    expect(apiKeySecret!.displayName).toContain("ElevenLabs");
+  });
+});
+
+describe("Fish Audio catalog entry", () => {
+  const entry = getCatalogProvider("fish-audio");
+
+  test("uses synthesized-play call mode", () => {
+    expect(entry.callMode).toBe("synthesized-play");
+  });
+
+  test("supports streaming", () => {
+    expect(entry.capabilities.supportsStreaming).toBe(true);
+  });
+
+  test("supports mp3, wav, and opus formats", () => {
+    expect(entry.capabilities.supportedFormats).toContain("mp3");
+    expect(entry.capabilities.supportedFormats).toContain("wav");
+    expect(entry.capabilities.supportedFormats).toContain("opus");
+  });
+
+  test("requires an API key stored under 'credential/fish-audio/api_key'", () => {
+    const apiKeySecret = entry.secretRequirements.find(
+      (s) => s.credentialStoreKey === "credential/fish-audio/api_key",
+    );
+    expect(apiKeySecret).toBeDefined();
+    expect(apiKeySecret!.displayName).toContain("Fish Audio");
+  });
+});
+
+describe("Deepgram catalog entry", () => {
+  const entry = getCatalogProvider("deepgram");
+
+  test("uses synthesized-play call mode", () => {
+    expect(entry.callMode).toBe("synthesized-play");
+  });
+
+  test("does not support streaming", () => {
+    expect(entry.capabilities.supportsStreaming).toBe(false);
+  });
+
+  test("supports mp3, wav, and opus formats", () => {
+    expect(entry.capabilities.supportedFormats).toContain("mp3");
+    expect(entry.capabilities.supportedFormats).toContain("wav");
+    expect(entry.capabilities.supportedFormats).toContain("opus");
+  });
+
+  test("requires a bare API key stored under 'deepgram'", () => {
+    const apiKeySecret = entry.secretRequirements.find(
+      (s) => s.credentialStoreKey === "deepgram",
+    );
+    expect(apiKeySecret).toBeDefined();
+    expect(apiKeySecret!.displayName).toContain("Deepgram");
+    expect(apiKeySecret!.setCommand).toContain("assistant keys set deepgram");
+  });
+});

package/src/tts/__tests__/provider-registry.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  _resetTtsProviderRegistry,
+  getTtsProvider,
+  listTtsProviders,
+  registerTtsProvider,
+} from "../provider-registry.js";
+import type { TtsProvider } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function stubProvider(id: string): TtsProvider {
+  return {
+    id,
+    capabilities: {
+      supportsStreaming: false,
+      supportedFormats: ["mp3"],
+    },
+    async synthesize() {
+      return { audio: Buffer.alloc(0), contentType: "audio/mpeg" };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("TTS provider registry", () => {
+  afterEach(() => {
+    _resetTtsProviderRegistry();
+  });
+
+  // -- Registration & lookup ------------------------------------------------
+
+  test("registers and resolves a provider by ID", () => {
+    const provider = stubProvider("test-provider");
+    registerTtsProvider(provider);
+
+    const resolved = getTtsProvider("test-provider");
+    expect(resolved).toBe(provider);
+  });
+
+  test("rejects duplicate registration with an explicit error", () => {
+    registerTtsProvider(stubProvider("dup"));
+
+    expect(() => registerTtsProvider(stubProvider("dup"))).toThrow(
+      /already registered/,
+    );
+  });
+
+  // -- Unknown provider errors ----------------------------------------------
+
+  test("throws for unknown provider ID when registry is empty", () => {
+    expect(() => getTtsProvider("nope")).toThrow(/Unknown TTS provider "nope"/);
+  });
+
+  test("throws for unknown provider ID and lists known providers", () => {
+    registerTtsProvider(stubProvider("alpha"));
+    registerTtsProvider(stubProvider("beta"));
+
+    try {
+      getTtsProvider("gamma");
+      throw new Error("Expected getTtsProvider to throw");
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toMatch(/Unknown TTS provider "gamma"/);
+      expect(msg).toMatch(/alpha/);
+      expect(msg).toMatch(/beta/);
+    }
+  });
+
+  // -- Listing order --------------------------------------------------------
+
+  test("listTtsProviders returns providers in registration order", () => {
+    registerTtsProvider(stubProvider("charlie"));
+    registerTtsProvider(stubProvider("alpha"));
+    registerTtsProvider(stubProvider("bravo"));
+
+    const ids = listTtsProviders().map((p) => p.id);
+    expect(ids).toEqual(["charlie", "alpha", "bravo"]);
+  });
+
+  test("listTtsProviders returns empty array when nothing is registered", () => {
+    expect(listTtsProviders()).toEqual([]);
+  });
+});

package/src/tts/provider-catalog.ts

@@ -0,0 +1,201 @@
+/**
+ * Canonical TTS provider catalog.
+ *
+ * This module is the **single source of truth** for provider IDs and
+ * provider-level metadata on the assistant side. Every TTS provider that
+ * the system knows about is declared here — downstream modules query the
+ * catalog via {@link getCatalogProvider}, {@link listCatalogProviders}, or
+ * {@link listCatalogProviderIds} instead of hardcoding provider IDs.
+ *
+ * Adding a new TTS provider starts here: create a new
+ * {@link TtsProviderCatalogEntry} and append it to {@link CATALOG}.
+ */
+
+import type { TtsCallMode, TtsProviderId } from "./types.js";
+
+export type { TtsCallMode } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Catalog entry model
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata about a secret (API key / credential) required by a provider.
+ */
+export interface TtsProviderSecretRequirement {
+  /**
+   * The key used to retrieve this secret from the secure credential store.
+   *
+   * For simple keys this is a bare name (e.g. `"elevenlabs"`).
+   * For namespaced keys this follows the `credential/{service}/{field}`
+   * convention (e.g. `"credential/fish-audio/api_key"`).
+   */
+  readonly credentialStoreKey: string;
+
+  /** Human-readable label shown in settings UI and error messages. */
+  readonly displayName: string;
+
+  /**
+   * CLI command the user can run to store this secret.
+   *
+   * Shown in error messages when the key is missing.
+   */
+  readonly setCommand: string;
+}
+
+/**
+ * Provider-level capabilities metadata surfaced by the catalog.
+ *
+ * These describe static, provider-wide traits — they do not change based
+ * on runtime configuration or per-request parameters.
+ */
+export interface TtsProviderCatalogCapabilities {
+  /** Whether the provider supports chunk-level streaming synthesis. */
+  readonly supportsStreaming: boolean;
+
+  /** Audio formats the provider can produce (e.g. `["mp3"]`). */
+  readonly supportedFormats: readonly string[];
+}
+
+/**
+ * A single entry in the TTS provider catalog.
+ *
+ * Captures everything the system needs to know about a provider at a
+ * metadata level — identity, display name, telephony call mode,
+ * capabilities, and secret requirements.
+ */
+export interface TtsProviderCatalogEntry {
+  /** Unique provider identifier matching {@link TtsProviderId}. */
+  readonly id: TtsProviderId;
+
+  /** Human-readable name for display in settings UI and logs. */
+  readonly displayName: string;
+
+  /** How this provider integrates with the telephony call path. */
+  readonly callMode: TtsCallMode;
+
+  /**
+   * Whether the call path may fall back to native Twilio token-based
+   * TTS when synthesized audio fails.
+   *
+   * Providers with `callMode: "native-twilio"` always set this to `true`.
+   * Synthesized-play providers that also work through Twilio's built-in
+   * TTS (e.g. Fish Audio) set this to `true` so callers still hear
+   * a response if synthesis fails. Providers that have **no** native
+   * Twilio integration (e.g. Deepgram) set this to `false` — a synthesis
+   * failure must propagate so the outer error handler can surface a
+   * user-facing recovery message.
+   */
+  readonly allowNativeFallback: boolean;
+
+  /** Static provider-level capabilities. */
+  readonly capabilities: Readonly<TtsProviderCatalogCapabilities>;
+
+  /** Secrets the provider requires to function. */
+  readonly secretRequirements: readonly Readonly<TtsProviderSecretRequirement>[];
+}
+
+// ---------------------------------------------------------------------------
+// Catalog data
+// ---------------------------------------------------------------------------
+
+/**
+ * The authoritative list of TTS providers.
+ *
+ * Order is significant only for display purposes (e.g. settings dropdowns).
+ */
+const CATALOG: readonly TtsProviderCatalogEntry[] = [
+  {
+    id: "elevenlabs",
+    displayName: "ElevenLabs",
+    callMode: "native-twilio",
+    allowNativeFallback: true,
+    capabilities: {
+      supportsStreaming: false,
+      supportedFormats: ["mp3"],
+    },
+    secretRequirements: [
+      {
+        credentialStoreKey: "credential/elevenlabs/api_key",
+        displayName: "ElevenLabs API Key",
+        setCommand:
+          "assistant credentials set --service elevenlabs --field api_key <key>",
+      },
+    ],
+  },
+  {
+    id: "fish-audio",
+    displayName: "Fish Audio",
+    callMode: "synthesized-play",
+    allowNativeFallback: true,
+    capabilities: {
+      supportsStreaming: true,
+      supportedFormats: ["mp3", "wav", "opus"],
+    },
+    secretRequirements: [
+      {
+        credentialStoreKey: "credential/fish-audio/api_key",
+        displayName: "Fish Audio API Key",
+        setCommand:
+          "assistant credentials set --service fish-audio --field api_key <key>",
+      },
+    ],
+  },
+  {
+    id: "deepgram",
+    displayName: "Deepgram",
+    callMode: "synthesized-play",
+    allowNativeFallback: false,
+    capabilities: {
+      supportsStreaming: false,
+      supportedFormats: ["mp3", "wav", "opus"],
+    },
+    secretRequirements: [
+      {
+        credentialStoreKey: "deepgram",
+        displayName: "Deepgram API Key",
+        setCommand: "assistant keys set deepgram <key>",
+      },
+    ],
+  },
+] as const;
+
+/** Index for O(1) lookup by provider ID. */
+const catalogById = new Map<TtsProviderId, TtsProviderCatalogEntry>(
+  CATALOG.map((entry) => [entry.id, entry]),
+);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * List all catalog providers in display order.
+ */
+export function listCatalogProviders(): readonly TtsProviderCatalogEntry[] {
+  return CATALOG;
+}
+
+/**
+ * List all known provider IDs in display order.
+ */
+export function listCatalogProviderIds(): TtsProviderId[] {
+  return CATALOG.map((entry) => entry.id);
+}
+
+/**
+ * Look up a catalog entry by provider ID.
+ *
+ * @throws if the ID is not in the catalog.
+ */
+export function getCatalogProvider(id: TtsProviderId): TtsProviderCatalogEntry {
+  const entry = catalogById.get(id);
+  if (!entry) {
+    const known = listCatalogProviderIds();
+    throw new Error(
+      `Unknown TTS provider "${id}" is not in the catalog. ` +
+        `Known providers: ${known.join(", ")}`,
+    );
+  }
+  return entry;
+}