@vellumai/assistant 0.3.5 → 0.3.7

package/src/calls/twilio-rest.ts

@@ -7,6 +7,7 @@
  */
 
 import { getSecureKey } from '../security/secure-keys.js';
+import { ProviderError, ConfigError } from '../util/errors.js';
 
 export interface TwilioCredentials {
   accountSid: string;
@@ -18,7 +19,7 @@ export function getTwilioCredentials(): TwilioCredentials {
   const accountSid = getSecureKey('credential:twilio:account_sid');
   const authToken = getSecureKey('credential:twilio:auth_token');
   if (!accountSid || !authToken) {
-    throw new Error(
+    throw new ConfigError(
       'Twilio credentials not configured. Set credential:twilio:account_sid and credential:twilio:auth_token via the credential_store tool.',
     );
   }
@@ -58,7 +59,7 @@ export async function listIncomingPhoneNumbers(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio API error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio API error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as {
@@ -102,7 +103,7 @@ export async function searchAvailableNumbers(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio API error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio API error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as {
@@ -139,7 +140,7 @@ export async function provisionPhoneNumber(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio API error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio API error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as {
@@ -171,7 +172,7 @@ export async function fetchMessageStatus(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio API error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio API error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as {
@@ -217,7 +218,7 @@ export async function updatePhoneNumberWebhooks(
 
   if (!listRes.ok) {
     const text = await listRes.text();
-    throw new Error(`Twilio API error ${listRes.status} looking up phone number: ${text}`);
+    throw new ProviderError(`Twilio API error ${listRes.status} looking up phone number: ${text}`, 'twilio', listRes.status);
   }
 
   const listData = (await listRes.json()) as {
@@ -226,7 +227,7 @@ export async function updatePhoneNumberWebhooks(
 
   const match = listData.incoming_phone_numbers.find((n) => n.phone_number === phoneNumber);
   if (!match) {
-    throw new Error(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`);
+    throw new ProviderError(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`, 'twilio');
   }
 
   // Update the phone number's webhook configuration
@@ -253,7 +254,7 @@ export async function updatePhoneNumberWebhooks(
 
   if (!updateRes.ok) {
     const text = await updateRes.text();
-    throw new Error(`Twilio API error ${updateRes.status} updating webhooks: ${text}`);
+    throw new ProviderError(`Twilio API error ${updateRes.status} updating webhooks: ${text}`, 'twilio', updateRes.status);
   }
 }
 
@@ -310,7 +311,7 @@ export async function getTollFreeVerificationStatus(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio Toll-Free Verification API error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio Toll-Free Verification API error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as { verifications?: Array<Record<string, unknown>> };
@@ -320,6 +321,30 @@ export async function getTollFreeVerificationStatus(
   return parseTollFreeVerification(verifications[0]);
 }
 
+/** Fetch a specific toll-free verification by SID. */
+export async function getTollFreeVerificationBySid(
+  accountSid: string,
+  authToken: string,
+  verificationSid: string,
+): Promise<TollFreeVerification | null> {
+  const res = await fetch(`${TOLLFREE_VERIFICATION_BASE}/${encodeURIComponent(verificationSid)}`, {
+    method: 'GET',
+    headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+  });
+
+  if (res.status === 404) {
+    return null;
+  }
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new ProviderError(`Twilio Toll-Free Verification fetch error ${res.status}: ${text}`, 'twilio', res.status);
+  }
+
+  const data = (await res.json()) as Record<string, unknown>;
+  return parseTollFreeVerification(data);
+}
+
 export interface TollFreeVerificationSubmitParams {
   tollfreePhoneNumberSid: string;
   businessName: string;
@@ -373,7 +398,7 @@ export async function submitTollFreeVerification(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio Toll-Free Verification submit error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio Toll-Free Verification submit error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as Record<string, unknown>;
@@ -419,7 +444,7 @@ export async function updateTollFreeVerification(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio Toll-Free Verification update error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio Toll-Free Verification update error ${res.status}: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as Record<string, unknown>;
@@ -439,7 +464,7 @@ export async function deleteTollFreeVerification(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio Toll-Free Verification delete error ${res.status}: ${text}`);
+    throw new ProviderError(`Twilio Toll-Free Verification delete error ${res.status}: ${text}`, 'twilio', res.status);
   }
 }
 
@@ -462,7 +487,7 @@ export async function getPhoneNumberSid(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio API error ${res.status} looking up phone number SID: ${text}`);
+    throw new ProviderError(`Twilio API error ${res.status} looking up phone number SID: ${text}`, 'twilio', res.status);
   }
 
   const data = (await res.json()) as {
@@ -484,7 +509,7 @@ export async function releasePhoneNumber(
 ): Promise<void> {
   const sid = await getPhoneNumberSid(accountSid, authToken, phoneNumber);
   if (!sid) {
-    throw new Error(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`);
+    throw new ProviderError(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`, 'twilio');
   }
 
   const res = await fetch(
@@ -497,6 +522,6 @@ export async function releasePhoneNumber(
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Twilio API error ${res.status} releasing phone number: ${text}`);
+    throw new ProviderError(`Twilio API error ${res.status} releasing phone number: ${text}`, 'twilio', res.status);
   }
 }

package/src/calls/twilio-routes.ts

@@ -7,6 +7,7 @@
  */
 
 import { getLogger } from '../util/logger.js';
+import { getCallWelcomeGreeting } from '../config/env.js';
 import {
   getCallSession,
   getCallSessionByCallSid,
@@ -25,14 +26,12 @@ import { getTwilioConfig } from './twilio-config.js';
 import { loadConfig } from '../config/loader.js';
 import { getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
 import { fireCallCompletionNotifier } from './call-state.js';
+import { persistCallCompletionMessage } from './call-conversation-messages.js';
 import { resolveVoiceQualityProfile, isVoiceProfileValid } from './voice-quality.js';
+import { createInboundVoiceSession } from './call-domain.js';
 
 const log = getLogger('twilio-routes');
 
-const CONTEXT_BLOCK_SPLIT_REGEX = /\n\s*\nContext:\s*/i;
-const MAX_TASK_SUMMARY_CHARS = 120;
-const DEFAULT_WELCOME_GREETING = 'Hello, this is an assistant calling. Is now a good time to talk?';
-
 // ── Helpers ──────────────────────────────────────────────────────────
 
 function escapeXml(str: string): string {
@@ -47,15 +46,18 @@ function escapeXml(str: string): string {
 export function generateTwiML(
   callSessionId: string,
   relayUrl: string,
-  welcomeGreeting: string,
+  welcomeGreeting: string | null,
   profile: { language: string; transcriptionProvider: string; ttsProvider: string; voice: string },
 ): string {
+  const greetingAttr = welcomeGreeting && welcomeGreeting.trim().length > 0
+    ? `\n      welcomeGreeting="${escapeXml(welcomeGreeting.trim())}"`
+    : '';
   return `<?xml version="1.0" encoding="UTF-8"?>
 <Response>
   <Connect>
     <ConversationRelay
       url="${escapeXml(relayUrl)}?callSessionId=${escapeXml(callSessionId)}"
-      welcomeGreeting="${escapeXml(welcomeGreeting)}"
+${greetingAttr}
       voice="${escapeXml(profile.voice)}"
       language="${escapeXml(profile.language)}"
       transcriptionProvider="${escapeXml(profile.transcriptionProvider)}"
@@ -67,38 +69,14 @@ export function generateTwiML(
 </Response>`;
 }
 
-function summarizeTaskForGreeting(task: string | null): string | null {
-  if (!task) return null;
-  const primaryTask = task.split(CONTEXT_BLOCK_SPLIT_REGEX)[0]?.trim() ?? '';
-  if (!primaryTask) return null;
-
-  const compact = primaryTask.replace(/\s+/g, ' ').trim().replace(/[.!?]+$/, '');
-  if (!compact) return null;
-  if (compact.length <= MAX_TASK_SUMMARY_CHARS) return compact;
-  return `${compact.slice(0, MAX_TASK_SUMMARY_CHARS - 3).trimEnd()}...`;
-}
-
-function formatTaskAsCallPurpose(taskSummary: string): string {
-  const lower = taskSummary.toLowerCase();
-  if (
-    lower.startsWith('about ') ||
-    lower.startsWith('to ') ||
-    lower.startsWith('for ') ||
-    lower.startsWith('regarding ')
-  ) {
-    return taskSummary;
-  }
-  return `about ${taskSummary}`;
-}
-
 export function buildWelcomeGreeting(task: string | null, configuredGreeting?: string): string {
+  void task;
   const override = configuredGreeting?.trim();
   if (override) return override;
-
-  const taskSummary = summarizeTaskForGreeting(task);
-  if (!taskSummary) return DEFAULT_WELCOME_GREETING;
-
-  return `Hello, I am calling ${formatTaskAsCallPurpose(taskSummary)}. Is now a good time to talk?`;
+  // The contextual first opener now comes from the call orchestrator's
+  // initial LLM turn. Keep Twilio's relay-level greeting empty by default
+  // so we don't speak a deterministic static line first.
+  return '';
 }
 
 /**
@@ -144,16 +122,43 @@ function mapTwilioStatus(twilioStatus: string): CallStatus | null {
 /**
  * Receives the initial voice webhook when Twilio connects the call.
  * Returns TwiML XML that tells Twilio to open a ConversationRelay WebSocket.
+ *
+ * Supports two modes:
+ * - **Outbound** (callSessionId present in query): uses the existing session
+ * - **Inbound** (callSessionId absent): creates or reuses a session keyed
+ *   by the Twilio CallSid. The optional `forwardedAssistantId` is resolved
+ *   by the gateway from the "To" phone number.
  */
-export async function handleVoiceWebhook(req: Request): Promise<Response> {
+export async function handleVoiceWebhook(req: Request, forwardedAssistantId?: string): Promise<Response> {
   const url = new URL(req.url);
   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') ?? '';
+
+  // ── Inbound mode: no callSessionId in query ─────────────────────
   if (!callSessionId) {
-    log.warn('Voice webhook called without callSessionId');
-    return new Response('Missing callSessionId', { status: 400 });
+    if (!callSid) {
+      log.warn('Inbound voice webhook called without CallSid');
+      return new Response('Missing CallSid', { status: 400 });
+    }
+
+    log.info({ callSid, from: callerFrom, to: callerTo, assistantId: forwardedAssistantId }, 'Inbound voice webhook — creating/reusing session');
+
+    const { session } = createInboundVoiceSession({
+      callSid,
+      fromNumber: callerFrom,
+      toNumber: callerTo,
+      assistantId: forwardedAssistantId,
+    });
+
+    return buildVoiceWebhookTwiml(session.id, session.assistantId ?? undefined, session.task);
   }
 
+  // ── Outbound mode: callSessionId is present ─────────────────────
   const session = getCallSession(callSessionId);
   if (!session) {
     log.warn({ callSessionId }, 'Voice webhook: call session not found');
@@ -165,16 +170,25 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     return new Response('Call session is no longer active', { status: 410 });
   }
 
-  // Parse the Twilio POST body to capture CallSid immediately, so status
-  // callbacks (keyed by CallSid) can locate this session even if the
-  // WebSocket relay hasn't been set up yet.
-  const formBody = new URLSearchParams(await req.text());
-  const callSid = formBody.get('CallSid');
+  // 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');
   }
 
+  return buildVoiceWebhookTwiml(callSessionId, session.assistantId ?? undefined, session.task);
+}
+
+/**
+ * Shared TwiML generation for both inbound and outbound voice webhooks.
+ * Resolves voice quality profile, relay URL, and welcome greeting,
+ * then returns a Response with the generated TwiML.
+ */
+function buildVoiceWebhookTwiml(
+  callSessionId: string,
+  assistantId: string | undefined,
+  task: string | null,
+): Response {
   let profile = resolveVoiceQualityProfile(loadConfig());
 
   log.info({ callSessionId, mode: profile.mode, ttsProvider: profile.ttsProvider, voice: profile.voice }, 'Voice quality profile resolved');
@@ -213,7 +227,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     });
   }
 
-  const twilioConfig = getTwilioConfig();
+  const twilioConfig = getTwilioConfig(assistantId);
   let relayUrl: string;
   try {
     relayUrl = getTwilioRelayUrl(loadConfig());
@@ -221,7 +235,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     // Fallback to legacy resolution when ingress is not configured
     relayUrl = resolveRelayUrl(twilioConfig.wssBaseUrl, twilioConfig.webhookBaseUrl);
   }
-  const welcomeGreeting = buildWelcomeGreeting(session.task, process.env.CALL_WELCOME_GREETING);
+  const welcomeGreeting = buildWelcomeGreeting(task, getCallWelcomeGreeting());
 
   const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, profile);
 
@@ -308,6 +322,7 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       expirePendingQuestions(session.id);
 
       if (!wasTerminal) {
+        persistCallCompletionMessage(session.conversationId, session.id);
         fireCallCompletionNotifier(session.conversationId, session.id);
       }
     }

package/src/calls/types.ts

@@ -1,5 +1,5 @@
 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';
+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';
 export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
 
 export interface CallSession {
@@ -13,6 +13,8 @@ export interface CallSession {
   status: CallStatus;
   callerIdentityMode: string | null;
   callerIdentitySource: string | null;
+  assistantId: string | null;
+  initiatedFromConversationId?: string | null;
   startedAt: number | null;
   endedAt: number | null;
   lastError: string | null;

package/src/channels/types.ts

@@ -0,0 +1,25 @@
+export const CHANNEL_IDS = [
+  'telegram', 'sms', 'voice', 'macos', 'ios', 'whatsapp', 'slack', 'email',
+] as const;
+
+export type ChannelId = (typeof CHANNEL_IDS)[number];
+
+export function isChannelId(value: unknown): value is ChannelId {
+  return typeof value === 'string' && (CHANNEL_IDS as readonly string[]).includes(value);
+}
+
+export function parseChannelId(value: unknown): ChannelId | null {
+  return isChannelId(value) ? value : null;
+}
+
+export function assertChannelId(value: unknown, field: string): ChannelId {
+  if (!isChannelId(value)) {
+    throw new Error(`Invalid channel ID for ${field}: ${String(value)}. Valid values: ${CHANNEL_IDS.join(', ')}`);
+  }
+  return value;
+}
+
+export interface TurnChannelContext {
+  userMessageChannel: ChannelId;
+  assistantMessageChannel: ChannelId;
+}