vellum 0.2.0 → 0.2.2

package/src/calls/twilio-provider.ts

@@ -0,0 +1,173 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { getLogger } from '../util/logger.js';
+import { getSecureKey } from '../security/secure-keys.js';
+import type { VoiceProvider, InitiateCallOptions } from './voice-provider.js';
+
+const log = getLogger('twilio-provider');
+
+/**
+ * Twilio ConversationRelay voice provider.
+ *
+ * Uses the Twilio REST API directly via fetch() — no twilio npm package.
+ * Credentials are resolved lazily from the secure key store on each call.
+ */
+export class TwilioConversationRelayProvider implements VoiceProvider {
+  readonly name = 'twilio';
+
+  // ── Credential helpers ──────────────────────────────────────────────
+
+  private getCredentials(): { accountSid: string; authToken: string } {
+    const accountSid = getSecureKey('twilio_account_sid');
+    const authToken = getSecureKey('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.',
+      );
+    }
+    return { accountSid, authToken };
+  }
+
+  private authHeader(accountSid: string, authToken: string): string {
+    return 'Basic ' + Buffer.from(`${accountSid}:${authToken}`).toString('base64');
+  }
+
+  private baseUrl(accountSid: string): string {
+    return `https://api.twilio.com/2010-04-01/Accounts/${accountSid}`;
+  }
+
+  // ── VoiceProvider interface ─────────────────────────────────────────
+
+  async initiateCall(opts: InitiateCallOptions): Promise<{ callSid: string }> {
+    const { accountSid, authToken } = this.getCredentials();
+
+    const body = new URLSearchParams({
+      From: opts.from,
+      To: opts.to,
+      Url: opts.webhookUrl,
+      StatusCallback: opts.statusCallbackUrl,
+      StatusCallbackEvent: 'initiated ringing answered completed',
+    });
+
+    const reservedKeys = new Set(['From', 'To', 'Url', 'StatusCallback', 'StatusCallbackEvent']);
+    if (opts.customParams) {
+      for (const [key, value] of Object.entries(opts.customParams)) {
+        if (reservedKeys.has(key)) {
+          log.warn({ key }, 'Ignoring reserved Twilio parameter in customParams');
+          continue;
+        }
+        body.set(key, value);
+      }
+    }
+
+    log.info({ from: opts.from, to: opts.to }, 'Initiating Twilio call');
+
+    const res = await fetch(`${this.baseUrl(accountSid)}/Calls.json`, {
+      method: 'POST',
+      headers: {
+        Authorization: this.authHeader(accountSid, authToken),
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    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}`);
+    }
+
+    const data = (await res.json()) as { sid: string };
+    log.info({ callSid: data.sid }, 'Twilio call initiated');
+    return { callSid: data.sid };
+  }
+
+  async endCall(callSid: string): Promise<void> {
+    const { accountSid, authToken } = this.getCredentials();
+
+    log.info({ callSid }, 'Ending Twilio call');
+
+    const body = new URLSearchParams({ Status: 'completed' });
+
+    const res = await fetch(`${this.baseUrl(accountSid)}/Calls/${callSid}.json`, {
+      method: 'POST',
+      headers: {
+        Authorization: this.authHeader(accountSid, authToken),
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    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}`);
+    }
+
+    log.info({ callSid }, 'Twilio call ended');
+  }
+
+  async getCallStatus(callSid: string): Promise<string> {
+    const { accountSid, authToken } = this.getCredentials();
+
+    const res = await fetch(`${this.baseUrl(accountSid)}/Calls/${callSid}.json`, {
+      method: 'GET',
+      headers: {
+        Authorization: this.authHeader(accountSid, authToken),
+      },
+    });
+
+    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}`);
+    }
+
+    const data = (await res.json()) as { status: string };
+    return data.status;
+  }
+
+  // ── 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('twilio_auth_token') ?? null;
+  }
+
+  /**
+   * Validates an X-Twilio-Signature header using HMAC-SHA1.
+   *
+   * Algorithm (from Twilio docs):
+   * 1. Take the full URL of the request.
+   * 2. Sort the POST parameters alphabetically by key.
+   * 3. Concatenate the URL with each key-value pair (key + value, no delimiters).
+   * 4. HMAC-SHA1 the result using the auth token as the key.
+   * 5. Base64-encode the hash.
+   * 6. Compare to the X-Twilio-Signature header value.
+   */
+  static verifyWebhookSignature(
+    url: string,
+    params: Record<string, string>,
+    signature: string,
+    authToken: string,
+  ): boolean {
+    const sortedKeys = Object.keys(params).sort();
+    let data = url;
+    for (const key of sortedKeys) {
+      data += key + params[key];
+    }
+
+    const computed = createHmac('sha1', authToken)
+      .update(data)
+      .digest('base64');
+
+    // Constant-time comparison to prevent timing attacks
+    const a = Buffer.from(computed);
+    const b = Buffer.from(signature);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  }
+}

package/src/calls/twilio-routes.ts

@@ -0,0 +1,250 @@
+/**
+ * HTTP route handlers for Twilio voice webhooks.
+ *
+ * - handleVoiceWebhook: initial voice webhook; returns TwiML to connect ConversationRelay
+ * - handleStatusCallback: call status updates (ringing, in-progress, completed, etc.)
+ * - handleConnectAction: called when the ConversationRelay connection ends
+ */
+
+import { getLogger } from '../util/logger.js';
+import {
+  getCallSession,
+  getCallSessionByCallSid,
+  updateCallSession,
+  recordCallEvent,
+  expirePendingQuestions,
+  buildCallbackDedupeKey,
+  claimCallback,
+  releaseCallbackClaim,
+  finalizeCallbackClaim,
+} from './call-store.js';
+import type { CallStatus } from './types.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');
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function generateTwiML(callSessionId: string, relayUrl: string, welcomeGreeting: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Connect>
+    <ConversationRelay
+      url="${escapeXml(relayUrl)}?callSessionId=${escapeXml(callSessionId)}"
+      welcomeGreeting="${escapeXml(welcomeGreeting)}"
+      voice="Google.en-US-Journey-O"
+      language="en-US"
+      transcriptionProvider="Deepgram"
+      ttsProvider="Google"
+      interruptible="true"
+      dtmfDetection="true"
+    />
+  </Connect>
+</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.
+ */
+function mapTwilioStatus(twilioStatus: string): CallStatus | null {
+  switch (twilioStatus) {
+    case 'queued':
+    case 'ringing':
+      return 'ringing';
+    case 'in-progress':
+      return 'in_progress';
+    case 'completed':
+      return 'completed';
+    case 'failed':
+    case 'busy':
+    case 'no-answer':
+    case 'canceled':
+      return 'failed';
+    default:
+      return null;
+  }
+}
+
+// ── Route handlers ───────────────────────────────────────────────────
+
+/**
+ * Receives the initial voice webhook when Twilio connects the call.
+ * Returns TwiML XML that tells Twilio to open a ConversationRelay WebSocket.
+ */
+export async function handleVoiceWebhook(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const callSessionId = url.searchParams.get('callSessionId');
+
+  if (!callSessionId) {
+    log.warn('Voice webhook called without callSessionId');
+    return new Response('Missing callSessionId', { status: 400 });
+  }
+
+  const session = getCallSession(callSessionId);
+  if (!session) {
+    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 });
+  }
+
+  // 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');
+  if (callSid && callSid !== session.providerCallSid) {
+    updateCallSession(callSessionId, { providerCallSid: callSid });
+    log.info({ callSessionId, callSid }, 'Stored CallSid from voice webhook');
+  }
+
+  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, relayUrl, welcomeGreeting);
+
+  log.info({ callSessionId }, 'Returning ConversationRelay TwiML');
+
+  return new Response(twiml, {
+    status: 200,
+    headers: { 'Content-Type': 'text/xml' },
+  });
+}
+
+/**
+ * Receives call status updates from Twilio (POST with form-urlencoded body).
+ * Updates the call session status and records events.
+ */
+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');
+
+  if (!callSid || !callStatus) {
+    const rawPayload = Object.fromEntries(formBody.entries());
+    logDeadLetterEvent('Status callback missing CallSid or CallStatus', rawPayload, log);
+    return new Response(null, { status: 200 });
+  }
+
+  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');
+    return new Response(null, { status: 200 });
+  }
+
+  const mappedStatus = mapTwilioStatus(callStatus);
+  if (!mappedStatus) {
+    const rawPayload = Object.fromEntries(formBody.entries());
+    logDeadLetterEvent(`Unknown Twilio status: ${callStatus}`, rawPayload, log);
+    return new Response(null, { status: 200 });
+  }
+
+  // ── Atomic idempotency claim ────────────────────────────────────
+  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');
+    return new Response(null, { status: 200 });
+  }
+
+  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 });
+}
+
+/**
+ * Called when the ConversationRelay connection ends.
+ * 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' },
+    },
+  );
+}
+

package/src/calls/types.ts

@@ -0,0 +1,37 @@
+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';
+
+export interface CallSession {
+  id: string;
+  conversationId: string;
+  provider: string;
+  providerCallSid: string | null;
+  fromNumber: string;
+  toNumber: string;
+  task: string | null;
+  status: CallStatus;
+  startedAt: number | null;
+  endedAt: number | null;
+  lastError: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface CallEvent {
+  id: string;
+  callSessionId: string;
+  eventType: CallEventType;
+  payloadJson: string;
+  createdAt: number;
+}
+
+export interface CallPendingQuestion {
+  id: string;
+  callSessionId: string;
+  questionText: string;
+  status: PendingQuestionStatus;
+  askedAt: number;
+  answeredAt: number | null;
+  answerText: string | null;
+}

package/src/calls/voice-provider.ts

@@ -0,0 +1,14 @@
+export interface InitiateCallOptions {
+  from: string;
+  to: string;
+  webhookUrl: string;
+  statusCallbackUrl: string;
+  customParams?: Record<string, string>;
+}
+
+export interface VoiceProvider {
+  name: string;
+  initiateCall(opts: InitiateCallOptions): Promise<{ callSid: string }>;
+  endCall(callSid: string): Promise<void>;
+  getCallStatus(callSid: string): Promise<string>;
+}