@vellumai/assistant 0.6.3 → 0.6.4

package/src/providers/provider-secret-catalog.ts

@@ -0,0 +1,139 @@
+/**
+ * Canonical source for API-key-addressable providers.
+ *
+ * This module composes the full set of providers that store API keys in
+ * secure storage (the `api_key` secret type) from three sources:
+ *
+ * 1. **LLM / search providers** -- statically declared here because they
+ *    have no separate catalog module yet.
+ * 2. **STT providers** -- dynamically derived from the canonical STT
+ *    provider catalog by reading credential-provider names.
+ * 3. **TTS catalog providers** -- dynamically derived from the canonical
+ *    TTS provider catalog by selecting entries whose secret requirements
+ *    use the bare-name (non-credential) storage convention.
+ *
+ * Consumers that need the set of valid API-key provider names should
+ * import {@link API_KEY_PROVIDERS} from this module rather than
+ * maintaining their own inline arrays.
+ */
+
+import { listCatalogProviders } from "../tts/provider-catalog.js";
+import { listCredentialProviderNames as listSttCredentialProviderNames } from "./speech-to-text/provider-catalog.js";
+
+// ---------------------------------------------------------------------------
+// Static LLM / search providers
+// ---------------------------------------------------------------------------
+
+/**
+ * LLM and search providers that store API keys under their bare provider
+ * name in the secure credential store (e.g. `anthropic`, `openai`).
+ *
+ * These are declared statically because no provider-catalog module exists
+ * for them yet. When one is introduced, this array should be replaced with
+ * a catalog-derived computation analogous to the TTS logic below.
+ */
+const LLM_AND_SEARCH_API_KEY_PROVIDERS = [
+  "anthropic",
+  "openai",
+  "gemini",
+  "ollama",
+  "fireworks",
+  "openrouter",
+  "brave",
+  "perplexity",
+] as const;
+
+// ---------------------------------------------------------------------------
+// STT catalog-derived providers
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the deduplicated set of STT credential-provider names from the
+ * canonical STT provider catalog, filtering out names that already appear
+ * in the LLM/search list to avoid duplicates (e.g. `openai-whisper` maps
+ * to `"openai"` which is already present in
+ * {@link LLM_AND_SEARCH_API_KEY_PROVIDERS}).
+ */
+function sttApiKeyProviderNames(): string[] {
+  const llmSet = new Set<string>(LLM_AND_SEARCH_API_KEY_PROVIDERS);
+  return listSttCredentialProviderNames().filter((name) => !llmSet.has(name));
+}
+
+// ---------------------------------------------------------------------------
+// TTS catalog-derived providers
+// ---------------------------------------------------------------------------
+
+/**
+ * The credential-store key prefix used by the namespaced credential type.
+ * Secrets stored under this prefix use the `credential` secret type
+ * (`assistant credentials set ...`) rather than the `api_key` type
+ * (`assistant keys set ...`), so they are excluded from the API-key
+ * provider list.
+ */
+const CREDENTIAL_KEY_PREFIX = "credential/";
+
+/**
+ * Derive the set of TTS bare-name credential store keys that use the
+ * `api_key` secret type by inspecting the catalog's secret requirements.
+ *
+ * A TTS provider entry is API-key-addressable when it declares at least
+ * one secret whose `credentialStoreKey` is a bare name (i.e. does NOT
+ * start with the `credential/` prefix). The bare key name is returned
+ * rather than the provider ID because the key name is what appears in
+ * the credential store (e.g. `deepgram` not `deepgram-tts`).
+ */
+function catalogApiKeyNames(): string[] {
+  return listCatalogProviders()
+    .filter((entry) =>
+      entry.secretRequirements.some(
+        (s) => !s.credentialStoreKey.startsWith(CREDENTIAL_KEY_PREFIX),
+      ),
+    )
+    .flatMap((entry) =>
+      entry.secretRequirements
+        .filter((s) => !s.credentialStoreKey.startsWith(CREDENTIAL_KEY_PREFIX))
+        .map((s) => s.credentialStoreKey),
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Unified export
+// ---------------------------------------------------------------------------
+
+/**
+ * All providers that store API keys in secure storage via the `api_key`
+ * secret type (`assistant keys set <provider> <key>`).
+ *
+ * This is the **single authoritative list** consumed by:
+ * - Config loader (validation of provider names in `config.json`)
+ * - Secret routes (HTTP API key add / read / delete validation)
+ * - CLI `keys` command (help text, list iteration)
+ * - Provider availability checks
+ *
+ * Adding a new TTS provider to the catalog with a bare-name secret
+ * requirement automatically includes it here. Adding a new STT
+ * provider to the STT catalog automatically includes it here (shared
+ * credential names like `openai` are deduplicated against the LLM
+ * list). Shared credential names across STT and TTS (e.g. `deepgram`)
+ * are deduplicated so the list contains no duplicates. Adding a new
+ * LLM or search provider requires appending to
+ * {@link LLM_AND_SEARCH_API_KEY_PROVIDERS} until those domains get
+ * their own catalog modules.
+ */
+export const API_KEY_PROVIDERS: readonly string[] = (() => {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const name of [
+    ...LLM_AND_SEARCH_API_KEY_PROVIDERS,
+    ...sttApiKeyProviderNames(),
+    ...catalogApiKeyNames(),
+  ]) {
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push(name);
+    }
+  }
+
+  return result;
+})();

package/src/providers/registry.ts

@@ -9,7 +9,7 @@ import {
 } from "./managed-proxy/context.js";
 import { getProviderDefaultModel } from "./model-intents.js";
 import { OllamaProvider } from "./ollama/client.js";
-import { OpenAIProvider } from "./openai/client.js";
+import { OpenAIResponsesProvider } from "./openai/client.js";
 import { OpenRouterProvider } from "./openrouter/client.js";
 import { RetryProvider } from "./retry.js";
 import type { Provider } from "./types.js";
@@ -174,7 +174,7 @@ export async function initializeProviders(
     registerProvider(
       "openai",
       new RetryProvider(
-        new OpenAIProvider(openaiCreds.apiKey, model, {
+        new OpenAIResponsesProvider(openaiCreds.apiKey, model, {
           streamTimeoutMs,
           ...(openaiCreds.baseURL ? { baseURL: openaiCreds.baseURL } : {}),
         }),

package/src/providers/retry.ts

@@ -26,6 +26,13 @@ const EFFORT_SUPPORTED_PROVIDERS = new Set([
   "fireworks",
 ]);
 
+/**
+ * Providers that consume the `thinking` config. Anthropic uses it directly on
+ * the wire; OpenRouter translates it into its unified `reasoning` parameter so
+ * users can control extended thinking on Anthropic models served via OpenRouter.
+ */
+const THINKING_AWARE_PROVIDERS = new Set(["anthropic", "openrouter"]);
+
 /** Patterns that indicate a transient streaming corruption from the SDK. */
 const RETRYABLE_STREAM_PATTERNS = [
   "Unexpected event order",
@@ -79,7 +86,7 @@ function normalizeSendMessageOptions(
   const hasIntent = config.modelIntent !== undefined;
 
   const needsThinkingStrip =
-    providerName !== "anthropic" && config.thinking !== undefined;
+    !THINKING_AWARE_PROVIDERS.has(providerName) && config.thinking !== undefined;
   const needsEffortStrip =
     !EFFORT_SUPPORTED_PROVIDERS.has(providerName) && config.effort !== undefined;
   const needsSpeedStrip =
@@ -98,8 +105,12 @@ function normalizeSendMessageOptions(
   const nextConfig: Record<string, unknown> = { ...config };
   delete nextConfig.modelIntent;
 
-  // thinking is Anthropic-specific; strip it for other providers
-  if (providerName !== "anthropic" && nextConfig.thinking !== undefined) {
+  // thinking is Anthropic-specific on the wire; OpenRouter reads it as a
+  // signal for its unified reasoning parameter. Strip it for other providers.
+  if (
+    !THINKING_AWARE_PROVIDERS.has(providerName) &&
+    nextConfig.thinking !== undefined
+  ) {
     delete nextConfig.thinking;
   }
 

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

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  getCredentialProvider,
+  getProviderEntry,
+  listCredentialProviderNames,
+  listProviderEntries,
+  listProviderIds,
+  supportsBoundary,
+  supportsDiarization,
+} from "../provider-catalog.js";
+
+// ---------------------------------------------------------------------------
+// Catalog invariants
+// ---------------------------------------------------------------------------
+
+describe("STT provider catalog", () => {
+  // -----------------------------------------------------------------------
+  // Stable IDs
+  // -----------------------------------------------------------------------
+
+  test("listProviderIds returns all known provider IDs", () => {
+    const ids = listProviderIds();
+    expect(ids).toContain("openai-whisper");
+    expect(ids).toContain("deepgram");
+    expect(ids).toContain("google-gemini");
+  });
+
+  test("listProviderIds returns IDs in deterministic insertion order", () => {
+    const first = listProviderIds();
+    const second = listProviderIds();
+    expect(first).toEqual(second);
+  });
+
+  test("every ID returned by listProviderIds has a catalog entry", () => {
+    for (const id of listProviderIds()) {
+      expect(getProviderEntry(id)).toBeDefined();
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Credential provider names
+  // -----------------------------------------------------------------------
+
+  test("listCredentialProviderNames returns deduplicated names", () => {
+    const names = listCredentialProviderNames();
+    const unique = new Set(names);
+    expect(names.length).toBe(unique.size);
+  });
+
+  test("listCredentialProviderNames includes expected providers", () => {
+    const names = listCredentialProviderNames();
+    // openai-whisper maps to "openai", deepgram maps to "deepgram", google-gemini maps to "gemini"
+    expect(names).toContain("openai");
+    expect(names).toContain("deepgram");
+    expect(names).toContain("gemini");
+  });
+
+  test("listCredentialProviderNames returns names in deterministic order", () => {
+    const first = listCredentialProviderNames();
+    const second = listCredentialProviderNames();
+    expect(first).toEqual(second);
+  });
+
+  // -----------------------------------------------------------------------
+  // Entry-level invariants
+  // -----------------------------------------------------------------------
+
+  test("every entry has a non-empty credentialProvider", () => {
+    for (const entry of listProviderEntries()) {
+      expect(entry.credentialProvider.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry has at least one supported boundary", () => {
+    for (const entry of listProviderEntries()) {
+      expect(entry.supportedBoundaries.size).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry ID matches its catalog key", () => {
+    for (const id of listProviderIds()) {
+      const entry = getProviderEntry(id);
+      expect(entry?.id).toBe(id);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Boundary support
+  // -----------------------------------------------------------------------
+
+  test("supportsBoundary returns true for supported boundaries", () => {
+    expect(supportsBoundary("openai-whisper", "daemon-batch")).toBe(true);
+    expect(supportsBoundary("deepgram", "daemon-batch")).toBe(true);
+    expect(supportsBoundary("google-gemini", "daemon-batch")).toBe(true);
+  });
+
+  test("supportsBoundary returns true for daemon-streaming on streaming-capable providers", () => {
+    expect(supportsBoundary("deepgram", "daemon-streaming")).toBe(true);
+    expect(supportsBoundary("google-gemini", "daemon-streaming")).toBe(true);
+    expect(supportsBoundary("openai-whisper", "daemon-streaming")).toBe(true);
+  });
+
+  test("supportsBoundary returns false for unknown provider IDs", () => {
+    // Cast to bypass type checking for the test
+    expect(supportsBoundary("nonexistent" as never, "daemon-batch")).toBe(
+      false,
+    );
+  });
+
+  // -----------------------------------------------------------------------
+  // Conversation streaming mode
+  // -----------------------------------------------------------------------
+
+  test("conversationStreamingMode is set for all providers", () => {
+    for (const entry of listProviderEntries()) {
+      expect(entry.conversationStreamingMode).toBeDefined();
+      expect(["realtime-ws", "incremental-batch", "none"]).toContain(
+        entry.conversationStreamingMode,
+      );
+    }
+  });
+
+  test("deepgram has realtime-ws conversation streaming mode", () => {
+    const entry = getProviderEntry("deepgram");
+    expect(entry?.conversationStreamingMode).toBe("realtime-ws");
+  });
+
+  test("google-gemini has realtime-ws conversation streaming mode", () => {
+    const entry = getProviderEntry("google-gemini");
+    expect(entry?.conversationStreamingMode).toBe("realtime-ws");
+  });
+
+  test("openai-whisper has incremental-batch conversation streaming mode", () => {
+    const entry = getProviderEntry("openai-whisper");
+    expect(entry?.conversationStreamingMode).toBe("incremental-batch");
+  });
+
+  // -----------------------------------------------------------------------
+  // Telephony routing metadata
+  // -----------------------------------------------------------------------
+
+  test("every entry has telephonyRouting metadata", () => {
+    for (const entry of listProviderEntries()) {
+      expect(entry.telephonyRouting).toBeDefined();
+      expect(["conversation-relay-native", "media-stream-custom"]).toContain(
+        entry.telephonyRouting.strategyKind,
+      );
+    }
+  });
+
+  test("conversation-relay-native entries have twilioNativeMapping", () => {
+    for (const entry of listProviderEntries()) {
+      if (entry.telephonyRouting.strategyKind === "conversation-relay-native") {
+        expect(entry.telephonyRouting.twilioNativeMapping).toBeDefined();
+        expect(
+          entry.telephonyRouting.twilioNativeMapping!.provider.length,
+        ).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  test("media-stream-custom entries do not have twilioNativeMapping", () => {
+    for (const entry of listProviderEntries()) {
+      if (entry.telephonyRouting.strategyKind === "media-stream-custom") {
+        expect(entry.telephonyRouting.twilioNativeMapping).toBeUndefined();
+      }
+    }
+  });
+
+  test("deepgram has conversation-relay-native strategy with Deepgram Twilio mapping", () => {
+    const entry = getProviderEntry("deepgram");
+    expect(entry?.telephonyRouting.strategyKind).toBe(
+      "conversation-relay-native",
+    );
+    expect(entry?.telephonyRouting.twilioNativeMapping?.provider).toBe(
+      "Deepgram",
+    );
+    expect(
+      entry?.telephonyRouting.twilioNativeMapping?.defaultSpeechModel,
+    ).toBe("nova-3");
+  });
+
+  test("google-gemini has conversation-relay-native strategy with Google Twilio mapping", () => {
+    const entry = getProviderEntry("google-gemini");
+    expect(entry?.telephonyRouting.strategyKind).toBe(
+      "conversation-relay-native",
+    );
+    expect(entry?.telephonyRouting.twilioNativeMapping?.provider).toBe(
+      "Google",
+    );
+    expect(
+      entry?.telephonyRouting.twilioNativeMapping?.defaultSpeechModel,
+    ).toBeUndefined();
+  });
+
+  test("openai-whisper has media-stream-custom strategy without Twilio mapping", () => {
+    const entry = getProviderEntry("openai-whisper");
+    expect(entry?.telephonyRouting.strategyKind).toBe("media-stream-custom");
+    expect(entry?.telephonyRouting.twilioNativeMapping).toBeUndefined();
+  });
+
+  // -----------------------------------------------------------------------
+  // Credential lookup
+  // -----------------------------------------------------------------------
+
+  test("getCredentialProvider returns correct mapping", () => {
+    expect(getCredentialProvider("openai-whisper")).toBe("openai");
+    expect(getCredentialProvider("deepgram")).toBe("deepgram");
+    expect(getCredentialProvider("google-gemini")).toBe("gemini");
+  });
+
+  test("getCredentialProvider returns undefined for unknown ID", () => {
+    expect(getCredentialProvider("nonexistent" as never)).toBeUndefined();
+  });
+
+  // -----------------------------------------------------------------------
+  // Speaker diarization capability
+  // -----------------------------------------------------------------------
+
+  test("supportsDiarization is set as a boolean for every entry", () => {
+    for (const entry of listProviderEntries()) {
+      expect(typeof entry.supportsDiarization).toBe("boolean");
+    }
+  });
+
+  test("deepgram supportsDiarization is true", () => {
+    const entry = getProviderEntry("deepgram");
+    expect(entry?.supportsDiarization).toBe(true);
+  });
+
+  test("google-gemini supportsDiarization is false", () => {
+    const entry = getProviderEntry("google-gemini");
+    expect(entry?.supportsDiarization).toBe(false);
+  });
+
+  test("openai-whisper supportsDiarization is false", () => {
+    const entry = getProviderEntry("openai-whisper");
+    expect(entry?.supportsDiarization).toBe(false);
+  });
+
+  test("supportsDiarization helper returns expected booleans per provider", () => {
+    expect(supportsDiarization("deepgram")).toBe(true);
+    expect(supportsDiarization("google-gemini")).toBe(false);
+    expect(supportsDiarization("openai-whisper")).toBe(false);
+  });
+
+  test("supportsDiarization helper returns false for unknown provider IDs", () => {
+    expect(supportsDiarization("nonexistent" as never)).toBe(false);
+  });
+});