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

package/src/calls/relay-setup-router.ts

@@ -1,16 +1,14 @@
 /**
- * Pure routing logic extracted from RelayConnection.handleSetup.
+ * Pure routing logic for the voice call setup phase.
  *
  * Given a setup context (call session, actor trust, voice config, ACL policy),
- * returns a discriminated union describing what the relay connection should do
+ * returns a discriminated union describing what the call session should do
  * next — without performing any side effects itself.
  */
 
 import type { AdmissionPolicy, TrustVerdict } from "@vellumai/gateway-client";
 
 import { getConfig } from "../config/loader.js";
-import { getContact } from "../contacts/contact-store.js";
-import { findActiveVoiceInvites } from "../persistence/invite-store.js";
 import {
   type ActorTrustContext,
   resolveActorTrust,
@@ -26,6 +24,7 @@ import {
   verdictMemberUnresolvable,
 } from "../runtime/trust-verdict-consumer.js";
 import { getLogger } from "../util/logger.js";
+import { getActiveVoiceInvite } from "./gateway-invite-reader.js";
 import type { CallSession } from "./types.js";
 
 const log = getLogger("relay-setup-router");
@@ -54,7 +53,7 @@ interface SetupContext {
 
 // ── Setup outcomes ───────────────────────────────────────────────────
 
-type SetupOutcome =
+export type SetupOutcome =
   | { action: "normal_call"; isInbound: boolean }
   | {
       action: "verification";
@@ -76,9 +75,9 @@ type SetupOutcome =
       assistantId: string;
       fromNumber: string;
       /**
-       * Display name of the invitee. For inbound redemptions, resolved from the
-       * bound contact's `displayName`; falls back to the legacy `friend_name`
-       * column for pre-contact-binding invites. For outbound invite calls,
+       * Display name of the invitee. For inbound redemptions, supplied by the
+       * gateway's active-voice-invite read (bound contact `displayName`
+       * preferred, invite `friendName` fallback). For outbound invite calls,
        * carries the session-recorded `inviteFriendName`. When null/empty, the
        * relay uses a neutral "Hi there" greeting instead of substituting the
        * channel address.
@@ -107,17 +106,18 @@ export interface SetupResolved {
 // ── Router ───────────────────────────────────────────────────────────
 
 /**
- * Determine the setup outcome for an incoming relay connection.
+ * Determine the setup outcome for a starting call session.
  *
- * This function is pure routing logic — it reads state but performs no
- * side effects (no call-session mutations, no event recording, no WS
- * messages). The caller (`RelayConnection.handleSetup`) is responsible
- * for acting on the returned outcome.
+ * This function is pure routing logic — it reads state (including the
+ * gateway's active-voice-invite view) but performs no side effects (no
+ * call-session mutations, no event recording, no WS messages). The caller
+ * (the media-stream server's start handler) is responsible for acting on
+ * the returned outcome.
  */
-export function routeSetup(ctx: SetupContext): {
+export async function routeSetup(ctx: SetupContext): Promise<{
   outcome: SetupOutcome;
   resolved: SetupResolved;
-} {
+}> {
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
   const isInbound = ctx.session?.initiatedFromConversationId == null;
   const otherPartyNumber = isInbound ? ctx.from : ctx.to;
@@ -302,44 +302,23 @@ export function routeSetup(ctx: SetupContext): {
       };
     }
 
-    // Check for active voice invites
-    let voiceInvites: ReturnType<typeof findActiveVoiceInvites> = [];
-    try {
-      voiceInvites = findActiveVoiceInvites({
-        expectedExternalUserId: ctx.from,
-      });
-    } catch (err) {
-      log.warn(
-        { err, callSessionId: ctx.callSessionId },
-        "Failed to check voice invites for unknown caller",
-      );
-    }
-
-    const now = Date.now();
-    const nonExpiredInvites = voiceInvites.filter(
-      (i) => !i.expiresAt || i.expiresAt > now,
-    );
+    // Check for an active voice invite. The gateway row is the lifecycle
+    // authority; the reader fails soft to `null` on any gateway failure, so a
+    // gateway blip falls through to the unverified-caller flows below instead
+    // of stalling setup.
+    const voiceInvite = await getActiveVoiceInvite(ctx.from);
 
-    if (nonExpiredInvites.length > 0) {
-      const matchedInvite = nonExpiredInvites[0];
+    if (voiceInvite) {
       log.info(
         { callSessionId: ctx.callSessionId, from: ctx.from },
         "Inbound voice ACL: unknown caller has active voice invite — entering redemption flow",
       );
-      // Resolve the invitee's name from the bound contact's displayName so
-      // the post-redemption greeting matches what the guardian sees in the
-      // contact graph. `contact_id` is NOT NULL on the invite row, so every
-      // invite is bound — when the contact has no displayName the greeting
-      // falls through to the neutral "Hi there" copy in relay-server.ts
-      // rather than a stale free-text `friend_name` label.
-      const boundContact = getContact(matchedInvite.contactId);
-      const inviteeName = boundContact?.displayName?.trim() || null;
       return {
         outcome: {
           action: "invite_redemption",
           assistantId,
           fromNumber: ctx.from,
-          inviteeName: inviteeName ?? null,
+          inviteeName: voiceInvite.inviteeName,
         },
         resolved,
       };

package/src/calls/relay-verification.ts

@@ -1,10 +1,10 @@
 /**
- * Extracted verification logic for the ConversationRelay voice pipeline.
+ * Verification logic for the voice call setup pipeline.
  *
  * These pure-ish functions encapsulate the decision-making for guardian code
- * verification and invite code redemption without directly mutating relay
- * connection state. They return structured result objects that the caller
- * (RelayConnection) interprets to drive side-effects (TTS, session updates,
+ * verification and invite code redemption without mutating call-session
+ * state. They return structured result objects that the caller
+ * (CallSetupFlow) interprets to drive side-effects (TTS, session updates,
  * timer scheduling, etc.).
  */
 
@@ -12,11 +12,11 @@ import {
   getGuardianBinding,
   validateAndConsumeVerification,
 } from "../runtime/channel-verification-service.js";
-import { redeemVoiceInviteCode } from "../runtime/invite-service.js";
 import {
   composeVerificationVoice,
   GUARDIAN_VERIFY_TEMPLATE_KEYS,
 } from "../runtime/verification-templates.js";
+import { redeemVoiceInviteViaGateway } from "./gateway-invite-reader.js";
 import type { CallEventType } from "./types.js";
 
 // ── parseDigitsFromSpeech ──────────────────────────────────────────────
@@ -221,7 +221,6 @@ export async function attemptVerificationCode(
 // ── Invite code redemption ─────────────────────────────────────────────
 
 interface InviteRedemptionParams {
-  inviteRedemptionAssistantId: string;
   inviteRedemptionFromNumber: string;
   enteredCode: string;
   /** Resolved guardian label used in the failure TTS message. */
@@ -233,7 +232,7 @@ type InviteRedemptionResult =
       outcome: "success";
       memberId: string;
       type: "redeemed" | "already_member";
-      inviteId?: string;
+      inviteId: string;
     }
   | {
       outcome: "failure";
@@ -241,33 +240,27 @@ type InviteRedemptionResult =
     };
 
 /**
- * Validate an entered invite code against active voice invites for the
- * caller. Returns a structured result so the caller can handle state
- * mutations and session updates.
+ * Redeem an entered invite code for the caller at the gateway — the single
+ * lifecycle authority for voice invites. Fails CLOSED: any gateway failure is
+ * the generic failure outcome with no local fallback. Returns a structured
+ * result so the caller can handle state mutations and session updates.
  */
 export async function attemptInviteCodeRedemption(
   params: InviteRedemptionParams,
 ): Promise<InviteRedemptionResult> {
-  const {
-    inviteRedemptionAssistantId,
+  const { inviteRedemptionFromNumber, enteredCode, guardianLabel } = params;
+
+  const result = await redeemVoiceInviteViaGateway(
     inviteRedemptionFromNumber,
     enteredCode,
-    guardianLabel,
-  } = params;
-
-  const result = await redeemVoiceInviteCode({
-    assistantId: inviteRedemptionAssistantId,
-    callerExternalUserId: inviteRedemptionFromNumber,
-    sourceChannel: "phone",
-    code: enteredCode,
-  });
+  );
 
   if (result.ok) {
     return {
       outcome: "success",
-      memberId: result.memberId,
-      type: result.type,
-      ...(result.type === "redeemed" ? { inviteId: result.inviteId } : {}),
+      memberId: result.outcome.contactId,
+      type: result.outcome.result,
+      inviteId: result.outcome.inviteId,
     };
   }
 

package/src/calls/resolve-call-tts-provider.ts

@@ -8,10 +8,18 @@
  */
 
 import { loadConfig } from "../config/loader.js";
+import {
+  getCatalogProvider,
+  listCatalogProviderIds,
+} from "../tts/provider-catalog.js";
 import { getTtsProvider } from "../tts/provider-registry.js";
 import { resolveTtsConfig } from "../tts/tts-config-resolver.js";
-import type { TtsProvider } from "../tts/types.js";
+import type { TtsProvider, TtsProviderId } from "../tts/types.js";
 import { getLogger } from "../util/logger.js";
+import {
+  evaluateTelephonyTtsPlayability,
+  fishAudioReferenceIdConfigured,
+} from "./telephony-tts-capability.js";
 import { resolveCallStrategy } from "./tts-call-strategy.js";
 
 const log = getLogger("resolve-call-tts-provider");
@@ -27,8 +35,10 @@ export interface ResolvedCallTts {
   /**
    * True when the catalog's `callMode` is `"synthesized-play"` -- audio
    * is synthesized via the provider API and streamed through the audio
-   * store. False when `callMode` is `"native-twilio"` -- text tokens are
-   * sent directly to the relay for Twilio's built-in TTS engine.
+   * store. False when `callMode` is `"native-twilio"` -- text is sent
+   * via `sendTextToken()`, which the media-stream transport re-synthesizes
+   * through daemon TTS. (Collapsing the callMode split is a documented
+   * deferred follow-up.)
    */
   useSynthesizedPath: boolean;
 
@@ -47,6 +57,11 @@ export interface ResolveCallTtsOptions {
    * because its {@link audioBufferToFrames} can only correctly
    * transcode WAV (PCM) to mu-law -- compressed formats (mp3, opus)
    * are sent as raw bytes and produce garbled audio.
+   *
+   * Also gates the media-stream playability guard: a configured provider
+   * that cannot produce playable PCM/WAV audio (or lacks credentials) is
+   * swapped for a playable fallback provider instead of resolving into a
+   * provider whose only possible media-stream outcome is silence.
    */
   preferWav?: boolean;
 }
@@ -63,49 +78,75 @@ export interface ResolveCallTtsOptions {
  * decision path used by `voice-quality.ts`. Providers with
  * `callMode: "synthesized-play"` have their audio streamed through the
  * audio store and played via `sendPlayUrl`. Providers with
- * `callMode: "native-twilio"` stream text tokens directly to the relay
- * for Twilio's built-in TTS.
+ * `callMode: "native-twilio"` send text via `sendTextToken`, which the
+ * media-stream transport re-synthesizes through daemon TTS.
+ *
+ * For WAV-requiring transports (`preferWav`, i.e. media-stream), the
+ * resolved provider is validated against the media-stream playability
+ * capability (format + credentials); a not-playable provider is replaced
+ * by {@link findPlayableTelephonyTtsFallback}.
  *
  * Falls back to the native path with `mp3` format when the config is
  * missing a `services.tts` block or the provider is not registered
  * (e.g. unit tests or early startup).
  */
-export function resolveCallTtsProvider(
+export async function resolveCallTtsProvider(
   options?: ResolveCallTtsOptions,
-): ResolvedCallTts {
+): Promise<ResolvedCallTts> {
   try {
     const config = loadConfig();
     const resolved = resolveTtsConfig(config);
-    const provider = getTtsProvider(resolved.provider);
 
     // Use the catalog's callMode to decide the call path -- the same
     // decision path used by voice-quality.ts via resolveCallStrategy().
     const strategy = resolveCallStrategy(config);
-    const useSynthesizedPath = strategy.callMode === "synthesized-play";
 
-    // For synthesized providers, preflight provider-specific config
-    // invariants that would otherwise fail only at first synthesis call.
-    // If required config is missing, degrade to the native token path
-    // (Twilio TTS) rather than letting the call stay silent.
-    //
-    // Fish Audio requires a reference ID when no per-request voiceId is
-    // supplied (which is the telephony default).
-    if (useSynthesizedPath && resolved.provider === "fish-audio") {
-      const referenceId = (resolved.providerConfig as { referenceId?: string })
-        .referenceId;
-      if (!referenceId?.trim()) {
-        log.warn(
-          { provider: resolved.provider },
-          "Synthesized call TTS disabled: fish-audio.referenceId is not configured; falling back to native token path",
-        );
-        return {
-          provider: null,
-          useSynthesizedPath: false,
-          audioFormat: "mp3",
-        };
+    let providerId = resolved.provider;
+    let useSynthesizedPath = strategy.callMode === "synthesized-play";
+
+    // Preflight provider-specific config invariants that would otherwise
+    // fail only at first synthesis call. Fish Audio requires a reference
+    // ID when no per-request voiceId is supplied (the telephony default).
+    const fishAudioUnusable =
+      providerId === "fish-audio" && !fishAudioReferenceIdConfigured();
+
+    if (options?.preferWav) {
+      // Media-stream transport: every spoken turn is synthesized, so the
+      // provider must produce playable PCM/WAV with resolvable credentials
+      // and satisfied config invariants (the capability check covers the
+      // fish-audio referenceId rule). Swap in a playable fallback rather
+      // than resolving into a provider that can only be silent.
+      const capability = await evaluateTelephonyTtsPlayability(providerId);
+      if (capability.status === "not-playable") {
+        const reason = capability.reason;
+        const fallbackId = await findPlayableTelephonyTtsFallback(providerId);
+        if (fallbackId) {
+          log.warn(
+            { providerId, reason, fallbackProviderId: fallbackId },
+            "Configured TTS provider is not playable on the media-stream transport; falling back",
+          );
+          providerId = fallbackId;
+          useSynthesizedPath =
+            getCatalogProvider(fallbackId).callMode === "synthesized-play";
+        } else {
+          log.warn(
+            { providerId, reason },
+            "Configured TTS provider is not playable on the media-stream transport and no playable fallback provider is available",
+          );
+        }
       }
+    } else if (useSynthesizedPath && fishAudioUnusable) {
+      // Non-WAV transport: degrade to the native token path rather than
+      // letting the call stay silent.
+      log.warn(
+        { provider: providerId },
+        "Synthesized call TTS disabled: fish-audio.referenceId is not configured; falling back to native token path",
+      );
+      return { provider: null, useSynthesizedPath: false, audioFormat: "mp3" };
     }
 
+    const provider = getTtsProvider(providerId);
+
     // Read the user-configured audio format from the resolved provider
     // config so the streaming store entry's content-type matches the
     // actual audio bytes the provider produces.
@@ -134,3 +175,29 @@ export function resolveCallTtsProvider(
     return { provider: null, useSynthesizedPath: false, audioFormat: "mp3" };
   }
 }
+
+/**
+ * Find a catalog provider that can produce playable media-stream audio
+ * with resolvable credentials.
+ *
+ * Preference order: the ElevenLabs default first (when its key resolves),
+ * then the remaining catalog providers in display order. The playability
+ * capability already applies the fish-audio `referenceId` invariant, so a
+ * referenceId-less fish-audio setup is never selected. Returns `null` when
+ * no provider qualifies.
+ */
+export async function findPlayableTelephonyTtsFallback(
+  excludeProviderId?: TtsProviderId,
+): Promise<TtsProviderId | null> {
+  const candidates = [
+    ...new Set<TtsProviderId>(["elevenlabs", ...listCatalogProviderIds()]),
+  ].filter((id) => id !== excludeProviderId);
+
+  for (const candidateId of candidates) {
+    const capability = await evaluateTelephonyTtsPlayability(candidateId);
+    if (capability.status === "playable") {
+      return candidateId;
+    }
+  }
+  return null;
+}

package/src/calls/stt-hints.ts

@@ -1,13 +1,4 @@
-import { findContactByAddress, listContacts } from "../contacts/contact-store.js";
-import {
-  getGuardianDelivery,
-  voiceGuardianDisplayName,
-} from "../contacts/guardian-delivery-reader.js";
-import { getAssistantName } from "../daemon/identity-helpers.js";
-import { DEFAULT_USER_REFERENCE, resolveGuardianName } from "../prompts/user-reference.js";
-import { getLogger } from "../util/logger.js";
-
-const logger = getLogger("stt-hints");
+import { DEFAULT_USER_REFERENCE } from "../prompts/user-reference.js";
 
 export interface SttHintsInput {
   staticHints: string[];
@@ -28,6 +19,9 @@ const MAX_HINTS_LENGTH = 500;
  * comma-separated string suitable for speech-to-text provider hint APIs.
  *
  * Pure function — no DB or filesystem dependencies.
+ *
+ * Dormant: the `calls.voice.hints` config key supplies static hints, but
+ * no daemon transcriber consumes the assembled string yet.
  */
 export function buildSttHints(input: SttHintsInput): string {
   const hints: string[] = [...input.staticHints];
@@ -44,26 +38,41 @@ export function buildSttHints(input: SttHintsInput): string {
     hints.push(input.guardianName.trim());
   }
 
-  if (input.inviteFriendName != null && input.inviteFriendName.trim().length > 0) {
+  if (
+    input.inviteFriendName != null &&
+    input.inviteFriendName.trim().length > 0
+  ) {
     hints.push(input.inviteFriendName.trim());
   }
 
-  if (input.inviteGuardianName != null && input.inviteGuardianName.trim().length > 0) {
+  if (
+    input.inviteGuardianName != null &&
+    input.inviteGuardianName.trim().length > 0
+  ) {
     hints.push(input.inviteGuardianName.trim());
   }
 
-  if (input.targetContactName != null && input.targetContactName.trim().length > 0) {
+  if (
+    input.targetContactName != null &&
+    input.targetContactName.trim().length > 0
+  ) {
     hints.push(input.targetContactName.trim());
   }
 
-  if (input.callerContactName != null && input.callerContactName.trim().length > 0) {
+  if (
+    input.callerContactName != null &&
+    input.callerContactName.trim().length > 0
+  ) {
     hints.push(input.callerContactName.trim());
   }
 
   // Extract potential proper nouns from task description.
   // Split on sentence boundaries, then for each sentence take words
   // after the first that start with an uppercase letter.
-  if (input.taskDescription != null && input.taskDescription.trim().length > 0) {
+  if (
+    input.taskDescription != null &&
+    input.taskDescription.trim().length > 0
+  ) {
     // Split on sentence-ending punctuation followed by whitespace, but avoid
     // splitting on periods after common abbreviations (Dr., Mr., etc.) so that
     // names like "Dr. Smith" aren't fragmented and dropped by the first-word skip.
@@ -112,75 +121,3 @@ export function buildSttHints(input: SttHintsInput): string {
   }
   return truncated.slice(0, lastComma);
 }
-
-/**
- * Wire real data sources (contacts DB, identity helpers, config) into
- * {@link buildSttHints}. All DB lookups are best-effort — errors are
- * logged but never propagate so hints can never fail a call.
- */
-export async function resolveCallHints(
-  session: {
-    task: string | null;
-    toNumber: string;
-    fromNumber: string;
-    direction: "inbound" | "outbound";
-    inviteFriendName: string | null;
-    inviteGuardianName: string | null;
-  } | null,
-  staticHints: string[],
-): Promise<string> {
-  const assistantName = getAssistantName();
-
-  // Resolve the guardian displayName from the gateway binding for STT vocabulary.
-  let guardianDisplayName: string | undefined;
-  try {
-    const list = await getGuardianDelivery();
-    guardianDisplayName = voiceGuardianDisplayName(list);
-  } catch (err) {
-    logger.warn({ err }, "Failed to look up guardian contact for STT hints");
-  }
-  const guardianName = resolveGuardianName(guardianDisplayName);
-
-  let targetContactName: string | null = null;
-  let callerContactName: string | null = null;
-  let recentContactNames: string[] = [];
-
-  // For inbound calls, fromNumber is the caller (the interesting party);
-  // toNumber is the assistant's own Twilio number (not useful for contact lookup).
-  // For outbound calls, toNumber is who we're calling.
-  try {
-    if (session) {
-      const otherPartyNumber =
-        session.direction === "inbound" ? session.fromNumber : session.toNumber;
-      const otherPartyContact = findContactByAddress("phone", otherPartyNumber);
-      if (otherPartyContact) {
-        if (session.direction === "inbound") {
-          callerContactName = otherPartyContact.displayName;
-        } else {
-          targetContactName = otherPartyContact.displayName;
-        }
-      }
-    }
-  } catch (err) {
-    logger.warn({ err }, "Failed to look up contact for STT hints");
-  }
-
-  try {
-    const recentContacts = listContacts(15);
-    recentContactNames = recentContacts.map((c) => c.displayName);
-  } catch (err) {
-    logger.warn({ err }, "Failed to list recent contacts for STT hints");
-  }
-
-  return buildSttHints({
-    staticHints,
-    assistantName,
-    guardianName,
-    taskDescription: session?.task ?? null,
-    targetContactName,
-    callerContactName,
-    inviteFriendName: session?.inviteFriendName ?? null,
-    inviteGuardianName: session?.inviteGuardianName ?? null,
-    recentContactNames,
-  });
-}