vellum 0.2.1 → 0.2.7

package/src/calls/relay-server.ts

@@ -14,6 +14,11 @@ import {
   recordCallEvent,
 } from './call-store.js';
 import { CallOrchestrator } from './call-orchestrator.js';
+import {
+  extractPromptSpeakerMetadata,
+  SpeakerIdentityTracker,
+  type PromptSpeakerContext,
+} from './speaker-identification.js';
 
 const log = getLogger('relay-server');
 
@@ -33,6 +38,23 @@ export interface RelayPromptMessage {
   voicePrompt: string;
   lang: string;
   last: boolean;
+  speakerId?: string;
+  speakerLabel?: string;
+  speakerName?: string;
+  speakerConfidence?: number;
+  participantId?: string;
+  participant?: {
+    id?: string;
+    name?: string;
+  };
+  speaker?: {
+    id?: string;
+    label?: string;
+    name?: string;
+    confidence?: number;
+  };
+  metadata?: Record<string, unknown>;
+  providerMetadata?: Record<string, unknown>;
 }
 
 export interface RelayInterruptMessage {
@@ -88,15 +110,22 @@ export const activeRelayConnections = new Map<string, RelayConnection>();
 export class RelayConnection {
   private ws: ServerWebSocket<RelayWebSocketData>;
   private callSessionId: string;
-  private conversationHistory: Array<{ role: 'caller' | 'assistant'; text: string; timestamp: number }>;
+  private conversationHistory: Array<{
+    role: 'caller' | 'assistant';
+    text: string;
+    timestamp: number;
+    speaker?: PromptSpeakerContext;
+  }>;
   private abortController: AbortController;
   private orchestrator: CallOrchestrator | null = null;
+  private speakerIdentityTracker: SpeakerIdentityTracker;
 
   constructor(ws: ServerWebSocket<RelayWebSocketData>, callSessionId: string) {
     this.ws = ws;
     this.callSessionId = callSessionId;
     this.conversationHistory = [];
     this.abortController = new AbortController();
+    this.speakerIdentityTracker = new SpeakerIdentityTracker();
   }
 
   /**
@@ -162,8 +191,8 @@ export class RelayConnection {
   /**
    * Get the conversation history for context.
    */
-  getConversationHistory(): Array<{ role: string; text: string }> {
-    return this.conversationHistory.map(({ role, text }) => ({ role, text }));
+  getConversationHistory(): Array<{ role: string; text: string; speaker?: PromptSpeakerContext }> {
+    return this.conversationHistory.map(({ role, text, speaker }) => ({ role, text, speaker }));
   }
 
   /**
@@ -236,22 +265,30 @@ export class RelayConnection {
       'Caller transcript received (final)',
     );
 
+    const speakerMetadata = extractPromptSpeakerMetadata(msg as unknown as Record<string, unknown>);
+    const speaker = this.speakerIdentityTracker.identifySpeaker(speakerMetadata);
+
     // Record in conversation history
     this.conversationHistory.push({
       role: 'caller',
       text: msg.voicePrompt,
       timestamp: Date.now(),
+      speaker,
     });
 
     // Record event
     recordCallEvent(this.callSessionId, 'caller_spoke', {
       transcript: msg.voicePrompt,
       lang: msg.lang,
+      speakerId: speaker.speakerId,
+      speakerLabel: speaker.speakerLabel,
+      speakerConfidence: speaker.speakerConfidence,
+      speakerSource: speaker.source,
     });
 
     // Route to orchestrator for LLM-driven response
     if (this.orchestrator) {
-      await this.orchestrator.handleCallerUtterance(msg.voicePrompt);
+      await this.orchestrator.handleCallerUtterance(msg.voicePrompt, speaker);
     } else {
       // Fallback if orchestrator not yet initialized
       this.sendTextToken('I\'m still setting up. Please hold.', true);

package/src/calls/speaker-identification.ts

@@ -0,0 +1,213 @@
+export interface PromptSpeakerContext {
+  speakerId: string;
+  speakerLabel: string;
+  speakerConfidence: number | null;
+  source: 'provider' | 'inferred';
+}
+
+export interface PromptSpeakerMetadata {
+  speakerId?: string;
+  speakerLabel?: string;
+  speakerName?: string;
+  speakerConfidence?: number;
+  participantId?: string;
+}
+
+interface SpeakerProfile {
+  speakerId: string;
+  speakerLabel: string;
+  speakerConfidence: number | null;
+  source: 'provider' | 'inferred';
+  utteranceCount: number;
+  firstSeenAt: number;
+  lastSeenAt: number;
+}
+
+function toCleanString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function toNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function getObject(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function normalizeSpeakerLabel(metadata: PromptSpeakerMetadata, fallbackIndex: number): string {
+  const preferredLabel = toCleanString(metadata.speakerName) ?? toCleanString(metadata.speakerLabel);
+  if (preferredLabel) return preferredLabel;
+  return `Speaker ${fallbackIndex}`;
+}
+
+export function extractPromptSpeakerMetadata(message: Record<string, unknown>): PromptSpeakerMetadata {
+  const providerMetadata = getObject(message.providerMetadata);
+  const metadata = getObject(message.metadata);
+  const participant = getObject(message.participant);
+  const speaker = getObject(message.speaker);
+
+  const pick = (...values: unknown[]): string | undefined => {
+    for (const value of values) {
+      const cleaned = toCleanString(value);
+      if (cleaned) return cleaned;
+    }
+    return undefined;
+  };
+
+  const pickNumber = (...values: unknown[]): number | undefined => {
+    for (const value of values) {
+      const parsed = toNumber(value);
+      if (parsed !== null) return parsed;
+    }
+    return undefined;
+  };
+
+  return {
+    speakerId: pick(
+      message.speakerId,
+      message.speaker_id,
+      speaker?.id,
+      speaker?.speakerId,
+      metadata?.speakerId,
+      providerMetadata?.speakerId,
+      metadata?.speaker_id,
+      providerMetadata?.speaker_id,
+    ),
+    speakerLabel: pick(
+      message.speakerLabel,
+      message.speaker_label,
+      message.speaker,
+      speaker?.label,
+      speaker?.name,
+      metadata?.speakerLabel,
+      providerMetadata?.speakerLabel,
+      metadata?.speaker_label,
+      providerMetadata?.speaker_label,
+    ),
+    speakerName: pick(
+      message.speakerName,
+      message.speaker_name,
+      participant?.name,
+      metadata?.speakerName,
+      providerMetadata?.speakerName,
+      metadata?.speaker_name,
+      providerMetadata?.speaker_name,
+    ),
+    speakerConfidence: pickNumber(
+      message.speakerConfidence,
+      message.speaker_confidence,
+      message.confidence,
+      speaker?.confidence,
+      metadata?.speakerConfidence,
+      providerMetadata?.speakerConfidence,
+      metadata?.speaker_confidence,
+      providerMetadata?.speaker_confidence,
+    ),
+    participantId: pick(
+      message.participantId,
+      message.participant_id,
+      participant?.id,
+      metadata?.participantId,
+      providerMetadata?.participantId,
+      metadata?.participant_id,
+      providerMetadata?.participant_id,
+    ),
+  };
+}
+
+export class SpeakerIdentityTracker {
+  private profiles = new Map<string, SpeakerProfile>();
+  private nextInferredIndex = 1;
+
+  identifySpeaker(metadata: PromptSpeakerMetadata): PromptSpeakerContext {
+    const providerSpeakerId =
+      toCleanString(metadata.speakerId)
+      ?? toCleanString(metadata.participantId)
+      ?? null;
+
+    if (providerSpeakerId) {
+      const existing = this.profiles.get(providerSpeakerId);
+      if (existing) {
+        existing.lastSeenAt = Date.now();
+        existing.utteranceCount += 1;
+        if (metadata.speakerConfidence !== undefined) {
+          existing.speakerConfidence = metadata.speakerConfidence;
+        }
+        return {
+          speakerId: existing.speakerId,
+          speakerLabel: existing.speakerLabel,
+          speakerConfidence: existing.speakerConfidence,
+          source: existing.source,
+        };
+      }
+
+      const profile: SpeakerProfile = {
+        speakerId: providerSpeakerId,
+        speakerLabel: normalizeSpeakerLabel(metadata, this.nextInferredIndex),
+        speakerConfidence: metadata.speakerConfidence ?? null,
+        source: 'provider',
+        utteranceCount: 1,
+        firstSeenAt: Date.now(),
+        lastSeenAt: Date.now(),
+      };
+      this.profiles.set(providerSpeakerId, profile);
+      this.nextInferredIndex += 1;
+      return {
+        speakerId: profile.speakerId,
+        speakerLabel: profile.speakerLabel,
+        speakerConfidence: profile.speakerConfidence,
+        source: profile.source,
+      };
+    }
+
+    const inferredSpeakerId = 'primary-speaker';
+    const existingPrimary = this.profiles.get(inferredSpeakerId);
+    if (existingPrimary) {
+      existingPrimary.lastSeenAt = Date.now();
+      existingPrimary.utteranceCount += 1;
+      return {
+        speakerId: existingPrimary.speakerId,
+        speakerLabel: existingPrimary.speakerLabel,
+        speakerConfidence: existingPrimary.speakerConfidence,
+        source: existingPrimary.source,
+      };
+    }
+
+    const inferredProfile: SpeakerProfile = {
+      speakerId: inferredSpeakerId,
+      speakerLabel: normalizeSpeakerLabel(metadata, this.nextInferredIndex),
+      speakerConfidence: metadata.speakerConfidence ?? null,
+      source: 'inferred',
+      utteranceCount: 1,
+      firstSeenAt: Date.now(),
+      lastSeenAt: Date.now(),
+    };
+    this.profiles.set(inferredSpeakerId, inferredProfile);
+    this.nextInferredIndex += 1;
+
+    return {
+      speakerId: inferredProfile.speakerId,
+      speakerLabel: inferredProfile.speakerLabel,
+      speakerConfidence: inferredProfile.speakerConfidence,
+      source: inferredProfile.source,
+    };
+  }
+
+  listProfiles(): PromptSpeakerContext[] {
+    return [...this.profiles.values()].map((profile) => ({
+      speakerId: profile.speakerId,
+      speakerLabel: profile.speakerLabel,
+      speakerConfidence: profile.speakerConfidence,
+      source: profile.source,
+    }));
+  }
+}

package/src/calls/twilio-config.ts

@@ -1,5 +1,7 @@
 import { getSecureKey } from '../security/secure-keys.js';
 import { getLogger } from '../util/logger.js';
+import { loadConfig } from '../config/loader.js';
+import { getWebhookBaseUrl } from './twilio-webhook-urls.js';
 
 const log = getLogger('twilio-config');
 
@@ -12,21 +14,19 @@ export interface TwilioConfig {
 }
 
 export function getTwilioConfig(): TwilioConfig {
-  const accountSid = getSecureKey('twilio_account_sid');
-  const authToken = getSecureKey('twilio_auth_token');
-  const phoneNumber = process.env.TWILIO_PHONE_NUMBER || getSecureKey('twilio_phone_number') || '';
-  const webhookBaseUrl = process.env.TWILIO_WEBHOOK_BASE_URL || '';
+  const accountSid = getSecureKey('credential:twilio:account_sid');
+  const authToken = getSecureKey('credential:twilio:auth_token');
+  const phoneNumber = process.env.TWILIO_PHONE_NUMBER || getSecureKey('credential:twilio:phone_number') || '';
+  const config = loadConfig();
+  const webhookBaseUrl = getWebhookBaseUrl(config);
   const wssBaseUrl = process.env.TWILIO_WSS_BASE_URL || '';
 
   if (!accountSid || !authToken) {
-    throw new Error('Twilio credentials not configured. Set twilio_account_sid and twilio_auth_token via the credential_store tool.');
+    throw new Error('Twilio credentials not configured. Set credential:twilio:account_sid and credential:twilio:auth_token via the credential_store tool.');
   }
   if (!phoneNumber) {
     throw new Error('TWILIO_PHONE_NUMBER not configured.');
   }
-  if (!webhookBaseUrl) {
-    throw new Error('TWILIO_WEBHOOK_BASE_URL not configured.');
-  }
 
   log.debug('Twilio config loaded successfully');
 

package/src/calls/twilio-provider.ts

@@ -17,11 +17,11 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
   // ── Credential helpers ──────────────────────────────────────────────
 
   private getCredentials(): { accountSid: string; authToken: string } {
-    const accountSid = getSecureKey('twilio_account_sid');
-    const authToken = getSecureKey('twilio_auth_token');
+    const accountSid = getSecureKey('credential:twilio:account_sid');
+    const authToken = getSecureKey('credential:twilio:auth_token');
     if (!accountSid || !authToken) {
       throw new Error(
-        'Twilio credentials not configured. Set twilio_account_sid and twilio_auth_token via the credential_store tool.',
+        'Twilio credentials not configured. Set credential:twilio:account_sid and credential:twilio:auth_token via the credential_store tool.',
       );
     }
     return { accountSid, authToken };
@@ -128,6 +128,15 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
 
   // ── Webhook signature verification ──────────────────────────────────
 
+  /**
+   * Returns the Twilio auth token from the secure key store, or null if
+   * not configured. Exposed as a static method so callers (e.g. the
+   * HTTP server webhook middleware) can check availability independently.
+   */
+  static getAuthToken(): string | null {
+    return getSecureKey('credential:twilio:auth_token') ?? null;
+  }
+
   /**
    * Validates an X-Twilio-Signature header using HMAC-SHA1.
    *
@@ -143,13 +152,8 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
     url: string,
     params: Record<string, string>,
     signature: string,
+    authToken: string,
   ): boolean {
-    const authToken = getSecureKey('twilio_auth_token');
-    if (!authToken) {
-      log.error('Cannot verify Twilio webhook signature: auth token not configured');
-      return false;
-    }
-
     const sortedKeys = Object.keys(params).sort();
     let data = url;
     for (const key of sortedKeys) {

package/src/calls/twilio-routes.ts

@@ -13,11 +13,15 @@ import {
   updateCallSession,
   recordCallEvent,
   expirePendingQuestions,
-  getPendingQuestion,
-  answerPendingQuestion,
+  buildCallbackDedupeKey,
+  claimCallback,
+  releaseCallbackClaim,
+  finalizeCallbackClaim,
 } from './call-store.js';
 import type { CallStatus } from './types.js';
-import { getCallOrchestrator } from './call-state.js';
+import { logDeadLetterEvent } from './call-recovery.js';
+import { isTerminalState } from './call-state-machine.js';
+import { getTwilioConfig } from './twilio-config.js';
 
 const log = getLogger('twilio-routes');
 
@@ -32,12 +36,12 @@ function escapeXml(str: string): string {
     .replace(/'/g, ''');
 }
 
-function generateTwiML(callSessionId: string, wssBaseUrl: string, welcomeGreeting: string): string {
+function generateTwiML(callSessionId: string, relayUrl: string, welcomeGreeting: string): string {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <Response>
   <Connect>
     <ConversationRelay
-      url="${escapeXml(wssBaseUrl)}/v1/calls/relay?callSessionId=${escapeXml(callSessionId)}"
+      url="${escapeXml(relayUrl)}?callSessionId=${escapeXml(callSessionId)}"
       welcomeGreeting="${escapeXml(welcomeGreeting)}"
       voice="Google.en-US-Journey-O"
       language="en-US"
@@ -50,6 +54,19 @@ function generateTwiML(callSessionId: string, wssBaseUrl: string, welcomeGreetin
 </Response>`;
 }
 
+/**
+ * Resolve the WebSocket relay URL from Twilio config.
+ *
+ * Treats wssBaseUrl as present only when it is non-empty after trimming.
+ * 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 {
+  const base = wssBaseUrl.trim() || webhookBaseUrl;
+  const normalized = base.replace(/\/$/, '').replace(/^http(s?)/, 'ws$1');
+  return `${normalized}/v1/calls/relay`;
+}
+
 /**
  * Map Twilio call status strings to our internal CallStatus.
  */
@@ -93,6 +110,11 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     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 });
+  }
+
   // 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.
@@ -103,10 +125,11 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     log.info({ callSessionId, callSid }, 'Stored CallSid from voice webhook');
   }
 
-  const wssBaseUrl = process.env.WSS_BASE_URL ?? process.env.BASE_URL ?? 'wss://localhost:7821';
+  const config = getTwilioConfig();
+  const relayUrl = resolveRelayUrl(config.wssBaseUrl, config.webhookBaseUrl);
   const welcomeGreeting = process.env.CALL_WELCOME_GREETING ?? 'Hello, how can I help you today?';
 
-  const twiml = generateTwiML(callSessionId, wssBaseUrl, welcomeGreeting);
+  const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting);
 
   log.info({ callSessionId }, 'Returning ConversationRelay TwiML');
 
@@ -126,7 +149,8 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
   const callStatus = formBody.get('CallStatus');
 
   if (!callSid || !callStatus) {
-    log.warn({ callSid, callStatus }, 'Status callback missing CallSid or CallStatus');
+    const rawPayload = Object.fromEntries(formBody.entries());
+    logDeadLetterEvent('Status callback missing CallSid or CallStatus', rawPayload, log);
     return new Response(null, { status: 200 });
   }
 
@@ -140,39 +164,70 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
 
   const mappedStatus = mapTwilioStatus(callStatus);
   if (!mappedStatus) {
-    log.warn({ callSid, callStatus }, 'Status callback: unknown Twilio status');
+    const rawPayload = Object.fromEntries(formBody.entries());
+    logDeadLetterEvent(`Unknown Twilio status: ${callStatus}`, rawPayload, log);
     return new Response(null, { status: 200 });
   }
 
-  // Build updates
-  const updates: Parameters<typeof updateCallSession>[1] = {
-    status: mappedStatus,
-  };
+  // ── Atomic idempotency claim ────────────────────────────────────
+  const timestamp = formBody.get('Timestamp');
+  const sequenceNumber = formBody.get('SequenceNumber');
+  const dedupeKey = buildCallbackDedupeKey(callSid, callStatus, timestamp, sequenceNumber);
 
-  if (mappedStatus === 'in_progress' && !session.startedAt) {
-    updates.startedAt = Date.now();
-  }
-
-  const isTerminal = mappedStatus === 'completed' || mappedStatus === 'failed';
-  if (isTerminal) {
-    updates.endedAt = Date.now();
+  const claimId = claimCallback(dedupeKey, session.id);
+  if (!claimId) {
+    log.info({ callSid, callStatus, dedupeKey }, 'Duplicate status callback — skipping');
+    return new Response(null, { status: 200 });
   }
 
-  updateCallSession(session.id, updates);
-
-  // Record event
-  const eventType = isTerminal
-    ? (mappedStatus === 'completed' ? 'call_ended' : 'call_failed')
-    : (mappedStatus === 'in_progress' ? 'call_connected' : 'call_started');
-
-  recordCallEvent(session.id, eventType, {
-    twilioStatus: callStatus,
-    callSid,
-  });
-
-  // Expire pending questions on terminal status
-  if (isTerminal) {
-    expirePendingQuestions(session.id);
+  try {
+    // Build updates
+    const updates: Parameters<typeof updateCallSession>[1] = {
+      status: mappedStatus,
+    };
+
+    if (mappedStatus === 'in_progress' && !session.startedAt) {
+      updates.startedAt = Date.now();
+    }
+
+    const isTerminal = mappedStatus === 'completed' || mappedStatus === 'failed';
+    if (isTerminal) {
+      updates.endedAt = Date.now();
+    }
+
+    updateCallSession(session.id, updates);
+
+    // Record event
+    const eventType = isTerminal
+      ? (mappedStatus === 'completed' ? 'call_ended' : 'call_failed')
+      : (mappedStatus === 'in_progress' ? 'call_connected' : 'call_started');
+
+    recordCallEvent(session.id, eventType, {
+      twilioStatus: callStatus,
+      callSid,
+    });
+
+    // Expire pending questions on terminal status
+    if (isTerminal) {
+      expirePendingQuestions(session.id);
+    }
+
+    // Mark the claim as permanently processed so it never expires.
+    // If finalization returns false, another handler reclaimed this key
+    // after our claim expired — our business writes already landed but
+    // the dedupe row now belongs to the other handler, risking duplicate
+    // processing on later retries.
+    const finalized = finalizeCallbackClaim(dedupeKey, claimId);
+    if (!finalized) {
+      log.warn(
+        { dedupeKey, claimId, callSid, callStatus },
+        'Lost claim during finalization — business writes committed but dedupe ownership was taken by another handler',
+      );
+    }
+  } catch (err) {
+    // Release claim so Twilio retries can reprocess
+    releaseCallbackClaim(dedupeKey, claimId);
+    throw err;
   }
 
   return new Response(null, { status: 200 });
@@ -193,44 +248,3 @@ export async function handleConnectAction(_req: Request): Promise<Response> {
   );
 }
 
-/**
- * Answer a pending question for an active call.
- * POST /v1/calls/:callSessionId/answer
- * Body: { answer: string }
- */
-export async function handleCallAnswer(req: Request, callSessionId: string): Promise<Response> {
-  const body = await req.json() as { answer?: string };
-  if (!body.answer) {
-    return Response.json({ error: 'Missing answer' }, { status: 400 });
-  }
-
-  const question = getPendingQuestion(callSessionId);
-  if (!question) {
-    return Response.json({ error: 'No pending question found' }, { status: 404 });
-  }
-
-  // Verify the orchestrator exists before attempting to route the answer.
-  const orchestrator = getCallOrchestrator(callSessionId);
-  if (!orchestrator) {
-    log.warn({ callSessionId }, 'handleCallAnswer: no active orchestrator for call session');
-    return Response.json({ error: 'No active orchestrator for this call' }, { status: 409 });
-  }
-
-  // Route answer to the orchestrator FIRST — it atomically checks whether it is
-  // in the `waiting_on_user` state and transitions to `processing`. Only persist
-  // the answer to the DB if the orchestrator actually accepted it, preventing a
-  // race where the consultation timer expires between our check and the persist.
-  const accepted = await orchestrator.handleUserAnswer(body.answer);
-  if (!accepted) {
-    log.warn(
-      { callSessionId },
-      'handleCallAnswer: orchestrator rejected the answer (not in waiting_on_user state)',
-    );
-    return Response.json({ error: 'Orchestrator is not waiting for an answer' }, { status: 409 });
-  }
-
-  // Mark question as answered — only after the orchestrator has accepted
-  answerPendingQuestion(question.id, body.answer);
-
-  return Response.json({ ok: true, questionId: question.id });
-}

package/src/calls/twilio-webhook-urls.ts

@@ -0,0 +1,50 @@
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('twilio-webhook-urls');
+
+/**
+ * Resolve the webhook base URL from config, falling back to the
+ * TWILIO_WEBHOOK_BASE_URL environment variable with a deprecation warning.
+ * Throws if neither source provides a value.
+ */
+export function getWebhookBaseUrl(config: { calls: { webhookBaseUrl?: string } }): string {
+  const configValue = config.calls.webhookBaseUrl;
+  if (configValue) {
+    const normalized = normalizeBaseUrl(configValue);
+    if (normalized) return normalized;
+  }
+
+  const envValue = process.env.TWILIO_WEBHOOK_BASE_URL;
+  if (envValue) {
+    log.warn(
+      'TWILIO_WEBHOOK_BASE_URL env var is deprecated — set calls.webhookBaseUrl in config instead.',
+    );
+    const normalized = normalizeBaseUrl(envValue);
+    if (normalized) return normalized;
+  }
+
+  throw new Error(
+    'No webhook base URL configured. Set calls.webhookBaseUrl in config or TWILIO_WEBHOOK_BASE_URL env var.',
+  );
+}
+
+/**
+ * Trim whitespace and strip trailing slash from a URL string.
+ */
+export function normalizeBaseUrl(url: string): string {
+  return url.trim().replace(/\/+$/, '');
+}
+
+/**
+ * Build the Twilio voice webhook URL for a given call session.
+ */
+export function buildTwilioVoiceWebhookUrl(baseUrl: string, callSessionId: string): string {
+  return `${normalizeBaseUrl(baseUrl)}/webhooks/twilio/voice?callSessionId=${callSessionId}`;
+}
+
+/**
+ * Build the Twilio status callback URL.
+ */
+export function buildTwilioStatusCallbackUrl(baseUrl: string): string {
+  return `${normalizeBaseUrl(baseUrl)}/webhooks/twilio/status`;
+}

package/src/calls/types.ts

@@ -1,4 +1,4 @@
-export type CallStatus = 'initiated' | 'ringing' | 'in_progress' | 'waiting_on_user' | 'completed' | 'failed';
+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' | 'call_ended' | 'call_failed';
 export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';