@vellumai/assistant 0.4.26 → 0.4.29

package/src/calls/twilio-routes.ts

@@ -6,16 +6,16 @@
  * - handleConnectAction: called when the ConversationRelay connection ends
  */
 
-import { getCallWelcomeGreeting } from '../config/env.js';
-import { loadConfig } from '../config/loader.js';
-import { getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
-import { mintEdgeRelayToken } from '../runtime/auth/token-service.js';
-import { getLogger } from '../util/logger.js';
-import { persistCallCompletionMessage } from './call-conversation-messages.js';
-import { createInboundVoiceSession } from './call-domain.js';
-import { logDeadLetterEvent } from './call-recovery.js';
-import { fireCallCompletionNotifier } from './call-state.js';
-import { isTerminalState } from './call-state-machine.js';
+import { getCallWelcomeGreeting } from "../config/env.js";
+import { loadConfig } from "../config/loader.js";
+import { getTwilioRelayUrl } from "../inbound/public-ingress-urls.js";
+import { mintEdgeRelayToken } from "../runtime/auth/token-service.js";
+import { getLogger } from "../util/logger.js";
+import { persistCallCompletionMessage } from "./call-conversation-messages.js";
+import { createInboundVoiceSession } from "./call-domain.js";
+import { logDeadLetterEvent } from "./call-recovery.js";
+import { fireCallCompletionNotifier } from "./call-state.js";
+import { isTerminalState } from "./call-state-machine.js";
 import {
   buildCallbackDedupeKey,
   claimCallback,
@@ -26,43 +26,53 @@ import {
   recordCallEvent,
   releaseCallbackClaim,
   updateCallSession,
-} from './call-store.js';
-import { getTwilioConfig } from './twilio-config.js';
-import type { CallStatus } from './types.js';
-import { resolveVoiceQualityProfile } from './voice-quality.js';
+} from "./call-store.js";
+import { getTwilioConfig } from "./twilio-config.js";
+import type { CallStatus } from "./types.js";
+import { resolveVoiceQualityProfile } from "./voice-quality.js";
 
-const log = getLogger('twilio-routes');
+const log = getLogger("twilio-routes");
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
 function escapeXml(str: string): string {
   return str
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;');
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
 }
 
 export function generateTwiML(
   callSessionId: string,
   relayUrl: string,
   welcomeGreeting: string | null,
-  profile: { language: string; transcriptionProvider: string; ttsProvider: string; voice: string },
+  profile: {
+    language: string;
+    transcriptionProvider: string;
+    ttsProvider: string;
+    voice: string;
+  },
   relayToken?: string,
   customParameters?: Record<string, string>,
 ): string {
-  const greetingAttr = welcomeGreeting && welcomeGreeting.trim().length > 0
-    ? `\n      welcomeGreeting="${escapeXml(welcomeGreeting.trim())}"`
-    : '';
-  const tokenParam = relayToken ? `&amp;token=${escapeXml(encodeURIComponent(relayToken))}` : '';
+  const greetingAttr =
+    welcomeGreeting && welcomeGreeting.trim().length > 0
+      ? `\n      welcomeGreeting="${escapeXml(welcomeGreeting.trim())}"`
+      : "";
+  const tokenParam = relayToken
+    ? `&amp;token=${escapeXml(encodeURIComponent(relayToken))}`
+    : "";
 
   // Build <Parameter> elements for custom parameters to propagate
   // through the ConversationRelay setup payload for observability.
-  let parameterElements = '';
+  let parameterElements = "";
   if (customParameters) {
     for (const [key, value] of Object.entries(customParameters)) {
-      parameterElements += `\n      <Parameter name="${escapeXml(key)}" value="${escapeXml(value)}" />`;
+      parameterElements += `\n      <Parameter name="${escapeXml(
+        key,
+      )}" value="${escapeXml(value)}" />`;
     }
   }
 
@@ -71,13 +81,15 @@ export function generateTwiML(
   const hasParameters = parameterElements.length > 0;
   const relayClose = hasParameters
     ? `>${parameterElements}\n    </ConversationRelay>`
-    : '/>';
+    : "/>";
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <Response>
   <Connect>
     <ConversationRelay
-      url="${escapeXml(relayUrl)}?callSessionId=${escapeXml(callSessionId)}${tokenParam}"
+      url="${escapeXml(relayUrl)}?callSessionId=${escapeXml(
+        callSessionId,
+      )}${tokenParam}"
 ${greetingAttr}
       voice="${escapeXml(profile.voice)}"
       language="${escapeXml(profile.language)}"
@@ -90,14 +102,17 @@ ${greetingAttr}
 </Response>`;
 }
 
-export function buildWelcomeGreeting(task: string | null, configuredGreeting?: string): string {
+export function buildWelcomeGreeting(
+  task: string | null,
+  configuredGreeting?: string,
+): string {
   void task;
   const override = configuredGreeting?.trim();
   if (override) return override;
   // The contextual first opener now comes from the call controller's
   // initial LLM turn via the session pipeline. Keep Twilio's relay-level
   // greeting empty by default so we don't speak a deterministic static line first.
-  return '';
+  return "";
 }
 
 /**
@@ -107,9 +122,12 @@ export function buildWelcomeGreeting(task: string | null, configuredGreeting?: s
  * Falls back to webhookBaseUrl, normalizing the scheme from http(s) to ws(s)
  * and stripping any trailing slash.
  */
-export function resolveRelayUrl(wssBaseUrl: string, webhookBaseUrl: string): string {
+export function resolveRelayUrl(
+  wssBaseUrl: string,
+  webhookBaseUrl: string,
+): string {
   const base = wssBaseUrl.trim() || webhookBaseUrl;
-  const normalized = base.replace(/\/$/, '').replace(/^http(s?)/, 'ws$1');
+  const normalized = base.replace(/\/$/, "").replace(/^http(s?)/, "ws$1");
   return `${normalized}/v1/calls/relay`;
 }
 
@@ -118,21 +136,21 @@ export function resolveRelayUrl(wssBaseUrl: string, webhookBaseUrl: string): str
  */
 function mapTwilioStatus(twilioStatus: string): CallStatus | null {
   switch (twilioStatus) {
-    case 'initiated':
-    case 'queued':
-      return 'initiated';
-    case 'ringing':
-      return 'ringing';
-    case 'answered':
-    case 'in-progress':
-      return 'in_progress';
-    case 'completed':
-      return 'completed';
-    case 'failed':
-    case 'busy':
-    case 'no-answer':
-    case 'canceled':
-      return 'failed';
+    case "initiated":
+    case "queued":
+      return "initiated";
+    case "ringing":
+      return "ringing";
+    case "answered":
+    case "in-progress":
+      return "in_progress";
+    case "completed":
+      return "completed";
+    case "failed":
+    case "busy":
+    case "no-answer":
+    case "canceled":
+      return "failed";
     default:
       return null;
   }
@@ -151,22 +169,25 @@ function mapTwilioStatus(twilioStatus: string): CallStatus | null {
  */
 export async function handleVoiceWebhook(req: Request): Promise<Response> {
   const url = new URL(req.url);
-  const callSessionId = url.searchParams.get('callSessionId');
+  const callSessionId = url.searchParams.get("callSessionId");
 
   // Parse the Twilio POST body to capture CallSid and caller metadata.
   const formBody = new URLSearchParams(await req.text());
-  const callSid = formBody.get('CallSid');
-  const callerFrom = formBody.get('From') ?? '';
-  const callerTo = formBody.get('To') ?? '';
+  const callSid = formBody.get("CallSid");
+  const callerFrom = formBody.get("From") ?? "";
+  const callerTo = formBody.get("To") ?? "";
 
   // ── Inbound mode: no callSessionId in query ─────────────────────
   if (!callSessionId) {
     if (!callSid) {
-      log.warn('Inbound voice webhook called without CallSid');
-      return new Response('Missing CallSid', { status: 400 });
+      log.warn("Inbound voice webhook called without CallSid");
+      return new Response("Missing CallSid", { status: 400 });
     }
 
-    log.info({ callSid, from: callerFrom, to: callerTo }, 'Inbound voice webhook — creating/reusing session');
+    log.info(
+      { callSid, from: callerFrom, to: callerTo },
+      "Inbound voice webhook — creating/reusing session",
+    );
 
     const { session } = createInboundVoiceSession({
       callSid,
@@ -174,28 +195,41 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
       toNumber: callerTo,
     });
 
-    return buildVoiceWebhookTwiml(session.id, session.assistantId ?? undefined, session.task, session.guardianVerificationSessionId);
+    return buildVoiceWebhookTwiml(
+      session.id,
+      session.assistantId ?? undefined,
+      session.task,
+      session.guardianVerificationSessionId,
+    );
   }
 
   // ── Outbound mode: callSessionId is present ─────────────────────
   const session = getCallSession(callSessionId);
   if (!session) {
-    log.warn({ callSessionId }, 'Voice webhook: call session not found');
-    return new Response('Call session not found', { status: 404 });
+    log.warn({ callSessionId }, "Voice webhook: call session not found");
+    return new Response("Call session not found", { status: 404 });
   }
 
   if (isTerminalState(session.status)) {
-    log.warn({ callSessionId, status: session.status }, 'Voice webhook: call session is in terminal state');
-    return new Response('Call session is no longer active', { status: 410 });
+    log.warn(
+      { callSessionId, status: session.status },
+      "Voice webhook: call session is in terminal state",
+    );
+    return new Response("Call session is no longer active", { status: 410 });
   }
 
   // Capture CallSid immediately so status callbacks can locate this session
   if (callSid && callSid !== session.providerCallSid) {
     updateCallSession(callSessionId, { providerCallSid: callSid });
-    log.info({ callSessionId, callSid }, 'Stored CallSid from voice webhook');
+    log.info({ callSessionId, callSid }, "Stored CallSid from voice webhook");
   }
 
-  return buildVoiceWebhookTwiml(callSessionId, session.assistantId ?? undefined, session.task, session.guardianVerificationSessionId);
+  return buildVoiceWebhookTwiml(
+    callSessionId,
+    session.assistantId ?? undefined,
+    session.task,
+    session.guardianVerificationSessionId,
+  );
 }
 
 /**
@@ -216,7 +250,10 @@ function buildVoiceWebhookTwiml(
 ): Response {
   const profile = resolveVoiceQualityProfile(loadConfig());
 
-  log.info({ callSessionId, ttsProvider: profile.ttsProvider, voice: profile.voice }, 'Voice quality profile resolved');
+  log.info(
+    { callSessionId, ttsProvider: profile.ttsProvider, voice: profile.voice },
+    "Voice quality profile resolved",
+  );
 
   const twilioConfig = getTwilioConfig();
   let relayUrl: string;
@@ -224,7 +261,10 @@ function buildVoiceWebhookTwiml(
     relayUrl = getTwilioRelayUrl(loadConfig());
   } catch {
     // Fallback to legacy resolution when ingress is not configured
-    relayUrl = resolveRelayUrl(twilioConfig.wssBaseUrl, twilioConfig.webhookBaseUrl);
+    relayUrl = resolveRelayUrl(
+      twilioConfig.wssBaseUrl,
+      twilioConfig.webhookBaseUrl,
+    );
   }
   const welcomeGreeting = buildWelcomeGreeting(task, getCallWelcomeGreeting());
 
@@ -238,13 +278,20 @@ function buildVoiceWebhookTwiml(
       ? { guardianVerificationSessionId }
       : undefined;
 
-  const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, profile, relayToken, customParameters);
+  const twiml = generateTwiML(
+    callSessionId,
+    relayUrl,
+    welcomeGreeting,
+    profile,
+    relayToken,
+    customParameters,
+  );
 
-  log.info({ callSessionId }, 'Returning ConversationRelay TwiML');
+  log.info({ callSessionId }, "Returning ConversationRelay TwiML");
 
   return new Response(twiml, {
     status: 200,
-    headers: { 'Content-Type': 'text/xml' },
+    headers: { "Content-Type": "text/xml" },
   });
 }
 
@@ -254,20 +301,27 @@ function buildVoiceWebhookTwiml(
  */
 export async function handleStatusCallback(req: Request): Promise<Response> {
   const formBody = new URLSearchParams(await req.text());
-  const callSid = formBody.get('CallSid');
-  const callStatus = formBody.get('CallStatus');
+  const callSid = formBody.get("CallSid");
+  const callStatus = formBody.get("CallStatus");
 
   if (!callSid || !callStatus) {
     const rawPayload = Object.fromEntries(formBody.entries());
-    logDeadLetterEvent('Status callback missing CallSid or CallStatus', rawPayload, log);
+    logDeadLetterEvent(
+      "Status callback missing CallSid or CallStatus",
+      rawPayload,
+      log,
+    );
     return new Response(null, { status: 200 });
   }
 
-  log.info({ callSid, callStatus }, 'Twilio status callback received');
+  log.info({ callSid, callStatus }, "Twilio status callback received");
 
   const session = getCallSessionByCallSid(callSid);
   if (!session) {
-    log.warn({ callSid, callStatus }, 'Status callback: no call session found for CallSid');
+    log.warn(
+      { callSid, callStatus },
+      "Status callback: no call session found for CallSid",
+    );
     return new Response(null, { status: 200 });
   }
 
@@ -279,13 +333,21 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
   }
 
   // ── Atomic idempotency claim ────────────────────────────────────
-  const timestamp = formBody.get('Timestamp');
-  const sequenceNumber = formBody.get('SequenceNumber');
-  const dedupeKey = buildCallbackDedupeKey(callSid, callStatus, timestamp, sequenceNumber);
+  const timestamp = formBody.get("Timestamp");
+  const sequenceNumber = formBody.get("SequenceNumber");
+  const dedupeKey = buildCallbackDedupeKey(
+    callSid,
+    callStatus,
+    timestamp,
+    sequenceNumber,
+  );
 
   const claimId = claimCallback(dedupeKey, session.id);
   if (!claimId) {
-    log.info({ callSid, callStatus, dedupeKey }, 'Duplicate status callback — skipping');
+    log.info(
+      { callSid, callStatus, dedupeKey },
+      "Duplicate status callback — skipping",
+    );
     return new Response(null, { status: 200 });
   }
 
@@ -297,11 +359,12 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       status: mappedStatus,
     };
 
-    if (mappedStatus === 'in_progress' && !session.startedAt) {
+    if (mappedStatus === "in_progress" && !session.startedAt) {
       updates.startedAt = Date.now();
     }
 
-    const isTerminal = mappedStatus === 'completed' || mappedStatus === 'failed';
+    const isTerminal =
+      mappedStatus === "completed" || mappedStatus === "failed";
     if (isTerminal) {
       updates.endedAt = Date.now();
     }
@@ -310,8 +373,12 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
 
     // Record event
     const eventType = isTerminal
-      ? (mappedStatus === 'completed' ? 'call_ended' : 'call_failed')
-      : (mappedStatus === 'in_progress' ? 'call_connected' : 'call_started');
+      ? mappedStatus === "completed"
+        ? "call_ended"
+        : "call_failed"
+      : mappedStatus === "in_progress"
+        ? "call_connected"
+        : "call_started";
 
     recordCallEvent(session.id, eventType, {
       twilioStatus: callStatus,
@@ -323,9 +390,18 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       expirePendingQuestions(session.id);
 
       if (!wasTerminal) {
-        persistCallCompletionMessage(session.conversationId, session.id).catch((err) => {
-          log.error({ err, conversationId: session.conversationId, callSessionId: session.id }, 'Failed to persist call completion message');
-        });
+        persistCallCompletionMessage(session.conversationId, session.id).catch(
+          (err) => {
+            log.error(
+              {
+                err,
+                conversationId: session.conversationId,
+                callSessionId: session.id,
+              },
+              "Failed to persist call completion message",
+            );
+          },
+        );
         fireCallCompletionNotifier(session.conversationId, session.id);
       }
     }
@@ -339,7 +415,7 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
     if (!finalized) {
       log.warn(
         { dedupeKey, claimId, callSid, callStatus },
-        'Lost claim during finalization — business writes committed but dedupe ownership was taken by another handler',
+        "Lost claim during finalization — business writes committed but dedupe ownership was taken by another handler",
       );
     }
   } catch (err) {
@@ -356,12 +432,9 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
  * Returns empty TwiML to acknowledge.
  */
 export async function handleConnectAction(_req: Request): Promise<Response> {
-  log.info('ConversationRelay connect-action callback received');
-  return new Response(
-    '<?xml version="1.0" encoding="UTF-8"?><Response/>',
-    {
-      status: 200,
-      headers: { 'Content-Type': 'text/xml' },
-    },
-  );
+  log.info("ConversationRelay connect-action callback received");
+  return new Response('<?xml version="1.0" encoding="UTF-8"?><Response/>', {
+    status: 200,
+    headers: { "Content-Type": "text/xml" },
+  });
 }

package/src/calls/types.ts

@@ -1,16 +1,64 @@
-export type CallStatus = 'initiated' | 'ringing' | 'in_progress' | 'waiting_on_user' | 'completed' | 'failed' | 'cancelled';
-export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed' | 'callee_verification_started' | 'callee_verification_succeeded' | 'callee_verification_failed' | 'guardian_voice_verification_started' | 'guardian_voice_verification_succeeded' | 'guardian_voice_verification_failed' | 'outbound_guardian_voice_verification_started' | 'outbound_guardian_voice_verification_succeeded' | 'outbound_guardian_voice_verification_failed' | 'guardian_consultation_timed_out' | 'guardian_unavailable_skipped' | 'guardian_consult_deferred' | 'guardian_consult_coalesced' | 'inbound_acl_denied' | 'inbound_acl_name_capture_started' | 'inbound_acl_name_captured' | 'inbound_acl_name_capture_timeout' | 'inbound_acl_access_approved' | 'inbound_acl_access_denied' | 'inbound_acl_access_timeout' | 'invite_redemption_started' | 'invite_redemption_succeeded' | 'invite_redemption_failed' | 'voice_guardian_wait_heartbeat_sent' | 'voice_guardian_wait_prompt_classified' | 'voice_guardian_wait_callback_offer_sent' | 'voice_guardian_wait_callback_opt_in_set' | 'voice_guardian_wait_callback_opt_in_declined'
-  | 'inbound_acl_post_approval_handoff_spoken'
-  | 'callback_handoff_notified'
-  | 'callback_handoff_failed';
-export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
+export type CallStatus =
+  | "initiated"
+  | "ringing"
+  | "in_progress"
+  | "waiting_on_user"
+  | "completed"
+  | "failed"
+  | "cancelled";
+export type CallEventType =
+  | "call_started"
+  | "call_connected"
+  | "caller_spoke"
+  | "assistant_spoke"
+  | "user_question_asked"
+  | "user_answered"
+  | "user_instruction_relayed"
+  | "call_ended"
+  | "call_failed"
+  | "callee_verification_started"
+  | "callee_verification_succeeded"
+  | "callee_verification_failed"
+  | "guardian_voice_verification_started"
+  | "guardian_voice_verification_succeeded"
+  | "guardian_voice_verification_failed"
+  | "outbound_guardian_voice_verification_started"
+  | "outbound_guardian_voice_verification_succeeded"
+  | "outbound_guardian_voice_verification_failed"
+  | "guardian_consultation_timed_out"
+  | "guardian_unavailable_skipped"
+  | "guardian_consult_deferred"
+  | "guardian_consult_coalesced"
+  | "inbound_acl_denied"
+  | "inbound_acl_name_capture_started"
+  | "inbound_acl_name_captured"
+  | "inbound_acl_name_capture_timeout"
+  | "inbound_acl_access_approved"
+  | "inbound_acl_access_denied"
+  | "inbound_acl_access_timeout"
+  | "invite_redemption_started"
+  | "invite_redemption_succeeded"
+  | "invite_redemption_failed"
+  | "voice_guardian_wait_heartbeat_sent"
+  | "voice_guardian_wait_prompt_classified"
+  | "voice_guardian_wait_callback_offer_sent"
+  | "voice_guardian_wait_callback_opt_in_set"
+  | "voice_guardian_wait_callback_opt_in_declined"
+  | "inbound_acl_post_approval_handoff_spoken"
+  | "callback_handoff_notified"
+  | "callback_handoff_failed";
+export type PendingQuestionStatus =
+  | "pending"
+  | "answered"
+  | "expired"
+  | "cancelled";
 
 /**
  * Explicit call mode written at session creation time. The relay server
  * uses this as the primary signal for deterministic flow selection,
  * with Twilio setup custom parameters as a secondary/observability signal.
  */
-export type CallMode = 'normal' | 'guardian_verification';
+export type CallMode = "normal" | "guardian_verification";
 
 export interface CallSession {
   id: string;

package/src/calls/voice-quality.ts

@@ -1,4 +1,4 @@
-import { loadConfig } from '../config/loader.js';
+import { loadConfig } from "../config/loader.js";
 
 export interface VoiceQualityProfile {
   language: string;
@@ -28,7 +28,7 @@ export function buildElevenLabsVoiceSpec(config: {
   similarityBoost?: number;
 }): string {
   const voiceId = config.voiceId?.trim();
-  if (!voiceId) return '';
+  if (!voiceId) return "";
 
   const voiceModelId = config.voiceModelId?.trim();
   if (!voiceModelId) return voiceId;
@@ -46,13 +46,15 @@ export function buildElevenLabsVoiceSpec(config: {
  * The voice ID comes from the shared `elevenlabs.voiceId` config
  * (defaults to Rachel — 21m00Tcm4TlvDq8ikWAM).
  */
-export function resolveVoiceQualityProfile(config?: ReturnType<typeof loadConfig>): VoiceQualityProfile {
+export function resolveVoiceQualityProfile(
+  config?: ReturnType<typeof loadConfig>,
+): VoiceQualityProfile {
   const cfg = config ?? loadConfig();
   const voice = cfg.calls.voice;
   return {
     language: voice.language,
     transcriptionProvider: voice.transcriptionProvider,
-    ttsProvider: 'ElevenLabs',
+    ttsProvider: "ElevenLabs",
     voice: buildElevenLabsVoiceSpec(cfg.elevenlabs),
   };
 }