vellum 0.2.0 → 0.2.1

package/src/calls/relay-server.ts

@@ -0,0 +1,298 @@
+/**
+ * WebSocket handler for Twilio ConversationRelay protocol.
+ *
+ * Manages real-time voice conversations over WebSocket. Each active call
+ * has a single RelayConnection instance that processes inbound messages
+ * from Twilio and can send text tokens back for TTS.
+ */
+
+import type { ServerWebSocket } from 'bun';
+import { getLogger } from '../util/logger.js';
+import {
+  getCallSession,
+  updateCallSession,
+  recordCallEvent,
+} from './call-store.js';
+import { CallOrchestrator } from './call-orchestrator.js';
+
+const log = getLogger('relay-server');
+
+// ── ConversationRelay message types ──────────────────────────────────
+
+// Messages FROM Twilio
+export interface RelaySetupMessage {
+  type: 'setup';
+  callSid: string;
+  from: string;
+  to: string;
+  customParameters?: Record<string, string>;
+}
+
+export interface RelayPromptMessage {
+  type: 'prompt';
+  voicePrompt: string;
+  lang: string;
+  last: boolean;
+}
+
+export interface RelayInterruptMessage {
+  type: 'interrupt';
+  utteranceUntilInterrupt: string;
+}
+
+export interface RelayDtmfMessage {
+  type: 'dtmf';
+  digit: string;
+}
+
+export interface RelayErrorMessage {
+  type: 'error';
+  description: string;
+}
+
+export type RelayInboundMessage =
+  | RelaySetupMessage
+  | RelayPromptMessage
+  | RelayInterruptMessage
+  | RelayDtmfMessage
+  | RelayErrorMessage;
+
+// Messages TO Twilio
+export interface RelayTextMessage {
+  type: 'text';
+  token: string;
+  last: boolean;
+}
+
+export interface RelayEndMessage {
+  type: 'end';
+  handoffData?: string;
+}
+
+// ── WebSocket data type ──────────────────────────────────────────────
+
+export interface RelayWebSocketData {
+  callSessionId: string;
+}
+
+// ── Module-level state ───────────────────────────────────────────────
+
+/** Active relay connections keyed by callSessionId. */
+export const activeRelayConnections = new Map<string, RelayConnection>();
+
+// ── RelayConnection ──────────────────────────────────────────────────
+
+/**
+ * Manages a single WebSocket connection for one call.
+ */
+export class RelayConnection {
+  private ws: ServerWebSocket<RelayWebSocketData>;
+  private callSessionId: string;
+  private conversationHistory: Array<{ role: 'caller' | 'assistant'; text: string; timestamp: number }>;
+  private abortController: AbortController;
+  private orchestrator: CallOrchestrator | null = null;
+
+  constructor(ws: ServerWebSocket<RelayWebSocketData>, callSessionId: string) {
+    this.ws = ws;
+    this.callSessionId = callSessionId;
+    this.conversationHistory = [];
+    this.abortController = new AbortController();
+  }
+
+  /**
+   * Handle an inbound message from Twilio via the ConversationRelay WebSocket.
+   */
+  async handleMessage(data: string): Promise<void> {
+    let parsed: RelayInboundMessage;
+    try {
+      parsed = JSON.parse(data) as RelayInboundMessage;
+    } catch {
+      log.warn({ callSessionId: this.callSessionId, data }, 'Failed to parse relay message');
+      return;
+    }
+
+    switch (parsed.type) {
+      case 'setup':
+        await this.handleSetup(parsed);
+        break;
+      case 'prompt':
+        await this.handlePrompt(parsed);
+        break;
+      case 'interrupt':
+        this.handleInterrupt(parsed);
+        break;
+      case 'dtmf':
+        this.handleDtmf(parsed);
+        break;
+      case 'error':
+        this.handleError(parsed);
+        break;
+      default:
+        log.warn({ callSessionId: this.callSessionId, type: (parsed as Record<string, unknown>).type }, 'Unknown relay message type');
+    }
+  }
+
+  /**
+   * Send a text token to the caller for TTS playback.
+   */
+  sendTextToken(token: string, last: boolean): void {
+    const message: RelayTextMessage = { type: 'text', token, last };
+    try {
+      this.ws.send(JSON.stringify(message));
+    } catch (err) {
+      log.error({ err, callSessionId: this.callSessionId }, 'Failed to send text token');
+    }
+  }
+
+  /**
+   * End the ConversationRelay session.
+   */
+  endSession(reason?: string): void {
+    const message: RelayEndMessage = { type: 'end' };
+    if (reason) {
+      message.handoffData = JSON.stringify({ reason });
+    }
+    try {
+      this.ws.send(JSON.stringify(message));
+    } catch (err) {
+      log.error({ err, callSessionId: this.callSessionId }, 'Failed to send end message');
+    }
+  }
+
+  /**
+   * Get the conversation history for context.
+   */
+  getConversationHistory(): Array<{ role: string; text: string }> {
+    return this.conversationHistory.map(({ role, text }) => ({ role, text }));
+  }
+
+  /**
+   * Get the call session ID for this connection.
+   */
+  getCallSessionId(): string {
+    return this.callSessionId;
+  }
+
+  /**
+   * Set the orchestrator for this connection.
+   */
+  setOrchestrator(orchestrator: CallOrchestrator): void {
+    this.orchestrator = orchestrator;
+  }
+
+  /**
+   * Get the orchestrator for this connection.
+   */
+  getOrchestrator(): CallOrchestrator | null {
+    return this.orchestrator;
+  }
+
+  /**
+   * Clean up resources on disconnect.
+   */
+  destroy(): void {
+    if (this.orchestrator) {
+      this.orchestrator.destroy();
+      this.orchestrator = null;
+    }
+    this.abortController.abort();
+    log.info({ callSessionId: this.callSessionId }, 'RelayConnection destroyed');
+  }
+
+  // ── Private handlers ─────────────────────────────────────────────
+
+  private async handleSetup(msg: RelaySetupMessage): Promise<void> {
+    log.info(
+      { callSessionId: this.callSessionId, callSid: msg.callSid, from: msg.from, to: msg.to },
+      'ConversationRelay setup received',
+    );
+
+    // Store the callSid association on the call session
+    const session = getCallSession(this.callSessionId);
+    if (session) {
+      updateCallSession(this.callSessionId, { providerCallSid: msg.callSid });
+    }
+
+    recordCallEvent(this.callSessionId, 'call_connected', {
+      callSid: msg.callSid,
+      from: msg.from,
+      to: msg.to,
+      customParameters: msg.customParameters,
+    });
+
+    // Create and attach the LLM-driven orchestrator
+    const orchestrator = new CallOrchestrator(this.callSessionId, this, session?.task ?? null);
+    this.setOrchestrator(orchestrator);
+  }
+
+  private async handlePrompt(msg: RelayPromptMessage): Promise<void> {
+    if (!msg.last) {
+      // Partial transcript, wait for final
+      return;
+    }
+
+    log.info(
+      { callSessionId: this.callSessionId, transcript: msg.voicePrompt, lang: msg.lang },
+      'Caller transcript received (final)',
+    );
+
+    // Record in conversation history
+    this.conversationHistory.push({
+      role: 'caller',
+      text: msg.voicePrompt,
+      timestamp: Date.now(),
+    });
+
+    // Record event
+    recordCallEvent(this.callSessionId, 'caller_spoke', {
+      transcript: msg.voicePrompt,
+      lang: msg.lang,
+    });
+
+    // Route to orchestrator for LLM-driven response
+    if (this.orchestrator) {
+      await this.orchestrator.handleCallerUtterance(msg.voicePrompt);
+    } else {
+      // Fallback if orchestrator not yet initialized
+      this.sendTextToken('I\'m still setting up. Please hold.', true);
+    }
+  }
+
+  private handleInterrupt(msg: RelayInterruptMessage): void {
+    log.info(
+      { callSessionId: this.callSessionId, utteranceUntilInterrupt: msg.utteranceUntilInterrupt },
+      'Caller interrupted assistant',
+    );
+
+    // Abort any in-flight processing
+    this.abortController.abort();
+    this.abortController = new AbortController();
+
+    // Notify the orchestrator of the interruption
+    if (this.orchestrator) {
+      this.orchestrator.handleInterrupt();
+    }
+  }
+
+  private handleDtmf(msg: RelayDtmfMessage): void {
+    log.info(
+      { callSessionId: this.callSessionId, digit: msg.digit },
+      'DTMF digit received',
+    );
+
+    recordCallEvent(this.callSessionId, 'caller_spoke', {
+      dtmfDigit: msg.digit,
+    });
+  }
+
+  private handleError(msg: RelayErrorMessage): void {
+    log.error(
+      { callSessionId: this.callSessionId, description: msg.description },
+      'ConversationRelay error',
+    );
+
+    recordCallEvent(this.callSessionId, 'call_failed', {
+      error: msg.description,
+    });
+  }
+}

package/src/calls/twilio-config.ts

@@ -0,0 +1,34 @@
+import { getSecureKey } from '../security/secure-keys.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('twilio-config');
+
+export interface TwilioConfig {
+  accountSid: string;
+  authToken: string;
+  phoneNumber: string;
+  webhookBaseUrl: string;
+  wssBaseUrl: string;
+}
+
+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 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.');
+  }
+  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');
+
+  return { accountSid, authToken, phoneNumber, webhookBaseUrl, wssBaseUrl };
+}

package/src/calls/twilio-provider.ts

@@ -0,0 +1,169 @@
+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 ──────────────────────────────────
+
+  /**
+   * 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,
+  ): 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) {
+      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);
+  }
+}