@vellumai/assistant 0.6.3 → 0.6.4

package/src/calls/telephony-stt-routing.ts

@@ -0,0 +1,145 @@
+/**
+ * Telephony STT routing resolver.
+ *
+ * Maps the `services.stt.provider` value to a discriminated telephony
+ * setup strategy that downstream TwiML generation and media-stream
+ * adapters can consume without re-deriving provider semantics.
+ *
+ * Two strategy variants exist:
+ *
+ * - **`conversation-relay-native`** — the STT provider is natively
+ *   supported by Twilio ConversationRelay. TwiML includes
+ *   `transcriptionProvider` / `speechModel` attributes and Twilio
+ *   handles audio ingestion. Used for `deepgram` and `google-gemini`.
+ *
+ * - **`media-stream-custom`** — the STT provider is not natively
+ *   supported by Twilio. A `<Stream>` media-stream is opened instead
+ *   and the daemon transcribes audio server-side via the provider's
+ *   batch API. Used for `openai-whisper`.
+ *
+ * Strategy selection and model normalization are driven entirely by
+ * the provider catalog's `telephonyRouting` metadata — this module
+ * contains no hardcoded provider-to-Twilio maps.
+ */
+
+import { getConfig } from "../config/loader.js";
+import {
+  getProviderEntry,
+  type TwilioNativeProvider,
+} from "../providers/speech-to-text/provider-catalog.js";
+import type { SttProviderId } from "../stt/types.js";
+
+// ---------------------------------------------------------------------------
+// Strategy types
+// ---------------------------------------------------------------------------
+
+/**
+ * Twilio-native ConversationRelay transcription provider name.
+ *
+ * Re-exported from the provider catalog for downstream consumers that
+ * reference the strategy types without importing the catalog directly.
+ */
+export type TwilioNativeTranscriptionProvider = TwilioNativeProvider;
+
+/**
+ * The configured STT provider maps to a Twilio-native
+ * ConversationRelay transcription path.
+ */
+export interface ConversationRelayNativeStrategy {
+  readonly strategy: "conversation-relay-native";
+  /** Provider ID from `services.stt.provider`. */
+  readonly providerId: SttProviderId;
+  /** Twilio-native provider name for the TwiML attribute. */
+  readonly transcriptionProvider: TwilioNativeTranscriptionProvider;
+  /** ASR model identifier, or undefined to use the provider default. */
+  readonly speechModel: string | undefined;
+}
+
+/**
+ * The configured STT provider requires a media-stream for custom
+ * server-side transcription.
+ */
+export interface MediaStreamCustomStrategy {
+  readonly strategy: "media-stream-custom";
+  /** Provider ID from `services.stt.provider`. */
+  readonly providerId: SttProviderId;
+}
+
+/**
+ * Discriminated union of telephony setup strategies.
+ */
+export type TelephonySttStrategy =
+  | ConversationRelayNativeStrategy
+  | MediaStreamCustomStrategy;
+
+/**
+ * Result of resolving a telephony STT routing decision.
+ *
+ * - `resolved` — the provider was recognized and a strategy was determined.
+ * - `unknown-provider` — the provider ID is not in the catalog or has no
+ *   telephony routing mapping.
+ */
+export type TelephonySttRoutingResult =
+  | { status: "resolved"; strategy: TelephonySttStrategy }
+  | { status: "unknown-provider"; providerId: string; reason: string };
+
+// ---------------------------------------------------------------------------
+// Public resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the telephony STT routing strategy from `services.stt.provider`.
+ *
+ * Reads the active provider from config, checks the provider catalog for
+ * validity, then derives the telephony strategy from the catalog entry's
+ * `telephonyRouting` metadata.
+ */
+export function resolveTelephonySttRouting(): TelephonySttRoutingResult {
+  const config = getConfig();
+  const providerId = config.services.stt.provider;
+
+  // Validate the provider exists in the catalog.
+  const entry = getProviderEntry(providerId as SttProviderId);
+  if (!entry) {
+    return {
+      status: "unknown-provider",
+      providerId,
+      reason: `STT provider "${providerId}" is not in the provider catalog`,
+    };
+  }
+
+  const { telephonyRouting } = entry;
+
+  // Derive strategy from catalog routing metadata.
+  if (telephonyRouting.strategyKind === "conversation-relay-native") {
+    const mapping = telephonyRouting.twilioNativeMapping;
+
+    // Defensive: conversation-relay-native entries must have a mapping.
+    if (!mapping) {
+      return {
+        status: "unknown-provider",
+        providerId: entry.id,
+        reason: `Provider "${entry.id}" declares conversation-relay-native strategy but has no twilioNativeMapping`,
+      };
+    }
+
+    return {
+      status: "resolved",
+      strategy: {
+        strategy: "conversation-relay-native",
+        providerId: entry.id,
+        transcriptionProvider: mapping.provider,
+        speechModel: mapping.defaultSpeechModel,
+      },
+    };
+  }
+
+  // media-stream-custom path.
+  return {
+    status: "resolved",
+    strategy: {
+      strategy: "media-stream-custom",
+      providerId: entry.id,
+    },
+  };
+}

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

@@ -0,0 +1,161 @@
+/**
+ * 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`.
+ *
+ * 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.
+ *
+ * - **synthesized-play** -- The assistant synthesises audio and streams
+ *   chunks to Twilio via `play` messages. The profile uses a
+ *   placeholder TTS provider (`"Google"`) and an empty voice string
+ *   because Twilio never drives TTS itself on this path.
+ *
+ * @module
+ */
+
+import type { AssistantConfig } from "../config/types.js";
+import { getCatalogProvider } from "../tts/provider-catalog.js";
+import { resolveTtsConfig } from "../tts/tts-config-resolver.js";
+import type { TtsCallMode, TtsProviderId } from "../tts/types.js";
+
+// ---------------------------------------------------------------------------
+// Native Twilio voice-spec builder registry
+// ---------------------------------------------------------------------------
+
+/**
+ * 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`.
+ *
+ * @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.
+ */
+export type NativeTwilioVoiceSpecBuilder = (
+  providerConfig: Record<string, unknown>,
+) => string;
+
+/**
+ * Metadata returned by a native Twilio voice-spec builder registration.
+ */
+export interface NativeTwilioVoiceSpec {
+  /** The Twilio `ttsProvider` attribute value (e.g. `"ElevenLabs"`). */
+  readonly twilioProviderName: string;
+
+  /** Builds the `voice` attribute string from provider config. */
+  readonly buildVoiceSpec: NativeTwilioVoiceSpecBuilder;
+}
+
+/** Internal registry keyed by provider ID. */
+const nativeVoiceSpecRegistry = new Map<TtsProviderId, NativeTwilioVoiceSpec>();
+
+/**
+ * Register a native Twilio voice-spec builder for a provider.
+ *
+ * Called at startup alongside provider adapter registration. This is
+ * the extension point that allows new native Twilio providers to be
+ * added without modifying core call routing logic.
+ *
+ * @throws if a builder for the same provider ID is already registered.
+ */
+export function registerNativeTwilioVoiceSpec(
+  providerId: TtsProviderId,
+  spec: NativeTwilioVoiceSpec,
+): void {
+  if (nativeVoiceSpecRegistry.has(providerId)) {
+    throw new Error(
+      `Native Twilio voice spec for "${providerId}" is already registered. ` +
+        "Duplicate registrations are not allowed.",
+    );
+  }
+  nativeVoiceSpecRegistry.set(providerId, spec);
+}
+
+/**
+ * Look up a registered native Twilio voice-spec builder.
+ *
+ * @throws if no builder has been registered for the given provider.
+ */
+export function getNativeTwilioVoiceSpec(
+  providerId: TtsProviderId,
+): NativeTwilioVoiceSpec {
+  const spec = nativeVoiceSpecRegistry.get(providerId);
+  if (!spec) {
+    const known = [...nativeVoiceSpecRegistry.keys()];
+    const knownList =
+      known.length > 0 ? ` Registered: ${known.join(", ")}` : "";
+    throw new Error(
+      `No native Twilio voice spec registered for "${providerId}".${knownList}`,
+    );
+  }
+  return spec;
+}
+
+// ---------------------------------------------------------------------------
+// Strategy resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolved call strategy for the active TTS provider.
+ */
+export interface TtsCallStrategy {
+  /** The provider ID from the catalog. */
+  readonly providerId: TtsProviderId;
+
+  /** How this provider integrates with the telephony call path. */
+  readonly callMode: TtsCallMode;
+}
+
+/**
+ * Resolve the call strategy for the currently configured TTS provider.
+ *
+ * Reads the active provider from config via {@link resolveTtsConfig},
+ * then looks up the provider's `callMode` in the catalog.
+ *
+ * Falls back to `native-twilio` with `"elevenlabs"` when the config
+ * or catalog is unavailable (e.g. test mocks, pre-migration configs).
+ */
+export function resolveCallStrategy(config: AssistantConfig): TtsCallStrategy {
+  try {
+    const resolved = resolveTtsConfig(config);
+    const catalogEntry = getCatalogProvider(resolved.provider);
+    return {
+      providerId: catalogEntry.id,
+      callMode: catalogEntry.callMode,
+    };
+  } catch {
+    // Config or catalog not available -- default to native ElevenLabs path.
+    return {
+      providerId: "elevenlabs",
+      callMode: "native-twilio",
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Clear all registered native Twilio voice spec builders.
+ *
+ * **Test-only** -- must not be called in production code.
+ */
+export function _resetNativeTwilioVoiceSpecRegistry(): void {
+  nativeVoiceSpecRegistry.clear();
+}

package/src/calls/tts-text-sanitizer.ts

@@ -10,9 +10,10 @@ export function sanitizeForTts(text: string): string {
   // 1. Markdown links: [text](url) → text
   //    Only matches the full [...](...) pattern — plain brackets like
   //    Fish Audio S2 annotations ([laughter], [breath]) pass through.
-  //    Handles one level of balanced parentheses in URLs (e.g. Wikipedia links).
+  //    Handles multiple balanced parentheses groups in URLs (e.g. Wikipedia
+  //    links, URL-encoded paths with multiple `(...)` segments).
   result = result.replace(
-    /\[([^\]]+)\]\([^()]*(?:\([^()]*\))*[^()]*\)/g,
+    /\[([^\]]+)\]\((?:[^()]*\([^()]*\))*[^()]*\)/g,
     "$1",
   );
 
@@ -24,36 +25,51 @@ export function sanitizeForTts(text: string): string {
   result = result.replace(/\*{2}(.+?)\*{2}/g, "$1");
   result = result.replace(/_{2}(.+?)_{2}/g, "$1");
 
-  // 4. Code fences: strip ```...``` fences but keep content
-  //    Must run before header stripping so # comments inside code blocks are preserved.
-  result = result.replace(/```[^\n]*\n([\s\S]*?)```\n?/g, "$1");
+  // 4. Code fences + headers: strip ```...``` fences keeping content, and
+  //    strip leading `#` header characters at line starts — but ONLY outside
+  //    code fences so `# comment` / `## comment` lines inside code blocks are
+  //    preserved verbatim.
+  {
+    const fenceRe = /(```[^\n]*\n[\s\S]*?```\n?)/g;
+    const parts = result.split(fenceRe);
+    for (let i = 0; i < parts.length; i++) {
+      if (i % 2 === 0) {
+        // Non-fence segment: strip headers.
+        parts[i] = parts[i].replace(/^#{1,6}\s+/gm, "");
+      } else {
+        // Fence segment: strip the ``` markers but keep content untouched.
+        parts[i] = parts[i].replace(
+          /```[^\n]*\n([\s\S]*?)```\n?/,
+          "$1",
+        );
+      }
+    }
+    result = parts.join("");
+  }
 
-  // 5. Headers: strip leading # characters at line starts
-  result = result.replace(/^#{1,6}\s+/gm, "");
-
-  // 6. Inline code: strip single backticks
+  // 5. Inline code: strip single backticks
   result = result.replace(/`([^`]+)`/g, "$1");
 
-  // 7. Bullet markers: strip `- ` or `* ` at line starts
+  // 6. Bullet markers: strip `- ` or `* ` at line starts
   //    Must run before italic stripping so `* item` is treated as a bullet.
   result = result.replace(/^[-*]\s+/gm, "");
 
-  // 8. Italic: *text* or _text_ → text
+  // 7. Italic: *text* or _text_ → text
   //    Word-boundary-aware to preserve arithmetic like `5 * 3` and identifiers like `my_var`.
   result = result.replace(/(?<!\w)\*([^*]+)\*(?!\w)/g, "$1");
   result = result.replace(/(?<!\w)_([^_]+)_(?!\w)/g, "$1");
 
-  // 9. Emojis: strip extended pictographic characters, variation selectors,
+  // 8. Emojis: strip extended pictographic characters, variation selectors,
   //    zero-width joiners, skin tone modifiers, and regional indicator symbols (flags).
   result = result.replace(/[\u200D\uFE00-\uFE0F]/gu, "");
   result = result.replace(/[\u{1F3FB}-\u{1F3FF}]/gu, "");
   result = result.replace(/\p{Extended_Pictographic}/gu, "");
   result = result.replace(/[\u{1F1E6}-\u{1F1FF}]/gu, "");
 
-  // 10. Collapse whitespace: multiple spaces → single space,
-  //     multiple blank lines → single newline.
-  //     Does NOT trim trailing whitespace — callers handle trimming so that
-  //     streaming chunks preserve inter-word spaces (e.g. "Hello " + "world").
+  // 9. Collapse whitespace: multiple spaces → single space,
+  //    multiple blank lines → single newline.
+  //    Does NOT trim trailing whitespace — callers handle trimming so that
+  //    streaming chunks preserve inter-word spaces (e.g. "Hello " + "world").
   result = result.replace(/ {2,}/g, " ");
   result = result.replace(/\n{3,}/g, "\n\n");