vellum 0.2.1 → 0.2.2

package/src/calls/call-recovery.ts

@@ -0,0 +1,207 @@
+/**
+ * Call recovery — reconciles in-flight calls on daemon restart.
+ *
+ * When the daemon restarts, any calls left in non-terminal states may be stale
+ * (the daemon crashed mid-call) or still active on the provider side. This
+ * module fetches the actual provider status and transitions each call
+ * accordingly.
+ */
+
+import { getLogger } from '../util/logger.js';
+import { listRecoverableCalls, updateCallSession, expirePendingQuestions } from './call-store.js';
+import type { VoiceProvider } from './voice-provider.js';
+import type { CallStatus } from './types.js';
+
+type Logger = ReturnType<typeof getLogger>;
+
+const defaultLog = getLogger('call-recovery');
+
+/**
+ * Grace period (in ms) for no-SID sessions during startup recovery.
+ *
+ * A daemon crash can leave a live Twilio call without a persisted SID
+ * (crash after `initiateCall` succeeds but before the SID is written).
+ * Webhooks carrying the SID may still arrive after restart.
+ *
+ * Sessions younger than this threshold are annotated but left in their
+ * current non-terminal state so incoming webhooks can still deliver the
+ * SID and resume the call normally.
+ *
+ * Sessions older than this threshold are transitioned to `failed` to
+ * prevent orphan sessions from creating false "active call" state
+ * indefinitely. 5 minutes is long enough for any legitimate webhook
+ * to arrive; after that the session is considered abandoned.
+ */
+export const NO_SID_GRACE_PERIOD_MS = 5 * 60_000;
+
+/**
+ * Map a Twilio provider status string to our internal CallStatus.
+ * Returns the mapped status or null if the status is unrecognised.
+ */
+function mapProviderStatus(providerStatus: string): CallStatus | null {
+  switch (providerStatus) {
+    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;
+  }
+}
+
+/**
+ * Check whether a CallStatus is terminal (no further transitions allowed).
+ */
+function isTerminal(status: CallStatus): boolean {
+  return status === 'completed' || status === 'failed' || status === 'cancelled';
+}
+
+/**
+ * Reconcile all non-terminal call sessions at daemon startup.
+ *
+ * For each recoverable call:
+ * - If it has a provider SID, fetch the current status from the provider
+ *   and transition the call to match.
+ * - If no provider SID exists and the session is older than the grace
+ *   period, transition it to `failed` to prevent orphan sessions from
+ *   creating false "active call" state indefinitely.
+ * - If no provider SID exists but the session is within the grace period,
+ *   leave it non-terminal so webhooks can still deliver the SID.
+ * - If the call transitions to a terminal state, expire any pending questions.
+ */
+export async function reconcileCallsOnStartup(
+  provider: VoiceProvider,
+  log: Logger = defaultLog,
+): Promise<void> {
+  const recoverableCalls = listRecoverableCalls();
+
+  if (recoverableCalls.length === 0) {
+    log.info('No recoverable calls found at startup');
+    return;
+  }
+
+  log.info({ count: recoverableCalls.length }, 'Reconciling non-terminal calls at startup');
+
+  for (const session of recoverableCalls) {
+    try {
+      if (!session.providerCallSid) {
+        const sessionAgeMs = Date.now() - session.createdAt;
+        const isStale = sessionAgeMs >= NO_SID_GRACE_PERIOD_MS;
+
+        if (isStale) {
+          // Session is old enough that any legitimate webhook should
+          // have arrived by now.  Transition to `failed` so it no
+          // longer appears as an active call.
+          log.info(
+            { callSessionId: session.id, previousStatus: session.status, sessionAgeMs },
+            'No-SID session past grace period — failing orphan session',
+          );
+          updateCallSession(session.id, {
+            status: 'failed',
+            endedAt: Date.now(),
+            lastError: 'Daemon restarted before provider SID persisted; grace period expired — orphan session failed',
+          });
+          expirePendingQuestions(session.id);
+        } else {
+          // Recent session — webhooks carrying the SID may still arrive.
+          // Leave in its current non-terminal state.
+          log.info(
+            { callSessionId: session.id, previousStatus: session.status, sessionAgeMs },
+            'Skipping recent no-SID session (within grace period, webhooks may still arrive)',
+          );
+          updateCallSession(session.id, {
+            lastError: 'Daemon restarted before provider SID persisted; awaiting webhook',
+          });
+        }
+        continue;
+      }
+
+      // Fetch actual status from provider
+      let providerStatus: string;
+      try {
+        providerStatus = await provider.getCallStatus(session.providerCallSid);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.warn(
+          { callSessionId: session.id, callSid: session.providerCallSid, err },
+          'Failed to fetch provider status during recovery — failing call',
+        );
+        updateCallSession(session.id, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: `Recovery: failed to fetch provider status: ${msg}`,
+        });
+        expirePendingQuestions(session.id);
+        continue;
+      }
+
+      const mappedStatus = mapProviderStatus(providerStatus);
+
+      if (!mappedStatus) {
+        log.warn(
+          { callSessionId: session.id, providerStatus },
+          'Unrecognised provider status during recovery — failing call',
+        );
+        updateCallSession(session.id, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: `Recovery: unrecognised provider status '${providerStatus}'`,
+        });
+        expirePendingQuestions(session.id);
+        continue;
+      }
+
+      if (isTerminal(mappedStatus)) {
+        // Provider says the call has ended
+        log.info(
+          { callSessionId: session.id, providerStatus, mappedStatus },
+          'Provider reports call ended — transitioning to terminal state',
+        );
+        updateCallSession(session.id, {
+          status: mappedStatus,
+          endedAt: Date.now(),
+        });
+        expirePendingQuestions(session.id);
+      } else {
+        // Provider says call is still active — leave it for webhooks to handle
+        log.info(
+          { callSessionId: session.id, providerStatus, mappedStatus },
+          'Provider reports call still active — leaving for webhook handling',
+        );
+      }
+    } catch (err) {
+      log.error(
+        { callSessionId: session.id, err },
+        'Unexpected error during call recovery',
+      );
+    }
+  }
+
+  log.info('Call recovery reconciliation complete');
+}
+
+/**
+ * Log a dead-letter provider event — a provider callback payload that
+ * could not be processed (malformed, unknown format, etc.).
+ *
+ * Rather than silently dropping these events, we log the full payload
+ * so operators can investigate later.
+ */
+export function logDeadLetterEvent(
+  reason: string,
+  payload: unknown,
+  log: Logger = defaultLog,
+): void {
+  log.error(
+    { reason, payload },
+    'Dead-letter provider event: callback could not be processed',
+  );
+}

package/src/calls/call-state-machine.ts

@@ -0,0 +1,68 @@
+/**
+ * Call state machine — defines allowed status transitions and validates
+ * all state changes in a single place.
+ *
+ * Terminal states (completed, failed, cancelled) are immutable: no further
+ * transitions are permitted once a call reaches one of these states.
+ */
+
+import type { CallStatus } from './types.js';
+
+// ── Transition table ─────────────────────────────────────────────────
+
+/**
+ * Maps each call status to the set of statuses it may transition to.
+ * Terminal states map to an empty set.
+ */
+const ALLOWED_TRANSITIONS: Record<CallStatus, Set<CallStatus>> = {
+  initiated: new Set<CallStatus>(['ringing', 'in_progress', 'waiting_on_user', 'completed', 'failed', 'cancelled']),
+  ringing: new Set<CallStatus>(['in_progress', 'waiting_on_user', 'completed', 'failed', 'cancelled']),
+  in_progress: new Set<CallStatus>(['waiting_on_user', 'completed', 'failed', 'cancelled']),
+  waiting_on_user: new Set<CallStatus>(['in_progress', 'completed', 'failed', 'cancelled']),
+  // Terminal states — no further transitions allowed
+  completed: new Set<CallStatus>(),
+  failed: new Set<CallStatus>(),
+  cancelled: new Set<CallStatus>(),
+};
+
+const TERMINAL_STATES: Set<CallStatus> = new Set(['completed', 'failed', 'cancelled']);
+
+// ── Public API ───────────────────────────────────────────────────────
+
+export interface TransitionResult {
+  valid: boolean;
+  reason?: string;
+}
+
+/**
+ * Check whether a transition from `current` to `next` is allowed.
+ */
+export function validateTransition(current: CallStatus, next: CallStatus): TransitionResult {
+  if (current === next) {
+    return { valid: true };
+  }
+
+  if (isTerminalState(current)) {
+    return {
+      valid: false,
+      reason: `Cannot transition from terminal state '${current}'`,
+    };
+  }
+
+  const allowed = ALLOWED_TRANSITIONS[current];
+  if (!allowed || !allowed.has(next)) {
+    return {
+      valid: false,
+      reason: `Invalid transition from '${current}' to '${next}'`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Returns true if the given status is a terminal (immutable) state.
+ */
+export function isTerminalState(status: CallStatus): boolean {
+  return TERMINAL_STATES.has(status);
+}

package/src/calls/call-store.ts

@@ -2,7 +2,8 @@ import { eq, and, notInArray, desc } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb } from '../memory/db.js';
 import { callSessions, callEvents, callPendingQuestions } from '../memory/schema.js';
-import type { CallSession, CallEvent, CallPendingQuestion, CallEventType } from './types.js';
+import type { CallSession, CallEvent, CallPendingQuestion, CallEventType, CallStatus } from './types.js';
+import { validateTransition } from './call-state-machine.js';
 import { getLogger } from '../util/logger.js';
 
 const log = getLogger('call-store');
@@ -105,7 +106,7 @@ export function getActiveCallSessionForConversation(conversationId: string): Cal
     .where(
       and(
         eq(callSessions.conversationId, conversationId),
-        notInArray(callSessions.status, ['completed', 'failed']),
+        notInArray(callSessions.status, ['completed', 'failed', 'cancelled']),
       ),
     )
     .orderBy(desc(callSessions.createdAt))
@@ -119,12 +120,44 @@ export function updateCallSession(
   updates: Partial<Pick<CallSession, 'status' | 'providerCallSid' | 'startedAt' | 'endedAt' | 'lastError'>>,
 ): void {
   const db = getDb();
+
+  // Validate status transition when a new status is provided
+  if (updates.status) {
+    const current = getCallSession(id);
+    if (current) {
+      const result = validateTransition(current.status, updates.status as CallStatus);
+      if (!result.valid) {
+        log.warn({ callSessionId: id, from: current.status, to: updates.status, reason: result.reason }, 'Invalid call status transition — skipping update');
+        return;
+      }
+    }
+  }
+
   db.update(callSessions)
     .set({ ...updates, updatedAt: Date.now() })
     .where(eq(callSessions.id, id))
     .run();
 }
 
+// ── Recovery queries ─────────────────────────────────────────────────
+
+/**
+ * Returns all call sessions that are in a non-terminal state
+ * (i.e. not completed, failed, or cancelled). Used during daemon startup
+ * to reconcile in-flight calls.
+ */
+export function listRecoverableCalls(): CallSession[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(callSessions)
+    .where(
+      notInArray(callSessions.status, ['completed', 'failed', 'cancelled']),
+    )
+    .all();
+  return rows.map(parseCallSession);
+}
+
 // ── Call Events ──────────────────────────────────────────────────────
 
 export function recordCallEvent(
@@ -207,10 +240,10 @@ export function answerPendingQuestion(id: string, answerText: string): void {
       ),
     )
     .run();
-  // Drizzle's .run() returns void for bun:sqlite, so verify via raw client.
+  // Drizzle's .run() returns void for bun:sqlite, so check affected rows via raw client.
   const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
-  const check = raw.query('SELECT status FROM call_pending_questions WHERE id = ?').get(id) as { status: string } | null;
-  if (!check || check.status !== 'answered') {
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  if (changes.c === 0) {
     log.warn({ questionId: id }, 'answerPendingQuestion: no rows updated — question may have already been answered or expired');
   }
 }
@@ -227,3 +260,157 @@ export function expirePendingQuestions(callSessionId: string): void {
     )
     .run();
 }
+
+// ── Callback Idempotency ─────────────────────────────────────────────
+
+/** Claims older than this are considered orphaned (crashed mid-processing) and can be reclaimed. */
+const CLAIM_EXPIRY_MS = 60_000; // 60 seconds
+
+/**
+ * Build a dedupe key for a Twilio status callback.
+ * Combines CallSid + CallStatus + Timestamp (or SequenceNumber if present)
+ * to uniquely identify each callback.
+ */
+export function buildCallbackDedupeKey(
+  callSid: string,
+  callStatus: string,
+  timestamp?: string | null,
+  sequenceNumber?: string | null,
+): string {
+  const discriminator = sequenceNumber ?? timestamp ?? '';
+  return `${callSid}:${callStatus}:${discriminator}`;
+}
+
+/**
+ * Check whether a callback dedupe key has already been processed (read-only).
+ * Returns true if the key already exists, false otherwise.
+ */
+export function isCallbackProcessed(dedupeKey: string): boolean {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  const row = raw.query(
+    `SELECT 1 FROM processed_callbacks WHERE dedupe_key = ?`,
+  ).get(dedupeKey);
+  return row != null;
+}
+
+/**
+ * Record a callback as processed. Should be called AFTER downstream writes
+ * (session updates, event recording) have succeeded so that Twilio retries
+ * are not silently dropped if those writes fail.
+ *
+ * Uses INSERT OR IGNORE so concurrent calls for the same key are safe.
+ */
+export function recordProcessedCallback(
+  dedupeKey: string,
+  callSessionId: string,
+): void {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  raw.query(
+    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, created_at) VALUES (?, ?, ?, ?)`,
+  ).run(uuid(), dedupeKey, callSessionId, Date.now());
+}
+
+/**
+ * Try to record a processed callback. Returns true if this is a new callback
+ * (inserted successfully). Returns false if the callback was already processed
+ * (dedupe key already exists), indicating a replay.
+ *
+ * Uses INSERT ... ON CONFLICT DO NOTHING pattern for atomicity.
+ *
+ * @deprecated Use claimCallback + releaseCallbackClaim instead to
+ * atomically claim a callback and release on failure.
+ */
+export function tryRecordProcessedCallback(
+  dedupeKey: string,
+  callSessionId: string,
+): boolean {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  raw.query(
+    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, created_at) VALUES (?, ?, ?, ?)`,
+  ).run(uuid(), dedupeKey, callSessionId, Date.now());
+
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  return changes.c > 0;
+}
+
+/**
+ * Atomically claim a callback for processing. Returns a unique claim ID
+ * (string) if this caller won the claim, or null if another caller already
+ * claimed it (dedupe_key conflict).
+ *
+ * Expired orphaned claims (older than CLAIM_EXPIRY_MS) are automatically
+ * cleared before attempting the insert, so crashes mid-processing don't
+ * permanently block retries.
+ *
+ * If processing fails, call `releaseCallbackClaim(dedupeKey, claimId)` to allow retries.
+ * On success, call `finalizeCallbackClaim(dedupeKey, claimId)` to make the claim permanent.
+ *
+ * The returned claim ID acts as an ownership token: release and finalize
+ * operations require it so that handler A cannot accidentally release or
+ * finalize a claim that was reclaimed by handler B after expiry.
+ */
+export function claimCallback(dedupeKey: string, callSessionId: string): string | null {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  // Clear any expired orphaned claims so they can be reprocessed
+  raw.query(
+    `DELETE FROM processed_callbacks WHERE dedupe_key = ? AND created_at < ?`,
+  ).run(dedupeKey, Date.now() - CLAIM_EXPIRY_MS);
+
+  const claimId = uuid();
+  raw.query(
+    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, claim_id, created_at) VALUES (?, ?, ?, ?, ?)`,
+  ).run(uuid(), dedupeKey, callSessionId, claimId, Date.now());
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  return changes.c > 0 ? claimId : null;
+}
+
+/**
+ * Release a callback claim so that retries can reprocess it.
+ * Called when processing fails after a successful claim.
+ *
+ * Only deletes the row if both dedupe_key AND claim_id match, preventing
+ * handler A from releasing a claim that was reclaimed by handler B.
+ */
+export function releaseCallbackClaim(dedupeKey: string, claimId: string): void {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+  raw.query(`DELETE FROM processed_callbacks WHERE dedupe_key = ? AND claim_id = ?`).run(dedupeKey, claimId);
+}
+
+/**
+ * Finalize a callback claim after successful processing.
+ * Sets the created_at to a far-future value so the claim never expires,
+ * distinguishing it from in-flight claims that may need to be reclaimed.
+ *
+ * Only updates the row if both dedupe_key AND claim_id match, preventing
+ * handler A from finalizing a claim that was reclaimed by handler B.
+ *
+ * Returns true if the claim was successfully finalized, or false if 0 rows
+ * were updated — meaning the claim was reclaimed by another handler after
+ * expiry. Callers should treat a false return as a lost-claim signal: the
+ * business writes already happened but the dedupe row belongs to someone
+ * else, so duplicate processing may occur on later retries.
+ */
+export function finalizeCallbackClaim(dedupeKey: string, claimId: string): boolean {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+  // Set created_at far in the future so expiry check never matches
+  const NEVER_EXPIRE = Date.now() + 100 * 365 * 24 * 60 * 60 * 1000; // ~100 years
+  raw.query(
+    `UPDATE processed_callbacks SET created_at = ? WHERE dedupe_key = ? AND claim_id = ?`,
+  ).run(NEVER_EXPIRE, dedupeKey, claimId);
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  if (changes.c === 0) {
+    log.warn({ dedupeKey, claimId }, 'finalizeCallbackClaim: claim was lost — another handler reclaimed this key after expiry');
+    return false;
+  }
+  return true;
+}

package/src/calls/relay-server.ts

@@ -14,6 +14,11 @@ import {
   recordCallEvent,
 } from './call-store.js';
 import { CallOrchestrator } from './call-orchestrator.js';
+import {
+  extractPromptSpeakerMetadata,
+  SpeakerIdentityTracker,
+  type PromptSpeakerContext,
+} from './speaker-identification.js';
 
 const log = getLogger('relay-server');
 
@@ -33,6 +38,23 @@ export interface RelayPromptMessage {
   voicePrompt: string;
   lang: string;
   last: boolean;
+  speakerId?: string;
+  speakerLabel?: string;
+  speakerName?: string;
+  speakerConfidence?: number;
+  participantId?: string;
+  participant?: {
+    id?: string;
+    name?: string;
+  };
+  speaker?: {
+    id?: string;
+    label?: string;
+    name?: string;
+    confidence?: number;
+  };
+  metadata?: Record<string, unknown>;
+  providerMetadata?: Record<string, unknown>;
 }
 
 export interface RelayInterruptMessage {
@@ -88,15 +110,22 @@ export const activeRelayConnections = new Map<string, RelayConnection>();
 export class RelayConnection {
   private ws: ServerWebSocket<RelayWebSocketData>;
   private callSessionId: string;
-  private conversationHistory: Array<{ role: 'caller' | 'assistant'; text: string; timestamp: number }>;
+  private conversationHistory: Array<{
+    role: 'caller' | 'assistant';
+    text: string;
+    timestamp: number;
+    speaker?: PromptSpeakerContext;
+  }>;
   private abortController: AbortController;
   private orchestrator: CallOrchestrator | null = null;
+  private speakerIdentityTracker: SpeakerIdentityTracker;
 
   constructor(ws: ServerWebSocket<RelayWebSocketData>, callSessionId: string) {
     this.ws = ws;
     this.callSessionId = callSessionId;
     this.conversationHistory = [];
     this.abortController = new AbortController();
+    this.speakerIdentityTracker = new SpeakerIdentityTracker();
   }
 
   /**
@@ -162,8 +191,8 @@ export class RelayConnection {
   /**
    * Get the conversation history for context.
    */
-  getConversationHistory(): Array<{ role: string; text: string }> {
-    return this.conversationHistory.map(({ role, text }) => ({ role, text }));
+  getConversationHistory(): Array<{ role: string; text: string; speaker?: PromptSpeakerContext }> {
+    return this.conversationHistory.map(({ role, text, speaker }) => ({ role, text, speaker }));
   }
 
   /**
@@ -236,22 +265,30 @@ export class RelayConnection {
       'Caller transcript received (final)',
     );
 
+    const speakerMetadata = extractPromptSpeakerMetadata(msg as unknown as Record<string, unknown>);
+    const speaker = this.speakerIdentityTracker.identifySpeaker(speakerMetadata);
+
     // Record in conversation history
     this.conversationHistory.push({
       role: 'caller',
       text: msg.voicePrompt,
       timestamp: Date.now(),
+      speaker,
     });
 
     // Record event
     recordCallEvent(this.callSessionId, 'caller_spoke', {
       transcript: msg.voicePrompt,
       lang: msg.lang,
+      speakerId: speaker.speakerId,
+      speakerLabel: speaker.speakerLabel,
+      speakerConfidence: speaker.speakerConfidence,
+      speakerSource: speaker.source,
     });
 
     // Route to orchestrator for LLM-driven response
     if (this.orchestrator) {
-      await this.orchestrator.handleCallerUtterance(msg.voicePrompt);
+      await this.orchestrator.handleCallerUtterance(msg.voicePrompt, speaker);
     } else {
       // Fallback if orchestrator not yet initialized
       this.sendTextToken('I\'m still setting up. Please hold.', true);