vellum 0.2.0 → 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-state.ts

@@ -0,0 +1,64 @@
+/**
+ * Call session notifiers and orchestrator registry.
+ *
+ * Follows the same notifier pattern as watch-state.ts: module-level Maps
+ * with register/unregister/fire helpers keyed by conversationId.
+ */
+
+import { getLogger } from '../util/logger.js';
+import type { CallOrchestrator } from './call-orchestrator.js';
+
+const log = getLogger('call-state');
+
+// ── Question notifiers ──────────────────────────────────────────────
+const questionNotifiers = new Map<string, (callSessionId: string, question: string) => void>();
+
+export function registerCallQuestionNotifier(
+  conversationId: string,
+  callback: (callSessionId: string, question: string) => void,
+): void {
+  questionNotifiers.set(conversationId, callback);
+}
+
+export function unregisterCallQuestionNotifier(conversationId: string): void {
+  questionNotifiers.delete(conversationId);
+}
+
+export function fireCallQuestionNotifier(conversationId: string, callSessionId: string, question: string): void {
+  questionNotifiers.get(conversationId)?.(callSessionId, question);
+}
+
+// ── Completion notifiers ────────────────────────────────────────────
+const completionNotifiers = new Map<string, (callSessionId: string) => void>();
+
+export function registerCallCompletionNotifier(
+  conversationId: string,
+  callback: (callSessionId: string) => void,
+): void {
+  completionNotifiers.set(conversationId, callback);
+}
+
+export function unregisterCallCompletionNotifier(conversationId: string): void {
+  completionNotifiers.delete(conversationId);
+}
+
+export function fireCallCompletionNotifier(conversationId: string, callSessionId: string): void {
+  completionNotifiers.get(conversationId)?.(callSessionId);
+}
+
+// ── Active orchestrator registry ────────────────────────────────────
+const activeCallOrchestrators = new Map<string, CallOrchestrator>();
+
+export function registerCallOrchestrator(callSessionId: string, orchestrator: CallOrchestrator): void {
+  activeCallOrchestrators.set(callSessionId, orchestrator);
+  log.info({ callSessionId }, 'Call orchestrator registered');
+}
+
+export function unregisterCallOrchestrator(callSessionId: string): void {
+  activeCallOrchestrators.delete(callSessionId);
+  log.info({ callSessionId }, 'Call orchestrator unregistered');
+}
+
+export function getCallOrchestrator(callSessionId: string): CallOrchestrator | undefined {
+  return activeCallOrchestrators.get(callSessionId);
+}