vellum 0.2.1 → 0.2.2

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-provider.ts

@@ -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('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/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';