@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/calls/telephony-credential-preflight.ts

@@ -0,0 +1,159 @@
+/**
+ * Telephony credential-readiness preflight.
+ *
+ * Transport contract: the daemon performs both telephony legs itself —
+ * Twilio only carries mu-law audio frames — so a call can only work when
+ * the user holds credentials for a telephony-capable STT provider AND a
+ * media-stream-playable TTS provider (the configured one, or a
+ * credentialed playable fallback from the catalog).
+ *
+ * This resolver combines the two capability resolvers into a single
+ * ready / not-ready verdict with a user-facing message suitable for both a
+ * call-tool error result and TwiML <Say> copy. It creates no provider
+ * instances and performs no call-site wiring — callers gate outbound call
+ * placement and inbound TwiML on the verdict.
+ */
+
+import { getConfig } from "../config/loader.js";
+import type { TelephonySttCapability } from "../providers/speech-to-text/resolve.js";
+import { resolveTelephonySttCapability } from "../providers/speech-to-text/resolve.js";
+import { findPlayableTelephonyTtsFallback } from "./resolve-call-tts-provider.js";
+import type { TelephonyTtsNotPlayableReason } from "./telephony-tts-capability.js";
+import { resolveTelephonyTtsCapability } from "./telephony-tts-capability.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** A single credential/capability gap blocking telephony readiness. */
+export interface TelephonyCredentialGap {
+  kind: "stt" | "tts";
+  providerId: string;
+  reason: string;
+}
+
+/** Result of resolving whether telephony STT+TTS credentials are in order. */
+export type TelephonyCredentialReadiness =
+  | { status: "ready" }
+  | {
+      status: "not-ready";
+      missing: TelephonyCredentialGap[];
+      /**
+       * A single human-readable sentence naming the offending provider(s)
+       * and missing credential(s), suitable for both a tool error result
+       * and TwiML <Say> copy.
+       */
+      userMessage: string;
+    };
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve whether the daemon can run both legs of a phone call.
+ *
+ * Readiness requires:
+ * - STT: `resolveTelephonySttCapability()` returns `"supported"`.
+ * - TTS: `resolveTelephonyTtsCapability()` returns `"playable"`, or a
+ *   credentialed playable fallback provider exists
+ *   ({@link findPlayableTelephonyTtsFallback}) — the call TTS resolver
+ *   swaps in that fallback at synthesis time, so readiness is satisfied
+ *   even when the configured provider is not playable.
+ */
+export async function resolveTelephonyCredentialReadiness(): Promise<TelephonyCredentialReadiness> {
+  const [stt, tts] = await Promise.all([
+    resolveTelephonySttCapability(),
+    resolveTelephonyTtsCapability(),
+  ]);
+
+  const missing: TelephonyCredentialGap[] = [];
+  const clauses: string[] = [];
+
+  if (stt.status !== "supported") {
+    const providerId =
+      "providerId" in stt ? stt.providerId : getConfig().services.stt.provider;
+    missing.push({ kind: "stt", providerId, reason: stt.reason });
+    clauses.push(sttGapClause(stt, providerId));
+  }
+
+  if (tts.status === "not-playable") {
+    const fallbackId = await findPlayableTelephonyTtsFallback(tts.providerId);
+    if (!fallbackId) {
+      const { gap, clause } = ttsGap(tts.providerId, tts.reason);
+      missing.push(gap);
+      clauses.push(clause);
+    }
+  }
+
+  if (missing.length === 0) {
+    return { status: "ready" };
+  }
+
+  return {
+    status: "not-ready",
+    missing,
+    userMessage: `Phone calls are unavailable because they require ${clauses.join(" and ")}.`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** User-message clause for an STT capability gap. */
+function sttGapClause(
+  capability: Exclude<TelephonySttCapability, { status: "supported" }>,
+  providerId: string,
+): string {
+  switch (capability.status) {
+    case "missing-credentials": {
+      return `an API key for the speech-to-text provider "${providerId}"`;
+    }
+    case "unsupported": {
+      return `a speech-to-text provider that supports phone calls (the configured "${providerId}" does not)`;
+    }
+    case "unconfigured": {
+      return `a recognized speech-to-text provider (the configured "${providerId}" is not in the provider catalog)`;
+    }
+  }
+}
+
+/** Gap entry and user-message clause for a TTS playability gap with no usable fallback. */
+function ttsGap(
+  providerId: string,
+  reason: TelephonyTtsNotPlayableReason,
+): { gap: TelephonyCredentialGap; clause: string } {
+  switch (reason) {
+    case "missing-credentials": {
+      return {
+        gap: {
+          kind: "tts",
+          providerId,
+          reason: `TTS provider "${providerId}" is missing credentials and no playable fallback provider is available`,
+        },
+        clause: `an API key for the text-to-speech provider "${providerId}" (no fallback provider has usable credentials)`,
+      };
+    }
+    case "missing-fish-audio-reference-id": {
+      return {
+        gap: {
+          kind: "tts",
+          providerId,
+          reason: `TTS provider "${providerId}" has no Fish Audio reference ID configured (services.tts.providers.fish-audio.referenceId) and no playable fallback provider is available`,
+        },
+        clause: `a Fish Audio voice reference ID for the text-to-speech provider "${providerId}" (set services.tts.providers.fish-audio.referenceId; no fallback provider is usable)`,
+      };
+    }
+    case "unsupported-format": {
+      return {
+        gap: {
+          kind: "tts",
+          providerId,
+          reason: `TTS provider "${providerId}" cannot produce media-stream-playable audio and no playable fallback provider is available`,
+        },
+        clause: `a text-to-speech provider that can produce call audio (the configured "${providerId}" cannot, and no fallback provider is usable)`,
+      };
+    }
+  }
+}

package/src/calls/telephony-tts-capability.ts

@@ -0,0 +1,183 @@
+/**
+ * Telephony TTS playability capability resolver.
+ *
+ * Validates whether a TTS provider can produce audio that is actually
+ * playable over the media-stream call transport. Playability requires:
+ *
+ * 1. The catalog entry's `mediaStreamPlayback.outputFormat` is `"pcm"` or
+ *    `"wav"` — the media-stream mu-law transcoder cannot decode compressed
+ *    formats (mp3, opus).
+ * 2. Every secret the catalog entry requires resolves to a value.
+ * 3. Provider-specific config invariants hold — Fish Audio requires a
+ *    configured `referenceId` (no per-request voiceId is supplied on the
+ *    telephony path), so a referenceId-less fish-audio setup synthesizes
+ *    nothing and is not playable.
+ *
+ * This resolver does **not** create a provider instance — it only validates
+ * catalog metadata and credentials, mirroring `resolveTelephonySttCapability`
+ * in `providers/speech-to-text/resolve.ts`. Credential lookup is centralized
+ * here (an authorized secure-keys importer) so callers don't need to import
+ * secure-keys directly.
+ */
+
+import { getConfig } from "../config/loader.js";
+import {
+  getProviderKeyAsync,
+  getSecureKeyAsync,
+} from "../security/secure-keys.js";
+import type { TtsProviderCatalogEntry } from "../tts/provider-catalog.js";
+import { getCatalogProvider } from "../tts/provider-catalog.js";
+import { resolveTtsConfig } from "../tts/tts-config-resolver.js";
+import type { TtsProviderId } from "../tts/types.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Why a provider cannot play over media-stream transports. */
+export type TelephonyTtsNotPlayableReason =
+  | "unsupported-format"
+  | "missing-credentials"
+  | "missing-fish-audio-reference-id";
+
+/**
+ * Result of resolving whether a TTS provider is playable over the
+ * media-stream call transport.
+ */
+export type TelephonyTtsCapability =
+  | {
+      /** The provider produces playable audio and credentials resolve. */
+      status: "playable";
+      providerId: TtsProviderId;
+    }
+  | {
+      /** The provider cannot play over media-stream transports. */
+      status: "not-playable";
+      providerId: TtsProviderId;
+      reason: TelephonyTtsNotPlayableReason;
+    };
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate whether the configured `services.tts.provider` is playable over
+ * the media-stream call transport.
+ *
+ * Callers can branch on the discriminated `status` field:
+ * - `"playable"` — the provider produces PCM/WAV and credentials resolve.
+ * - `"not-playable"` — see `reason` (`"unsupported-format"` when the
+ *   provider is unknown or only produces compressed audio,
+ *   `"missing-credentials"` when a required secret does not resolve,
+ *   `"missing-fish-audio-reference-id"` when fish-audio has no configured
+ *   `referenceId`).
+ */
+export async function resolveTelephonyTtsCapability(): Promise<TelephonyTtsCapability> {
+  const { provider } = resolveTtsConfig(getConfig());
+  return evaluateTelephonyTtsPlayability(provider);
+}
+
+/**
+ * Evaluate media-stream playability for a specific catalog provider.
+ *
+ * Shared by {@link resolveTelephonyTtsCapability} (configured provider) and
+ * the call TTS resolver's fallback scan (candidate providers).
+ */
+export async function evaluateTelephonyTtsPlayability(
+  providerId: TtsProviderId,
+): Promise<TelephonyTtsCapability> {
+  let entry: TtsProviderCatalogEntry;
+  try {
+    entry = getCatalogProvider(providerId);
+  } catch {
+    // Unknown providers have no declared playable format.
+    return { status: "not-playable", providerId, reason: "unsupported-format" };
+  }
+
+  if (entry.mediaStreamPlayback.outputFormat === "none") {
+    return {
+      status: "not-playable",
+      providerId: entry.id,
+      reason: "unsupported-format",
+    };
+  }
+
+  for (const secret of entry.secretRequirements) {
+    if (!(await secretResolves(secret.credentialStoreKey))) {
+      return {
+        status: "not-playable",
+        providerId: entry.id,
+        reason: "missing-credentials",
+      };
+    }
+  }
+
+  if (entry.id === "fish-audio" && !fishAudioReferenceIdConfigured()) {
+    return {
+      status: "not-playable",
+      providerId: entry.id,
+      reason: "missing-fish-audio-reference-id",
+    };
+  }
+
+  return { status: "playable", providerId: entry.id };
+}
+
+/**
+ * Whether the fish-audio `referenceId` is configured.
+ *
+ * Single source of truth for the fish-audio usability invariant: the
+ * telephony path supplies no per-request voiceId, so synthesis requires a
+ * configured reference ID. Shared by {@link evaluateTelephonyTtsPlayability}
+ * and the call TTS resolver's non-WAV degrade path.
+ *
+ * When fish-audio is the active `services.tts.provider`, its config is
+ * read through the {@link resolveTtsConfig} provider-options layer — the
+ * same path the call TTS resolver has always used. When fish-audio is only
+ * a fallback candidate, the canonical `services.tts.providers.fish-audio`
+ * block is read directly.
+ */
+export function fishAudioReferenceIdConfigured(): boolean {
+  try {
+    const config = getConfig();
+    const resolved = resolveTtsConfig(config);
+    const providerConfig =
+      resolved.provider === "fish-audio"
+        ? resolved.providerConfig
+        : (
+            config.services?.tts?.providers as
+              | Record<string, unknown>
+              | undefined
+          )?.["fish-audio"];
+    return Boolean(
+      (
+        providerConfig as { referenceId?: string } | undefined
+      )?.referenceId?.trim(),
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a catalog `credentialStoreKey` resolves to a value.
+ *
+ * API keys (`credential/{service}/api_key` or a bare service name) go
+ * through `getProviderKeyAsync` so env-var-only setups are honoured;
+ * other namespaced fields are looked up verbatim.
+ */
+async function secretResolves(credentialStoreKey: string): Promise<boolean> {
+  const parts = credentialStoreKey.split("/");
+  if (parts.length === 1) {
+    return Boolean(await getProviderKeyAsync(credentialStoreKey));
+  }
+  if (parts.length === 3 && parts[0] === "credential" && parts[2] === "api_key") {
+    return Boolean(await getProviderKeyAsync(parts[1]));
+  }
+  return Boolean(await getSecureKeyAsync(credentialStoreKey));
+}

package/src/calls/tts-call-strategy.ts

@@ -1,25 +1,24 @@
 /**
  * Explicit call-path strategy for TTS providers.
  *
- * Determines how a TTS provider integrates with the Twilio
- * ConversationRelay call path by reading the provider's `callMode` from
- * the canonical catalog rather than inferring behavior from runtime
- * capabilities like `supportsStreaming`.
+ * Determines how a TTS provider integrates with the telephony call path
+ * by reading the provider's `callMode` from the canonical catalog rather
+ * than inferring behavior from runtime capabilities like
+ * `supportsStreaming`.
  *
  * Two strategies exist:
  *
- * - **native-twilio** -- Twilio handles TTS natively via
- *   ConversationRelay. The profile needs a real `ttsProvider` name
- *   (e.g. `"ElevenLabs"`) and a provider-specific voice spec string.
- *   New native providers plug in by registering a
- *   {@link NativeTwilioVoiceSpecBuilder} -- no edits to the core call
- *   routing logic required.
+ * - **native-twilio** -- the text-token path: spoken text is sent via
+ *   `sendTextToken()`, which the media-stream transport re-synthesizes
+ *   through daemon TTS. The profile carries a real `ttsProvider` name
+ *   (e.g. `"ElevenLabs"`) and a provider-specific voice spec string built
+ *   by a registered {@link NativeTwilioVoiceSpecBuilder}.
  *
- * - **synthesized-play** -- The assistant synthesises audio and streams
- *   chunks to Twilio via `play` messages, so Twilio does not drive TTS on
- *   the happy path. The profile still carries a valid native fallback voice
+ * - **synthesized-play** -- The assistant synthesises audio via the
+ *   provider API and streams it through the audio store / `sendPlayUrl()`
+ *   path. The profile still carries a valid native fallback voice
  *   (see `resolveVoiceQualityProfile`) so a mid-call synthesis failure can
- *   degrade to native token TTS instead of being rejected with error 64106.
+ *   degrade to the text-token path.
  *
  * @module
  */
@@ -37,15 +36,14 @@ import type { TtsCallMode, TtsProviderId } from "../tts/types.js";
  * Builds the provider-specific voice spec string for a native Twilio
  * provider.
  *
- * The returned string is used as the `voice` attribute in the
- * ConversationRelay TwiML element. Its format is provider-specific --
- * e.g. ElevenLabs uses `voiceId-modelId-speed_stability_similarity`.
+ * The returned string is used as Twilio's TTS `voice` attribute. Its
+ * format is provider-specific -- e.g. ElevenLabs uses
+ * `voiceId-modelId-speed_stability_similarity`.
  *
  * @param providerConfig - Provider-specific config block from
  *   `services.tts.providers.<id>`.
- * @returns The voice spec string for the ConversationRelay `voice`
- *   attribute, or an empty string if the provider has no voice to
- *   specify.
+ * @returns The voice spec string for Twilio's TTS `voice` attribute, or
+ *   an empty string if the provider has no voice to specify.
  */
 export type NativeTwilioVoiceSpecBuilder = (
   providerConfig: Record<string, unknown>,

package/src/calls/twilio-provider.ts

@@ -14,12 +14,13 @@ import type { InitiateCallOptions, VoiceProvider } from "./voice-provider.js";
 const log = getLogger("twilio-provider");
 
 /**
- * Twilio ConversationRelay voice provider.
+ * Twilio voice provider: outbound REST dialing, call status/teardown,
+ * caller-ID eligibility checks, and webhook signature validation.
  *
  * Uses the Twilio REST API directly via fetch() — no twilio npm package.
  * Credentials are resolved lazily from config on each call.
  */
-export class TwilioConversationRelayProvider implements VoiceProvider {
+export class TwilioVoiceProvider implements VoiceProvider {
   readonly name = "twilio";
 
   // ── Credential helpers ──────────────────────────────────────────────