@vellumai/assistant 0.3.5 → 0.3.7

package/src/calls/call-store.ts

@@ -1,56 +1,53 @@
-import { eq, and, notInArray, desc } from 'drizzle-orm';
+import { eq, and, or, notInArray, desc } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
-import { getDb } from '../memory/db.js';
+import { getDb, rawChanges, rawGet, rawRun } from '../memory/db.js';
 import { callSessions, callEvents, callPendingQuestions } from '../memory/schema.js';
 import type { CallSession, CallEvent, CallPendingQuestion, CallEventType, CallStatus } from './types.js';
 import { validateTransition } from './call-state-machine.js';
 import { getLogger } from '../util/logger.js';
+import { createRowMapper, cast } from '../util/row-mapper.js';
 
 const log = getLogger('call-store');
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
-function parseCallSession(row: typeof callSessions.$inferSelect): CallSession {
-  return {
-    id: row.id,
-    conversationId: row.conversationId,
-    provider: row.provider,
-    providerCallSid: row.providerCallSid,
-    fromNumber: row.fromNumber,
-    toNumber: row.toNumber,
-    task: row.task,
-    status: row.status as CallSession['status'],
-    callerIdentityMode: row.callerIdentityMode,
-    callerIdentitySource: row.callerIdentitySource,
-    startedAt: row.startedAt,
-    endedAt: row.endedAt,
-    lastError: row.lastError,
-    createdAt: row.createdAt,
-    updatedAt: row.updatedAt,
-  };
-}
-
-function parseCallEvent(row: typeof callEvents.$inferSelect): CallEvent {
-  return {
-    id: row.id,
-    callSessionId: row.callSessionId,
-    eventType: row.eventType as CallEvent['eventType'],
-    payloadJson: row.payloadJson,
-    createdAt: row.createdAt,
-  };
-}
-
-function parsePendingQuestion(row: typeof callPendingQuestions.$inferSelect): CallPendingQuestion {
-  return {
-    id: row.id,
-    callSessionId: row.callSessionId,
-    questionText: row.questionText,
-    status: row.status as CallPendingQuestion['status'],
-    askedAt: row.askedAt,
-    answeredAt: row.answeredAt,
-    answerText: row.answerText,
-  };
-}
+const parseCallSession = createRowMapper<typeof callSessions.$inferSelect, CallSession>({
+  id: 'id',
+  conversationId: 'conversationId',
+  provider: 'provider',
+  providerCallSid: 'providerCallSid',
+  fromNumber: 'fromNumber',
+  toNumber: 'toNumber',
+  task: 'task',
+  status: { from: 'status', transform: cast<CallSession['status']>() },
+  callerIdentityMode: 'callerIdentityMode',
+  callerIdentitySource: 'callerIdentitySource',
+  assistantId: 'assistantId',
+  initiatedFromConversationId: 'initiatedFromConversationId',
+  startedAt: 'startedAt',
+  endedAt: 'endedAt',
+  lastError: 'lastError',
+  createdAt: 'createdAt',
+  updatedAt: 'updatedAt',
+});
+
+const parseCallEvent = createRowMapper<typeof callEvents.$inferSelect, CallEvent>({
+  id: 'id',
+  callSessionId: 'callSessionId',
+  eventType: { from: 'eventType', transform: cast<CallEvent['eventType']>() },
+  payloadJson: 'payloadJson',
+  createdAt: 'createdAt',
+});
+
+const parsePendingQuestion = createRowMapper<typeof callPendingQuestions.$inferSelect, CallPendingQuestion>({
+  id: 'id',
+  callSessionId: 'callSessionId',
+  questionText: 'questionText',
+  status: { from: 'status', transform: cast<CallPendingQuestion['status']>() },
+  askedAt: 'askedAt',
+  answeredAt: 'answeredAt',
+  answerText: 'answerText',
+});
 
 // ── Call Sessions ────────────────────────────────────────────────────
 
@@ -62,6 +59,8 @@ export function createCallSession(opts: {
   task?: string;
   callerIdentityMode?: string;
   callerIdentitySource?: string;
+  assistantId?: string;
+  initiatedFromConversationId?: string;
 }): CallSession {
   const db = getDb();
   const now = Date.now();
@@ -76,6 +75,8 @@ export function createCallSession(opts: {
     status: 'initiated' as const,
     callerIdentityMode: opts.callerIdentityMode ?? null,
     callerIdentitySource: opts.callerIdentitySource ?? null,
+    assistantId: opts.assistantId ?? null,
+    initiatedFromConversationId: opts.initiatedFromConversationId ?? null,
     startedAt: null,
     endedAt: null,
     lastError: null,
@@ -111,7 +112,10 @@ export function getActiveCallSessionForConversation(conversationId: string): Cal
     .from(callSessions)
     .where(
       and(
-        eq(callSessions.conversationId, conversationId),
+        or(
+          eq(callSessions.conversationId, conversationId),
+          eq(callSessions.initiatedFromConversationId, conversationId),
+        ),
         notInArray(callSessions.status, ['completed', 'failed', 'cancelled']),
       ),
     )
@@ -123,7 +127,7 @@ export function getActiveCallSessionForConversation(conversationId: string): Cal
 
 export function updateCallSession(
   id: string,
-  updates: Partial<Pick<CallSession, 'status' | 'providerCallSid' | 'startedAt' | 'endedAt' | 'lastError'>>,
+  updates: Partial<Pick<CallSession, 'status' | 'providerCallSid' | 'startedAt' | 'endedAt' | 'lastError' | 'conversationId' | 'initiatedFromConversationId'>>,
 ): void {
   const db = getDb();
 
@@ -246,10 +250,7 @@ export function answerPendingQuestion(id: string, answerText: string): void {
       ),
     )
     .run();
-  // 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 changes = raw.query('SELECT changes() as c').get() as { c: number };
-  if (changes.c === 0) {
+  if (rawChanges() === 0) {
     log.warn({ questionId: id }, 'answerPendingQuestion: no rows updated — question may have already been answered or expired');
   }
 }
@@ -292,13 +293,7 @@ export function buildCallbackDedupeKey(
  * 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;
+  return rawGet<{ 1: number }>(`SELECT 1 FROM processed_callbacks WHERE dedupe_key = ?`, dedupeKey) != null;
 }
 
 /**
@@ -312,12 +307,10 @@ 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(
+  rawRun(
     `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, created_at) VALUES (?, ?, ?, ?)`,
-  ).run(uuid(), dedupeKey, callSessionId, Date.now());
+    uuid(), dedupeKey, callSessionId, Date.now(),
+  );
 }
 
 /**
@@ -334,15 +327,10 @@ 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(
+  return rawRun(
     `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;
+    uuid(), dedupeKey, callSessionId, Date.now(),
+  ) > 0;
 }
 
 /**
@@ -362,20 +350,18 @@ export function tryRecordProcessedCallback(
  * 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(
+  rawRun(
     `DELETE FROM processed_callbacks WHERE dedupe_key = ? AND created_at < ?`,
-  ).run(dedupeKey, Date.now() - CLAIM_EXPIRY_MS);
+    dedupeKey, Date.now() - CLAIM_EXPIRY_MS,
+  );
 
   const claimId = uuid();
-  raw.query(
+  const changes = rawRun(
     `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;
+    uuid(), dedupeKey, callSessionId, claimId, Date.now(),
+  );
+  return changes > 0 ? claimId : null;
 }
 
 /**
@@ -386,9 +372,7 @@ export function claimCallback(dedupeKey: string, callSessionId: string): string
  * 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);
+  rawRun(`DELETE FROM processed_callbacks WHERE dedupe_key = ? AND claim_id = ?`, dedupeKey, claimId);
 }
 
 /**
@@ -406,15 +390,13 @@ export function releaseCallbackClaim(dedupeKey: string, claimId: string): void {
  * 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(
+  const changes = rawRun(
     `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) {
+    NEVER_EXPIRE, dedupeKey, claimId,
+  );
+  if (changes === 0) {
     log.warn({ dedupeKey, claimId }, 'finalizeCallbackClaim: claim was lost — another handler reclaimed this key after expiry');
     return false;
   }

package/src/calls/elevenlabs-config.ts

@@ -1,5 +1,6 @@
 import { getConfig } from '../config/loader.js';
 import { getSecureKey } from '../security/secure-keys.js';
+import { ConfigError } from '../util/errors.js';
 
 export interface ElevenLabsConfig {
   apiKey: string;
@@ -14,12 +15,12 @@ export function getElevenLabsConfig(): ElevenLabsConfig {
 
   const apiKey = getSecureKey('credential:elevenlabs:api_key') ?? '';
   if (!apiKey) {
-    throw new Error('ElevenLabs API key is not configured. Set credential:elevenlabs:api_key in the secure key store.');
+    throw new ConfigError('ElevenLabs API key is not configured. Set credential:elevenlabs:api_key in the secure key store.');
   }
 
   const agentId = voice.elevenlabs.agentId;
   if (!agentId) {
-    throw new Error('ElevenLabs agent ID is not configured. Set calls.voice.elevenlabs.agentId in config.');
+    throw new ConfigError('ElevenLabs agent ID is not configured. Set calls.voice.elevenlabs.agentId in config.');
   }
 
   return {

package/src/calls/guardian-action-sweep.ts

@@ -0,0 +1,105 @@
+/**
+ * Periodic sweep for expired guardian action requests.
+ *
+ * Runs on a 60-second interval. When a request has passed its expiresAt
+ * timestamp:
+ * 1. Expires the request and all its deliveries in the store
+ * 2. Expires the associated pending question so the call-side timeout fires
+ * 3. Sends expiry notices to external delivery destinations (telegram, sms)
+ * 4. Adds an expiry message to mac guardian thread conversations
+ */
+
+import { getLogger } from '../util/logger.js';
+import {
+  getExpiredGuardianActionRequests,
+  expireGuardianActionRequest,
+  getDeliveriesByRequestId,
+} from '../memory/guardian-action-store.js';
+import { expirePendingQuestions } from './call-store.js';
+import { deliverChannelReply } from '../runtime/gateway-client.js';
+import { addMessage } from '../memory/conversation-store.js';
+
+const log = getLogger('guardian-action-sweep');
+
+const SWEEP_INTERVAL_MS = 60_000;
+
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Sweep expired guardian action requests and clean up.
+ */
+export function sweepExpiredGuardianActions(
+  gatewayBaseUrl: string,
+  bearerToken?: string,
+): void {
+  const expired = getExpiredGuardianActionRequests();
+
+  for (const request of expired) {
+    // Capture deliveries before expiring (since expiry changes their status)
+    const deliveries = getDeliveriesByRequestId(request.id);
+
+    // Expire the request and all deliveries
+    expireGuardianActionRequest(request.id);
+
+    // Expire associated pending questions
+    expirePendingQuestions(request.callSessionId);
+
+    log.info(
+      { requestId: request.id, callSessionId: request.callSessionId },
+      'Expired guardian action request',
+    );
+
+    // Send expiry notices to each delivery destination
+    for (const delivery of deliveries) {
+      if (delivery.status !== 'sent' && delivery.status !== 'pending') continue;
+
+      if ((delivery.destinationChannel === 'macos' || delivery.destinationChannel === 'mac') && delivery.destinationConversationId) {
+        // Add expiry message to mac guardian thread
+        addMessage(
+          delivery.destinationConversationId,
+          'assistant',
+          JSON.stringify([{ type: 'text', text: 'This guardian question has expired without a response.' }]),
+          { userMessageChannel: 'voice', assistantMessageChannel: 'macos' },
+        );
+      } else if (delivery.destinationChatId) {
+        // External channel — send expiry notice
+        const deliverUrl = `${gatewayBaseUrl}/deliver/${delivery.destinationChannel}`;
+        void (async () => {
+          try {
+            await deliverChannelReply(deliverUrl, {
+              chatId: delivery.destinationChatId!,
+              text: 'The guardian question has expired without a response. The call has moved on.',
+              assistantId: request.assistantId,
+            }, bearerToken);
+          } catch (err) {
+            log.error(
+              { err, deliveryId: delivery.id, channel: delivery.destinationChannel },
+              'Failed to deliver guardian action expiry notice',
+            );
+          }
+        })();
+      }
+    }
+  }
+}
+
+export function startGuardianActionSweep(
+  gatewayBaseUrl: string,
+  bearerToken?: string,
+): void {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => {
+    try {
+      sweepExpiredGuardianActions(gatewayBaseUrl, bearerToken);
+    } catch (err) {
+      log.error({ err }, 'Guardian action sweep failed');
+    }
+  }, SWEEP_INTERVAL_MS);
+}
+
+export function stopGuardianActionSweep(): void {
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+}

package/src/calls/guardian-dispatch.ts

@@ -0,0 +1,203 @@
+/**
+ * Guardian dispatch engine for cross-channel voice calls.
+ *
+ * When a call orchestrator detects ASK_GUARDIAN, this module:
+ * 1. Creates a guardian_action_request
+ * 2. Determines delivery destinations (telegram, sms, macos)
+ * 3. Creates guardian_action_delivery rows for each destination
+ * 4. Sends HTTP POST to gateway for external channels
+ * 5. Emits IPC events for the mac channel
+ */
+
+import { getLogger } from '../util/logger.js';
+import { getGatewayInternalBaseUrl } from '../config/env.js';
+import { getActiveBinding } from '../memory/channel-guardian-store.js';
+import {
+  createGuardianActionRequest,
+  createGuardianActionDelivery,
+  updateDeliveryStatus,
+} from '../memory/guardian-action-store.js';
+import { deliverChannelReply } from '../runtime/gateway-client.js';
+import { getUserConsultationTimeoutMs } from './call-constants.js';
+import { getOrCreateConversation } from '../memory/conversation-key-store.js';
+import { addMessage } from '../memory/conversation-store.js';
+import type { CallPendingQuestion } from './types.js';
+import { readHttpToken } from '../util/platform.js';
+import type { ServerMessage } from '../daemon/ipc-contract.js';
+import { generateGuardianCopy } from './guardian-question-copy.js';
+
+const log = getLogger('guardian-dispatch');
+
+/** Resolve the gateway base URL for internal delivery callbacks. */
+function getGatewayBaseUrl(): string {
+  return getGatewayInternalBaseUrl();
+}
+
+export interface GuardianDispatchParams {
+  callSessionId: string;
+  conversationId: string;
+  assistantId: string;
+  pendingQuestion: CallPendingQuestion;
+  /** Broadcast function to emit IPC events to connected clients. */
+  broadcast?: (msg: ServerMessage) => void;
+}
+
+/**
+ * Dispatch a guardian action request to all configured channels.
+ * Fire-and-forget: errors are logged but do not propagate.
+ */
+export async function dispatchGuardianQuestion(params: GuardianDispatchParams): Promise<void> {
+  const {
+    callSessionId,
+    conversationId,
+    assistantId,
+    pendingQuestion,
+    broadcast,
+  } = params;
+
+  try {
+    const expiresAt = Date.now() + getUserConsultationTimeoutMs();
+
+    // Create the action request
+    const request = createGuardianActionRequest({
+      assistantId,
+      kind: 'ask_guardian',
+      sourceChannel: 'voice',
+      sourceConversationId: conversationId,
+      callSessionId,
+      pendingQuestionId: pendingQuestion.id,
+      questionText: pendingQuestion.questionText,
+      expiresAt,
+    });
+
+    log.info(
+      { requestId: request.id, requestCode: request.requestCode, callSessionId },
+      'Created guardian action request',
+    );
+
+    // Determine delivery destinations
+    const destinations: Array<{
+      channel: string;
+      chatId?: string;
+      externalUserId?: string;
+    }> = [];
+
+    // Telegram guardian binding
+    const telegramBinding = getActiveBinding(assistantId, 'telegram');
+    if (telegramBinding) {
+      destinations.push({
+        channel: 'telegram',
+        chatId: telegramBinding.guardianDeliveryChatId,
+        externalUserId: telegramBinding.guardianExternalUserId,
+      });
+    }
+
+    // SMS guardian binding
+    const smsBinding = getActiveBinding(assistantId, 'sms');
+    if (smsBinding) {
+      destinations.push({
+        channel: 'sms',
+        chatId: smsBinding.guardianDeliveryChatId,
+        externalUserId: smsBinding.guardianExternalUserId,
+      });
+    }
+
+    // Mac (internal) delivery — always created
+    destinations.push({ channel: 'macos' });
+
+    // Start LLM copy generation concurrently — only awaited in the macOS branch
+    // so external channels (Telegram, SMS) dispatch without LLM latency.
+    const guardianCopyPromise = generateGuardianCopy(
+      pendingQuestion.questionText,
+      request.requestCode,
+    );
+
+    // Create delivery rows and dispatch
+    for (const dest of destinations) {
+      if (dest.channel === 'macos') {
+        // Create conversation and delivery row synchronously so they exist
+        // before awaiting LLM copy — prevents a race where an external channel
+        // reply resolves the request before the macOS delivery is created.
+        const macConvKey = `asst:${assistantId}:guardian:request:${request.id}`;
+        const { conversationId: macConversationId } = getOrCreateConversation(macConvKey);
+
+        const delivery = createGuardianActionDelivery({
+          requestId: request.id,
+          destinationChannel: 'macos',
+          destinationConversationId: macConversationId,
+        });
+
+        // Now await LLM-generated copy for the message content and thread title
+        const guardianCopy = await guardianCopyPromise;
+
+        // Add the guardian question as the initial message in the thread
+        addMessage(
+          macConversationId,
+          'assistant',
+          JSON.stringify([{ type: 'text', text: guardianCopy.initialMessage }]),
+          { userMessageChannel: 'voice', assistantMessageChannel: 'macos' },
+        );
+
+        // Emit IPC event for the mac client with the server-created conversation
+        if (broadcast) {
+          broadcast({
+            type: 'guardian_request_thread_created',
+            conversationId: macConversationId,
+            requestId: request.id,
+            callSessionId,
+            title: guardianCopy.threadTitle,
+            questionText: request.questionText,
+          } as ServerMessage);
+        }
+        updateDeliveryStatus(delivery.id, 'sent');
+        log.info({ deliveryId: delivery.id, channel: 'macos', macConversationId }, 'Mac guardian delivery emitted');
+      } else {
+        const delivery = createGuardianActionDelivery({
+          requestId: request.id,
+          destinationChannel: dest.channel,
+          destinationChatId: dest.chatId,
+          destinationExternalUserId: dest.externalUserId,
+        });
+        // External channel — POST to gateway
+        void deliverToExternalChannel(delivery.id, dest.channel, dest.chatId!, request.questionText, request.requestCode, assistantId, readHttpToken() ?? undefined);
+      }
+    }
+  } catch (err) {
+    log.error({ err, callSessionId }, 'Failed to dispatch guardian question');
+  }
+}
+
+async function deliverToExternalChannel(
+  deliveryId: string,
+  channel: string,
+  chatId: string,
+  questionText: string,
+  requestCode: string,
+  assistantId: string,
+  bearerToken?: string,
+): Promise<void> {
+  const gatewayBase = getGatewayBaseUrl();
+  const deliverUrl = `${gatewayBase}/deliver/${channel}`;
+
+  const messageText = [
+    `Your assistant needs your input during a phone call.`,
+    ``,
+    `Question: ${questionText}`,
+    ``,
+    `Reply to this message with your answer. (ref: ${requestCode})`,
+  ].join('\n');
+
+  try {
+    await deliverChannelReply(deliverUrl, {
+      chatId,
+      text: messageText,
+      assistantId,
+    }, bearerToken);
+    updateDeliveryStatus(deliveryId, 'sent');
+    log.info({ deliveryId, channel, chatId }, 'External guardian delivery sent');
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    updateDeliveryStatus(deliveryId, 'failed', errorMsg);
+    log.error({ err, deliveryId, channel, chatId }, 'External guardian delivery failed');
+  }
+}