vellum 0.2.1 → 0.2.2

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 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 baseUrl = config.webhookBaseUrl.replace(/\/$/, '');
+    const { callSid } = await provider.initiateCall({
+      from: config.phoneNumber,
+      to: phoneNumber,
+      webhookUrl: `${baseUrl}/webhooks/twilio/voice?callSessionId=${session.id}`,
+      statusCallbackUrl: `${baseUrl}/webhooks/twilio/status`,
+    });
+
+    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 };
+}

package/src/calls/call-orchestrator.ts

@@ -16,9 +16,10 @@ import {
   createPendingQuestion,
   expirePendingQuestions,
 } from './call-store.js';
-import { MAX_CALL_DURATION_MS, USER_CONSULTATION_TIMEOUT_MS, SILENCE_TIMEOUT_MS } from './call-constants.js';
+import { getMaxCallDurationMs, getUserConsultationTimeoutMs, SILENCE_TIMEOUT_MS } from './call-constants.js';
 import type { RelayConnection } from './relay-server.js';
 import { registerCallOrchestrator, unregisterCallOrchestrator, fireCallQuestionNotifier, fireCallCompletionNotifier } from './call-state.js';
+import type { PromptSpeakerContext } from './speaker-identification.js';
 
 const log = getLogger('call-orchestrator');
 
@@ -60,7 +61,7 @@ export class CallOrchestrator {
   /**
    * Handle a final caller utterance from the ConversationRelay.
    */
-  async handleCallerUtterance(transcript: string): Promise<void> {
+  async handleCallerUtterance(transcript: string, speaker?: PromptSpeakerContext): Promise<void> {
     // If we're already processing or speaking, abort the in-flight generation
     if (this.state === 'processing' || this.state === 'speaking') {
       this.abortController.abort();
@@ -71,7 +72,10 @@ export class CallOrchestrator {
     this.resetSilenceTimer();
 
     // Append caller utterance
-    this.conversationHistory.push({ role: 'user', content: transcript });
+    this.conversationHistory.push({
+      role: 'user',
+      content: this.formatCallerUtterance(transcript, speaker),
+    });
 
     await this.runLlm();
   }
@@ -100,7 +104,11 @@ export class CallOrchestrator {
     // Append the user's answer as a special message the model recognizes
     this.conversationHistory.push({ role: 'user', content: `[USER_ANSWERED: ${answerText}]` });
 
-    await this.runLlm();
+    // Fire-and-forget: unblock the caller so the HTTP response and answer
+    // persistence happen immediately, before LLM streaming begins.
+    this.runLlm().catch((err) =>
+      log.error({ err, callSessionId: this.callSessionId }, 'runLlm failed after user answer'),
+    );
     return true;
   }
 
@@ -130,6 +138,11 @@ export class CallOrchestrator {
   // ── Private ──────────────────────────────────────────────────────
 
   private buildSystemPrompt(): string {
+    const config = getConfig();
+    const disclosureRule = config.calls.disclosure.enabled
+      ? `1. ${config.calls.disclosure.text}`
+      : '1. Begin the conversation naturally.';
+
     return [
       'You are on a live phone call on behalf of your user.',
       this.task ? `Task: ${this.task}` : '',
@@ -138,18 +151,27 @@ export class CallOrchestrator {
       'Respond naturally and conversationally — speak as you would in a real phone conversation.',
       '',
       'IMPORTANT RULES:',
-      '1. At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+      disclosureRule,
       '2. Be concise — phone conversations should be brief and natural.',
       '3. If the callee asks something you don\'t know, include [ASK_USER: your question here] in your response along with a hold message like "Let me check on that for you."',
       '4. If the callee provides information preceded by [USER_ANSWERED: ...], use that answer naturally in the conversation.',
       '5. When the call\'s purpose is fulfilled, include [END_CALL] in your response along with a polite goodbye.',
       '6. Do not make up information — ask the user if unsure.',
       '7. Keep responses short — 1-3 sentences is ideal for phone conversation.',
+      '8. When caller text includes [SPEAKER id="..." label="..."], treat each speaker as a distinct person and personalize responses using that speaker\'s prior context in this call.',
     ]
       .filter(Boolean)
       .join('\n');
   }
 
+  private formatCallerUtterance(transcript: string, speaker?: PromptSpeakerContext): string {
+    if (!speaker) return transcript;
+    const safeId = speaker.speakerId.replaceAll('"', '\'');
+    const safeLabel = speaker.speakerLabel.replaceAll('"', '\'');
+    const confidencePart = speaker.speakerConfidence !== null ? ` confidence="${speaker.speakerConfidence.toFixed(2)}"` : '';
+    return `[SPEAKER id="${safeId}" label="${safeLabel}" source="${speaker.source}"${confidencePart}] ${transcript}`;
+  }
+
   /**
    * Run the LLM with the current conversation history and stream
    * the response back through the relay.
@@ -215,7 +237,8 @@ export class CallOrchestrator {
             '[ASK_USER:'.startsWith(afterBracket) ||
             '[END_CALL]'.startsWith(afterBracket) ||
             afterBracket.startsWith('[ASK_USER:') ||
-            afterBracket.startsWith('[END_CALL');
+            afterBracket === '[END_CALL' ||
+            afterBracket.startsWith('[END_CALL]');
 
           if (!couldBeControl) {
             // Not a control marker prefix — flush up to the next '[' (if any)
@@ -295,7 +318,7 @@ export class CallOrchestrator {
             updateCallSession(this.callSessionId, { status: 'in_progress' });
             expirePendingQuestions(this.callSessionId);
           }
-        }, USER_CONSULTATION_TIMEOUT_MS);
+        }, getUserConsultationTimeoutMs());
         return;
       }
 
@@ -329,15 +352,18 @@ export class CallOrchestrator {
   }
 
   private startDurationTimer(): void {
-    const warningMs = MAX_CALL_DURATION_MS - 2 * 60 * 1000; // 2 minutes before max
-
-    this.durationWarningTimer = setTimeout(() => {
-      log.info({ callSessionId: this.callSessionId }, 'Call duration warning');
-      this.relay.sendTextToken(
-        'Just to let you know, we\'re running low on time for this call.',
-        true,
-      );
-    }, warningMs);
+    const maxDurationMs = getMaxCallDurationMs();
+    const warningMs = maxDurationMs - 2 * 60 * 1000; // 2 minutes before max
+
+    if (warningMs > 0) {
+      this.durationWarningTimer = setTimeout(() => {
+        log.info({ callSessionId: this.callSessionId }, 'Call duration warning');
+        this.relay.sendTextToken(
+          'Just to let you know, we\'re running low on time for this call.',
+          true,
+        );
+      }, warningMs);
+    }
 
     this.durationTimer = setTimeout(() => {
       log.info({ callSessionId: this.callSessionId }, 'Call duration limit reached');
@@ -351,7 +377,7 @@ export class CallOrchestrator {
         updateCallSession(this.callSessionId, { status: 'completed', endedAt: Date.now() });
         recordCallEvent(this.callSessionId, 'call_ended', { reason: 'max_duration' });
       }, 3000);
-    }, MAX_CALL_DURATION_MS);
+    }, maxDurationMs);
   }
 
   private resetSilenceTimer(): void {