vellum 0.2.1 → 0.2.7

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

@@ -0,0 +1,162 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Mocks — silence logger output during tests
+// ---------------------------------------------------------------------------
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of ['info', 'warn', 'error', 'debug', 'trace', 'fatal', 'silent', 'child']) {
+    stub[m] = m === 'child' ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module('../../util/logger.js', () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+import {
+  normalizeBaseUrl,
+  buildTwilioVoiceWebhookUrl,
+  buildTwilioStatusCallbackUrl,
+  getWebhookBaseUrl,
+} from '../twilio-webhook-urls.js';
+
+// ---------------------------------------------------------------------------
+// normalizeBaseUrl
+// ---------------------------------------------------------------------------
+
+describe('normalizeBaseUrl', () => {
+  test('returns already-clean URL unchanged', () => {
+    expect(normalizeBaseUrl('https://example.com')).toBe('https://example.com');
+  });
+
+  test('strips trailing slash', () => {
+    expect(normalizeBaseUrl('https://example.com/')).toBe('https://example.com');
+  });
+
+  test('strips multiple trailing slashes', () => {
+    expect(normalizeBaseUrl('https://example.com///')).toBe('https://example.com');
+  });
+
+  test('trims leading and trailing whitespace', () => {
+    expect(normalizeBaseUrl('  https://example.com  ')).toBe('https://example.com');
+  });
+
+  test('trims whitespace and strips trailing slash together', () => {
+    expect(normalizeBaseUrl('  https://example.com/  ')).toBe('https://example.com');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTwilioVoiceWebhookUrl
+// ---------------------------------------------------------------------------
+
+describe('buildTwilioVoiceWebhookUrl', () => {
+  test('returns correct URL with callSessionId', () => {
+    const url = buildTwilioVoiceWebhookUrl('https://example.com', 'session-123');
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=session-123');
+  });
+
+  test('normalizes base URL before composing', () => {
+    const url = buildTwilioVoiceWebhookUrl('https://example.com/', 'abc');
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=abc');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTwilioStatusCallbackUrl
+// ---------------------------------------------------------------------------
+
+describe('buildTwilioStatusCallbackUrl', () => {
+  test('returns correct URL', () => {
+    const url = buildTwilioStatusCallbackUrl('https://example.com');
+    expect(url).toBe('https://example.com/webhooks/twilio/status');
+  });
+
+  test('normalizes base URL before composing', () => {
+    const url = buildTwilioStatusCallbackUrl('https://example.com/');
+    expect(url).toBe('https://example.com/webhooks/twilio/status');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getWebhookBaseUrl
+// ---------------------------------------------------------------------------
+
+describe('getWebhookBaseUrl', () => {
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedEnv = process.env.TWILIO_WEBHOOK_BASE_URL;
+    delete process.env.TWILIO_WEBHOOK_BASE_URL;
+  });
+
+  afterEach(() => {
+    if (savedEnv !== undefined) {
+      process.env.TWILIO_WEBHOOK_BASE_URL = savedEnv;
+    } else {
+      delete process.env.TWILIO_WEBHOOK_BASE_URL;
+    }
+  });
+
+  test('uses config value when set', () => {
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: 'https://config.example.com/' } });
+    expect(result).toBe('https://config.example.com');
+  });
+
+  test('falls back to env var when config value is empty', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com/';
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '' } });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('falls back to env var when config value is undefined', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getWebhookBaseUrl({ calls: {} });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('throws when neither config nor env var is set', () => {
+    expect(() => getWebhookBaseUrl({ calls: { webhookBaseUrl: '' } })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+
+  test('throws when config is undefined and env var is unset', () => {
+    expect(() => getWebhookBaseUrl({ calls: {} })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+
+  test('normalizes the returned URL', () => {
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '  https://example.com/  ' } });
+    expect(result).toBe('https://example.com');
+  });
+
+  test('falls through when config value is whitespace-only', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '   ' } });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('falls through when config value is slash-only', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '///' } });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('throws when config is whitespace-only and env var is unset', () => {
+    expect(() => getWebhookBaseUrl({ calls: { webhookBaseUrl: '   ' } })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+
+  test('throws when env var is whitespace-only and config is empty', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = '   ';
+    expect(() => getWebhookBaseUrl({ calls: {} })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+});

package/src/calls/call-bridge.ts

@@ -0,0 +1,95 @@
+/**
+ * Call-answer bridge: auto-consumes user replies in-thread as answers
+ * to pending call questions, routing them to the live call orchestrator.
+ *
+ * When a call has a pending question and the user sends a normal message
+ * in the conversation thread, this bridge intercepts the message before
+ * the agent loop, forwards the answer to the orchestrator, and returns
+ * `{ handled: true }` so the caller can skip agent processing.
+ */
+
+import { getLogger } from '../util/logger.js';
+import {
+  getActiveCallSessionForConversation,
+  getPendingQuestion,
+  answerPendingQuestion,
+  recordCallEvent,
+  getCallSession,
+} from './call-store.js';
+import { getCallOrchestrator } from './call-state.js';
+import * as conversationStore from '../memory/conversation-store.js';
+
+const log = getLogger('call-bridge');
+
+export interface CallBridgeResult {
+  handled: boolean;
+  reason?: string;
+}
+
+/**
+ * Attempt to route a user message as an answer to a pending call question.
+ *
+ * @param conversationId - The conversation the message belongs to.
+ * @param userText - The user's message text.
+ * @param _userMessageId - The persisted message ID (reserved for future use).
+ * @returns `{ handled: true }` if the answer was consumed by the call system,
+ *          `{ handled: false, reason }` otherwise.
+ */
+export async function tryHandlePendingCallAnswer(
+  conversationId: string,
+  userText: string,
+  _userMessageId?: string,
+): Promise<CallBridgeResult> {
+  // 1. Find an active call for this conversation
+  const callSession = getActiveCallSessionForConversation(conversationId);
+  if (!callSession) {
+    return { handled: false, reason: 'no_active_call' };
+  }
+
+  // 2. Check for a pending question
+  const pendingQuestion = getPendingQuestion(callSession.id);
+  if (!pendingQuestion) {
+    return { handled: false, reason: 'no_pending_question' };
+  }
+
+  // 3. Check that the orchestrator is alive and waiting
+  const orchestrator = getCallOrchestrator(callSession.id);
+  if (!orchestrator) {
+    // The call may have ended between the question being asked and the
+    // user replying. Persist a follow-up message so the user knows.
+    const freshSession = getCallSession(callSession.id);
+    const ended = freshSession && (freshSession.status === 'completed' || freshSession.status === 'failed');
+    if (ended) {
+      conversationStore.addMessage(
+        conversationId,
+        'assistant',
+        JSON.stringify([{
+          type: 'text',
+          text: 'The call ended before your answer could be relayed to the caller.',
+        }]),
+      );
+    }
+    return { handled: false, reason: 'orchestrator_not_found' };
+  }
+
+  if (orchestrator.getState() !== 'waiting_on_user') {
+    return { handled: false, reason: 'orchestrator_not_waiting' };
+  }
+
+  // 4. Route the answer through the orchestrator
+  const accepted = await orchestrator.handleUserAnswer(userText);
+  if (!accepted) {
+    return { handled: false, reason: 'orchestrator_rejected' };
+  }
+
+  // 5. Persist the answered state
+  answerPendingQuestion(pendingQuestion.id, userText);
+  recordCallEvent(callSession.id, 'user_answered', { answer: userText });
+
+  log.info(
+    { conversationId, callSessionId: callSession.id, questionId: pendingQuestion.id },
+    'User reply routed as call answer via bridge',
+  );
+
+  return { handled: true };
+}

package/src/calls/call-constants.ts

@@ -1,10 +1,48 @@
+import { getConfig } from '../config/loader.js';
+
 // Emergency/high-risk numbers that should never be called
 export const DENIED_NUMBERS = new Set([
-  '911', '112', '999', '000', '110', '119',  // Emergency
-  '+1911', '+1112',
+  '911', '112', '999', '000', '110', '119',
 ]);
 
-// Call limits
-export const MAX_CALL_DURATION_MS = 12 * 60 * 1000; // 12 minutes
-export const USER_CONSULTATION_TIMEOUT_MS = 90 * 1000; // 90 seconds
+/**
+ * Check whether a phone number is a denied emergency number.
+ *
+ * Normalizes E.164 variants by stripping the leading '+' and then checking
+ * whether the resulting digit string exactly matches a denied number or could
+ * be a country-code-prefixed emergency number (e.g. +1911, +44999, +61000).
+ * Country codes are 1–3 digits, so we try every valid split.
+ */
+export function isDeniedNumber(phoneNumber: string): boolean {
+  // Strip leading '+' to get a digits-only string
+  const digits = phoneNumber.startsWith('+') ? phoneNumber.slice(1) : phoneNumber;
+
+  // Exact match (covers bare short codes like "911", "112")
+  if (DENIED_NUMBERS.has(digits)) return true;
+
+  // Try splitting off 1-, 2-, or 3-digit country codes and check if the
+  // remainder is a denied number. This catches patterns like +1911, +44999.
+  for (let ccLen = 1; ccLen <= 3; ccLen++) {
+    if (digits.length > ccLen) {
+      const remainder = digits.slice(ccLen);
+      if (DENIED_NUMBERS.has(remainder)) return true;
+    }
+  }
+
+  return false;
+}
+
+// Call limits — backed by config with hardcoded fallbacks
+export function getMaxCallDurationMs(): number {
+  return getConfig().calls.maxDurationSeconds * 1000;
+}
+
+export function getUserConsultationTimeoutMs(): number {
+  return getConfig().calls.userConsultTimeoutSeconds * 1000;
+}
+
 export const SILENCE_TIMEOUT_MS = 30 * 1000; // 30 seconds
+
+// Legacy named exports for backward compatibility (use functions above for config-backed values)
+export const MAX_CALL_DURATION_MS = 3600 * 1000; // fallback default; prefer getMaxCallDurationMs()
+export const USER_CONSULTATION_TIMEOUT_MS = 120 * 1000; // fallback default; prefer getUserConsultationTimeoutMs()

package/src/calls/call-domain.ts

@@ -0,0 +1,276 @@
+/**
+ * Shared domain functions for call operations.
+ *
+ * Both the tool implementations and the HTTP route handlers delegate
+ * to these functions so business logic lives in one place.
+ */
+
+import { getLogger } from '../util/logger.js';
+import { isDeniedNumber } from './call-constants.js';
+import {
+  createCallSession,
+  getCallSession,
+  getActiveCallSessionForConversation,
+  updateCallSession,
+  getPendingQuestion,
+  answerPendingQuestion,
+  expirePendingQuestions,
+} from './call-store.js';
+import { getCallOrchestrator, unregisterCallOrchestrator } from './call-state.js';
+import { activeRelayConnections } from './relay-server.js';
+import { TwilioConversationRelayProvider } from './twilio-provider.js';
+import { getTwilioConfig } from './twilio-config.js';
+import { buildTwilioVoiceWebhookUrl, buildTwilioStatusCallbackUrl } from './twilio-webhook-urls.js';
+import type { CallSession } from './types.js';
+
+const log = getLogger('call-domain');
+
+const E164_REGEX = /^\+\d+$/;
+
+// ── Result types ─────────────────────────────────────────────────────
+
+export interface StartCallResult {
+  ok: true;
+  session: CallSession;
+  callSid: string;
+}
+
+export interface CallError {
+  ok: false;
+  error: string;
+  status?: number;
+}
+
+export type StartCallInput = {
+  phoneNumber: string;
+  task: string;
+  context?: string;
+  conversationId: string;
+};
+
+export type CancelCallInput = {
+  callSessionId: string;
+  reason?: string;
+};
+
+export type AnswerCallInput = {
+  callSessionId: string;
+  answer: string;
+};
+
+// ── Domain operations ────────────────────────────────────────────────
+
+/**
+ * Initiate a new outbound call.
+ */
+export async function startCall(input: StartCallInput): Promise<StartCallResult | CallError> {
+  const { phoneNumber, task, context: callContext, conversationId } = input;
+
+  if (!phoneNumber || typeof phoneNumber !== 'string') {
+    return { ok: false, error: 'phone_number is required and must be a string', status: 400 };
+  }
+
+  if (!E164_REGEX.test(phoneNumber)) {
+    return {
+      ok: false,
+      error: 'phone_number must be in E.164 format (starts with + followed by digits, e.g. +14155551234)',
+      status: 400,
+    };
+  }
+
+  if (!task || typeof task !== 'string' || task.trim().length === 0) {
+    return { ok: false, error: 'task is required and must be a non-empty string', status: 400 };
+  }
+
+  if (isDeniedNumber(phoneNumber)) {
+    return { ok: false, error: 'This phone number is not allowed to be called', status: 403 };
+  }
+
+  let sessionId: string | null = null;
+
+  try {
+    const config = getTwilioConfig();
+    const provider = new TwilioConversationRelayProvider();
+
+    const session = createCallSession({
+      conversationId,
+      provider: 'twilio',
+      fromNumber: config.phoneNumber,
+      toNumber: phoneNumber,
+      task: callContext ? `${task}\n\nContext: ${callContext}` : task,
+    });
+    sessionId = session.id;
+
+    log.info({ callSessionId: session.id, to: phoneNumber, task }, 'Initiating outbound call');
+
+    const { callSid } = await provider.initiateCall({
+      from: config.phoneNumber,
+      to: phoneNumber,
+      webhookUrl: buildTwilioVoiceWebhookUrl(config.webhookBaseUrl, session.id),
+      statusCallbackUrl: buildTwilioStatusCallbackUrl(config.webhookBaseUrl),
+    });
+
+    updateCallSession(session.id, { providerCallSid: callSid });
+
+    log.info({ callSessionId: session.id, callSid }, 'Call initiated successfully');
+
+    return {
+      ok: true,
+      session: { ...session, providerCallSid: callSid },
+      callSid,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ err, phoneNumber }, 'Failed to initiate call');
+
+    // FK constraint failure on conversation_id means the conversationId is invalid
+    if (err instanceof Error && msg.includes('FOREIGN KEY constraint failed') && !sessionId) {
+      return { ok: false, error: `Invalid conversationId: no conversation found with ID ${conversationId}`, status: 400 };
+    }
+
+    if (sessionId) {
+      updateCallSession(sessionId, {
+        status: 'failed',
+        endedAt: Date.now(),
+        lastError: msg,
+      });
+    }
+
+    return { ok: false, error: `Error initiating call: ${msg}`, status: 500 };
+  }
+}
+
+/**
+ * Get the status of a call session. If no callSessionId is provided,
+ * looks up the active call for the given conversationId.
+ */
+export function getCallStatus(
+  callSessionId?: string,
+  conversationId?: string,
+): { ok: true; session: CallSession; pendingQuestion?: { id: string; questionText: string } } | CallError {
+  let session: CallSession | null = null;
+
+  if (callSessionId) {
+    session = getCallSession(callSessionId);
+    if (!session) {
+      return { ok: false, error: `No call session found with ID ${callSessionId}`, status: 404 };
+    }
+  } else if (conversationId) {
+    session = getActiveCallSessionForConversation(conversationId);
+    if (!session) {
+      return { ok: false, error: 'No active call found in the current conversation', status: 404 };
+    }
+  } else {
+    return { ok: false, error: 'Either callSessionId or conversationId is required', status: 400 };
+  }
+
+  log.info({ callSessionId: session.id, status: session.status }, 'Checking call status');
+
+  const pendingQuestion = getPendingQuestion(session.id);
+  return {
+    ok: true,
+    session,
+    pendingQuestion: pendingQuestion
+      ? { id: pendingQuestion.id, questionText: pendingQuestion.questionText }
+      : undefined,
+  };
+}
+
+/**
+ * Cancel an active call. Cleans up relay connections and orchestrators.
+ */
+export async function cancelCall(input: CancelCallInput): Promise<{ ok: true; session: CallSession } | CallError> {
+  const { callSessionId, reason } = input;
+
+  const session = getCallSession(callSessionId);
+  if (!session) {
+    return { ok: false, error: `No call session found with ID ${callSessionId}`, status: 404 };
+  }
+
+  if (session.status === 'completed' || session.status === 'failed' || session.status === 'cancelled') {
+    return { ok: false, error: `Call session ${callSessionId} has already ended with status: ${session.status}`, status: 409 };
+  }
+
+  log.info({ callSessionId, reason }, 'Cancelling call');
+
+  // Terminate the call via the provider API
+  if (session.providerCallSid) {
+    try {
+      const provider = new TwilioConversationRelayProvider();
+      await provider.endCall(session.providerCallSid);
+    } catch (endErr) {
+      log.warn({ err: endErr, callSessionId, callSid: session.providerCallSid }, 'Failed to terminate call via provider API — proceeding with cleanup');
+    }
+  }
+
+  // End the relay connection if active
+  const relayConnection = activeRelayConnections.get(callSessionId);
+  if (relayConnection) {
+    relayConnection.endSession(reason);
+    relayConnection.destroy();
+    activeRelayConnections.delete(callSessionId);
+  }
+
+  // Clean up orchestrator
+  const orchestrator = getCallOrchestrator(callSessionId);
+  if (orchestrator) {
+    orchestrator.destroy();
+    unregisterCallOrchestrator(callSessionId);
+  }
+
+  // Update session status
+  updateCallSession(callSessionId, {
+    status: 'cancelled',
+    endedAt: Date.now(),
+  });
+
+  // Expire any pending questions so they don't linger
+  expirePendingQuestions(callSessionId);
+
+  // Re-check final status: a concurrent transition (e.g. Twilio callback) may have
+  // moved the session to a terminal state before our update, causing it to be skipped.
+  const updated = getCallSession(callSessionId);
+  if (updated && updated.status !== 'cancelled') {
+    log.warn({ callSessionId, finalStatus: updated.status }, 'Cancel lost race — session already transitioned to terminal state');
+    return { ok: false, error: `Call session ${callSessionId} transitioned to ${updated.status} before cancellation could be applied`, status: 409 };
+  }
+
+  log.info({ callSessionId }, 'Call cancelled successfully');
+
+  return { ok: true, session: updated ?? { ...session, status: 'cancelled', endedAt: Date.now() } };
+}
+
+/**
+ * Answer a pending question for an active call.
+ */
+export async function answerCall(input: AnswerCallInput): Promise<{ ok: true; questionId: string } | CallError> {
+  const { callSessionId, answer } = input;
+
+  if (!answer || typeof answer !== 'string') {
+    return { ok: false, error: 'Missing answer', status: 400 };
+  }
+
+  const question = getPendingQuestion(callSessionId);
+  if (!question) {
+    return { ok: false, error: 'No pending question found', status: 404 };
+  }
+
+  const orchestrator = getCallOrchestrator(callSessionId);
+  if (!orchestrator) {
+    log.warn({ callSessionId }, 'answerCall: no active orchestrator for call session');
+    return { ok: false, error: 'No active orchestrator for this call', status: 409 };
+  }
+
+  const accepted = await orchestrator.handleUserAnswer(answer);
+  if (!accepted) {
+    log.warn(
+      { callSessionId },
+      'answerCall: orchestrator rejected the answer (not in waiting_on_user state)',
+    );
+    return { ok: false, error: 'Orchestrator is not waiting for an answer', status: 409 };
+  }
+
+  answerPendingQuestion(question.id, answer);
+
+  return { ok: true, questionId: question.id };
+}