@vellumai/assistant 0.3.4 → 0.3.6

package/src/calls/twilio-provider.ts

@@ -2,6 +2,7 @@ import { createHmac, timingSafeEqual } from 'node:crypto';
 import { getLogger } from '../util/logger.js';
 import { getSecureKey } from '../security/secure-keys.js';
 import { getTwilioCredentials, twilioAuthHeader, twilioBaseUrl } from './twilio-rest.js';
+import { ProviderError } from '../util/errors.js';
 import type { VoiceProvider, InitiateCallOptions } from './voice-provider.js';
 
 const log = getLogger('twilio-provider');
@@ -72,7 +73,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
     if (!res.ok) {
       const text = await res.text();
       log.error({ status: res.status, body: text }, 'Twilio initiateCall failed');
-      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 { sid: string };
@@ -99,7 +100,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
     if (!res.ok) {
       const text = await res.text();
       log.error({ status: res.status, body: text, callSid }, 'Twilio endCall failed');
-      throw new Error(`Twilio API error ${res.status}: ${text}`);
+      throw new ProviderError(`Twilio API error ${res.status}: ${text}`, 'twilio', res.status);
     }
 
     log.info({ callSid }, 'Twilio call ended');
@@ -118,7 +119,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
     if (!res.ok) {
       const text = await res.text();
       log.error({ status: res.status, body: text, callSid }, 'Twilio getCallStatus failed');
-      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 { status: string };
@@ -203,8 +204,9 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
         ...(!incomingOk ? [`IncomingPhoneNumbers: ${incomingRes.status}`] : []),
         ...(!outgoingOk ? [`OutgoingCallerIds: ${outgoingRes.status}`] : []),
       ].join(', ');
-      throw new Error(
+      throw new ProviderError(
         `Unable to verify caller ID eligibility for ${phoneNumber}: Twilio API error (${failedEndpoints}). The number may be eligible but could not be confirmed. Please check your Twilio credentials and try again.`,
+        'twilio',
       );
     }
 

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 {
@@ -155,6 +156,38 @@ export async function provisionPhoneNumber(
   };
 }
 
+/** Fetch the current status of a Twilio message by SID. */
+export async function fetchMessageStatus(
+  accountSid: string,
+  authToken: string,
+  messageSid: string,
+): Promise<{ status: string; errorCode?: string; errorMessage?: string }> {
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/Messages/${encodeURIComponent(messageSid)}.json`,
+    {
+      method: 'GET',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new ProviderError(`Twilio API error ${res.status}: ${text}`, 'twilio', res.status);
+  }
+
+  const data = (await res.json()) as {
+    status?: string;
+    error_code?: number | null;
+    error_message?: string | null;
+  };
+
+  return {
+    status: data.status ?? 'unknown',
+    errorCode: data.error_code != null ? String(data.error_code) : undefined,
+    errorMessage: data.error_message ?? undefined,
+  };
+}
+
 export interface WebhookUrls {
   voiceUrl: string;
   statusCallbackUrl: string;
@@ -185,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 {
@@ -194,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
@@ -221,6 +254,274 @@ 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);
+  }
+}
+
+// ── Toll-Free Verification ──────────────────────────────────────────────
+
+/** Twilio Messaging API base URL for toll-free verification endpoints. */
+const TOLLFREE_VERIFICATION_BASE = 'https://messaging.twilio.com/v1/Tollfree/Verifications';
+
+export interface TollFreeVerification {
+  sid: string;
+  status: string;
+  rejectionReason?: string;
+  rejectionReasons?: string[];
+  errorCode?: string;
+  editAllowed?: boolean;
+  editExpiration?: string;
+  regulationType?: string;
+}
+
+function parseTollFreeVerification(raw: Record<string, unknown>): TollFreeVerification {
+  return {
+    sid: raw.sid as string,
+    status: raw.status as string,
+    rejectionReason: (raw.rejection_reason as string) ?? undefined,
+    rejectionReasons: (raw.rejection_reasons as string[]) ?? undefined,
+    errorCode: (raw.error_code != null ? String(raw.error_code) : undefined),
+    editAllowed: (raw.edit_allowed as boolean) ?? undefined,
+    editExpiration: (raw.edit_expiration as string) ?? undefined,
+    regulationType: (raw.regulation_type as string) ?? undefined,
+  };
+}
+
+/**
+ * Get toll-free verification status for a phone number.
+ * If `phoneNumberSid` is provided, filters by that SID; otherwise returns the
+ * first verification found.
+ */
+export async function getTollFreeVerificationStatus(
+  accountSid: string,
+  authToken: string,
+  phoneNumberSid?: string,
+): Promise<TollFreeVerification | null> {
+  const params = new URLSearchParams();
+  if (phoneNumberSid) params.set('TollfreePhoneNumberSid', phoneNumberSid);
+
+  const url = params.toString()
+    ? `${TOLLFREE_VERIFICATION_BASE}?${params.toString()}`
+    : TOLLFREE_VERIFICATION_BASE;
+
+  const res = await fetch(url, {
+    method: 'GET',
+    headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+  });
+
+  if (!res.ok) {
+    const text = await res.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>> };
+  const verifications = data.verifications ?? [];
+  if (verifications.length === 0) return null;
+
+  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;
+  businessWebsite: string;
+  notificationEmail: string;
+  useCaseCategories: string[];
+  useCaseSummary: string;
+  productionMessageSample: string;
+  optInImageUrls: string[];
+  optInType: string;
+  messageVolume: string;
+  businessType?: string;
+  customerProfileSid?: string;
+}
+
+/** Submit a new toll-free verification request. */
+export async function submitTollFreeVerification(
+  accountSid: string,
+  authToken: string,
+  params: TollFreeVerificationSubmitParams,
+): Promise<TollFreeVerification> {
+  const body = new URLSearchParams();
+  body.set('TollfreePhoneNumberSid', params.tollfreePhoneNumberSid);
+  body.set('BusinessName', params.businessName);
+  body.set('BusinessWebsite', params.businessWebsite);
+  body.set('NotificationEmail', params.notificationEmail);
+  body.set('UseCaseSummary', params.useCaseSummary);
+  body.set('ProductionMessageSample', params.productionMessageSample);
+  body.set('OptInType', params.optInType);
+  body.set('MessageVolume', params.messageVolume);
+  body.set('BusinessType', params.businessType ?? 'SOLE_PROPRIETOR');
+
+  for (const cat of params.useCaseCategories) {
+    body.append('UseCaseCategories', cat);
+  }
+  for (const url of params.optInImageUrls) {
+    body.append('OptInImageUrls', url);
+  }
+  if (params.customerProfileSid) {
+    body.set('CustomerProfileSid', params.customerProfileSid);
+  }
+
+  const res = await fetch(TOLLFREE_VERIFICATION_BASE, {
+    method: 'POST',
+    headers: {
+      Authorization: twilioAuthHeader(accountSid, authToken),
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    const text = await res.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>;
+  return parseTollFreeVerification(data);
+}
+
+/** Update an existing toll-free verification. */
+export async function updateTollFreeVerification(
+  accountSid: string,
+  authToken: string,
+  verificationSid: string,
+  params: Partial<TollFreeVerificationSubmitParams>,
+): Promise<TollFreeVerification> {
+  const body = new URLSearchParams();
+  if (params.businessName) body.set('BusinessName', params.businessName);
+  if (params.businessWebsite) body.set('BusinessWebsite', params.businessWebsite);
+  if (params.notificationEmail) body.set('NotificationEmail', params.notificationEmail);
+  if (params.useCaseSummary) body.set('UseCaseSummary', params.useCaseSummary);
+  if (params.productionMessageSample) body.set('ProductionMessageSample', params.productionMessageSample);
+  if (params.optInType) body.set('OptInType', params.optInType);
+  if (params.messageVolume) body.set('MessageVolume', params.messageVolume);
+  if (params.businessType) body.set('BusinessType', params.businessType);
+  if (params.useCaseCategories) {
+    for (const cat of params.useCaseCategories) {
+      body.append('UseCaseCategories', cat);
+    }
+  }
+  if (params.optInImageUrls) {
+    for (const url of params.optInImageUrls) {
+      body.append('OptInImageUrls', url);
+    }
+  }
+  if (params.customerProfileSid) body.set('CustomerProfileSid', params.customerProfileSid);
+
+  const res = await fetch(`${TOLLFREE_VERIFICATION_BASE}/${encodeURIComponent(verificationSid)}`, {
+    method: 'POST',
+    headers: {
+      Authorization: twilioAuthHeader(accountSid, authToken),
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    const text = await res.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>;
+  return parseTollFreeVerification(data);
+}
+
+/** Delete a toll-free verification. */
+export async function deleteTollFreeVerification(
+  accountSid: string,
+  authToken: string,
+  verificationSid: string,
+): Promise<void> {
+  const res = await fetch(`${TOLLFREE_VERIFICATION_BASE}/${encodeURIComponent(verificationSid)}`, {
+    method: 'DELETE',
+    headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new ProviderError(`Twilio Toll-Free Verification delete error ${res.status}: ${text}`, 'twilio', res.status);
+  }
+}
+
+/**
+ * Get the SID for an incoming phone number.
+ * Looks up the number via `IncomingPhoneNumbers.json?PhoneNumber=...`.
+ */
+export async function getPhoneNumberSid(
+  accountSid: string,
+  authToken: string,
+  phoneNumber: string,
+): Promise<string | null> {
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers.json?PhoneNumber=${encodeURIComponent(phoneNumber)}`,
+    {
+      method: 'GET',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new ProviderError(`Twilio API error ${res.status} looking up phone number SID: ${text}`, 'twilio', res.status);
+  }
+
+  const data = (await res.json()) as {
+    incoming_phone_numbers: Array<{ sid: string; phone_number: string }>;
+  };
+
+  const match = data.incoming_phone_numbers.find((n) => n.phone_number === phoneNumber);
+  return match?.sid ?? null;
+}
+
+/**
+ * Release (delete) an incoming phone number from the Twilio account.
+ * Looks up the SID by phone number then sends a DELETE request.
+ */
+export async function releasePhoneNumber(
+  accountSid: string,
+  authToken: string,
+  phoneNumber: string,
+): Promise<void> {
+  const sid = await getPhoneNumberSid(accountSid, authToken, phoneNumber);
+  if (!sid) {
+    throw new ProviderError(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`, 'twilio');
+  }
+
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers/${sid}.json`,
+    {
+      method: 'DELETE',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.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,7 +26,9 @@ 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');
 
@@ -43,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)}"
@@ -63,6 +69,16 @@ export function generateTwiML(
 </Response>`;
 }
 
+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 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 '';
+}
+
 /**
  * Resolve the WebSocket relay URL from Twilio config.
  *
@@ -106,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');
@@ -127,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');
@@ -175,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());
@@ -183,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 = process.env.CALL_WELCOME_GREETING ?? 'Hello, how can I help you today?';
+  const welcomeGreeting = buildWelcomeGreeting(task, getCallWelcomeGreeting());
 
   const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, profile);
 
@@ -270,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;
+}