@vellumai/assistant 0.3.15 → 0.3.18

package/src/memory/guardian-action-store.ts

@@ -7,7 +7,7 @@
  * answer resolves the request and all other deliveries are marked answered.
  */
 
-import { and, eq, inArray, lt } from 'drizzle-orm';
+import { and, count, desc, eq, inArray, lt } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
 import { getLogger } from '../util/logger.js';
@@ -25,6 +25,9 @@ const log = getLogger('guardian-action-store');
 
 export type GuardianActionRequestStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
 export type GuardianActionDeliveryStatus = 'pending' | 'sent' | 'failed' | 'answered' | 'expired' | 'cancelled';
+export type ExpiredReason = 'call_timeout' | 'sweep_timeout' | 'cancelled';
+export type FollowupState = 'none' | 'awaiting_guardian_choice' | 'dispatching' | 'completed' | 'declined' | 'failed';
+export type FollowupAction = 'call_back' | 'message_back' | 'decline';
 
 export interface GuardianActionRequest {
   id: string;
@@ -42,6 +45,12 @@ export interface GuardianActionRequest {
   answeredByExternalUserId: string | null;
   answeredAt: number | null;
   expiresAt: number;
+  expiredReason: ExpiredReason | null;
+  followupState: FollowupState;
+  lateAnswerText: string | null;
+  lateAnsweredAt: number | null;
+  followupAction: FollowupAction | null;
+  followupCompletedAt: number | null;
   createdAt: number;
   updatedAt: number;
 }
@@ -82,6 +91,12 @@ function rowToRequest(row: typeof guardianActionRequests.$inferSelect): Guardian
     answeredByExternalUserId: row.answeredByExternalUserId,
     answeredAt: row.answeredAt,
     expiresAt: row.expiresAt,
+    expiredReason: (row.expiredReason as ExpiredReason) ?? null,
+    followupState: (row.followupState as FollowupState) ?? 'none',
+    lateAnswerText: row.lateAnswerText ?? null,
+    lateAnsweredAt: row.lateAnsweredAt ?? null,
+    followupAction: (row.followupAction as FollowupAction) ?? null,
+    followupCompletedAt: row.followupCompletedAt ?? null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -143,6 +158,12 @@ export function createGuardianActionRequest(params: {
     answeredByExternalUserId: null,
     answeredAt: null,
     expiresAt: params.expiresAt,
+    expiredReason: null,
+    followupState: 'none' as const,
+    lateAnswerText: null,
+    lateAnsweredAt: null,
+    followupAction: null,
+    followupCompletedAt: null,
     createdAt: now,
     updatedAt: now,
   };
@@ -171,6 +192,46 @@ export function getByPendingQuestionId(questionId: string): GuardianActionReques
   return row ? rowToRequest(row) : null;
 }
 
+/**
+ * Find the most recent pending guardian action request for a given call session.
+ * Used by the consultation timeout handler to mark the linked request as timed out.
+ */
+export function getPendingRequestByCallSessionId(callSessionId: string): GuardianActionRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(guardianActionRequests)
+    .where(
+      and(
+        eq(guardianActionRequests.callSessionId, callSessionId),
+        eq(guardianActionRequests.status, 'pending'),
+      ),
+    )
+    .orderBy(desc(guardianActionRequests.createdAt))
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+/**
+ * Count pending guardian action requests for a given call session.
+ * Used as a candidate-affinity hint so the decision engine knows how many
+ * active guardian requests already exist for the current call.
+ */
+export function countPendingRequestsByCallSessionId(callSessionId: string): number {
+  const db = getDb();
+  const row = db
+    .select({ count: count() })
+    .from(guardianActionRequests)
+    .where(
+      and(
+        eq(guardianActionRequests.callSessionId, callSessionId),
+        eq(guardianActionRequests.status, 'pending'),
+      ),
+    )
+    .get();
+  return row?.count ?? 0;
+}
+
 /**
  * First-response-wins resolution. Checks that the request is still
  * 'pending' before updating; returns the updated request on success
@@ -217,13 +278,14 @@ export function resolveGuardianActionRequest(
 
 /**
  * Expire a guardian action request and all its deliveries.
+ * When reason is not provided, defaults to 'sweep_timeout' for backward compatibility.
  */
-export function expireGuardianActionRequest(id: string): void {
+export function expireGuardianActionRequest(id: string, reason?: ExpiredReason): void {
   const db = getDb();
   const now = Date.now();
 
   db.update(guardianActionRequests)
-    .set({ status: 'expired', updatedAt: now })
+    .set({ status: 'expired', expiredReason: reason ?? 'sweep_timeout', updatedAt: now })
     .where(
       and(
         eq(guardianActionRequests.id, id),
@@ -303,6 +365,175 @@ export function cancelGuardianActionRequest(id: string): void {
     .run();
 }
 
+// ---------------------------------------------------------------------------
+// Follow-up lifecycle helpers
+// ---------------------------------------------------------------------------
+
+/** Valid non-terminal followup_state transitions for progressFollowupState.
+ * Terminal states (completed, declined, failed) are only reachable via
+ * finalizeFollowup, which properly sets followupCompletedAt. */
+const FOLLOWUP_TRANSITIONS: Record<FollowupState, FollowupState[]> = {
+  none: [],
+  awaiting_guardian_choice: ['dispatching'],
+  dispatching: [],
+  completed: [],
+  declined: [],
+  failed: [],
+};
+
+/** Valid terminal transitions for finalizeFollowup. Maps from current
+ * followup_state to the terminal states reachable from it. */
+const FOLLOWUP_FINALIZE_TRANSITIONS: Partial<Record<FollowupState, FollowupState[]>> = {
+  awaiting_guardian_choice: ['declined'],
+  dispatching: ['completed', 'failed'],
+};
+
+/**
+ * Atomically set status='expired' and expired_reason on a pending request.
+ * Returns the updated request on success, or null if the request was not
+ * in 'pending' status (first-writer-wins).
+ */
+export function markTimedOutWithReason(id: string, reason: ExpiredReason): GuardianActionRequest | null {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(guardianActionRequests)
+    .set({ status: 'expired', expiredReason: reason, updatedAt: now })
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'pending'),
+      ),
+    )
+    .run();
+
+  if (rawChanges() === 0) return null;
+
+  // Also expire active deliveries
+  db.update(guardianActionDeliveries)
+    .set({ status: 'expired', updatedAt: now })
+    .where(
+      and(
+        eq(guardianActionDeliveries.requestId, id),
+        inArray(guardianActionDeliveries.status, ['pending', 'sent']),
+      ),
+    )
+    .run();
+
+  return getGuardianActionRequest(id);
+}
+
+/**
+ * Atomically transition an expired request into the follow-up flow.
+ * Sets followup_state='awaiting_guardian_choice', records the late answer
+ * text and timestamp. Only succeeds if status='expired' and followup_state='none'.
+ * Returns the updated request on success, or null on conflict.
+ */
+export function startFollowupFromExpiredRequest(
+  id: string,
+  lateAnswerText: string,
+): GuardianActionRequest | null {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(guardianActionRequests)
+    .set({
+      followupState: 'awaiting_guardian_choice',
+      lateAnswerText,
+      lateAnsweredAt: now,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'expired'),
+        eq(guardianActionRequests.followupState, 'none'),
+      ),
+    )
+    .run();
+
+  if (rawChanges() === 0) return null;
+  return getGuardianActionRequest(id);
+}
+
+/**
+ * Atomically progress the followup_state. Validates that the transition
+ * is allowed (see FOLLOWUP_TRANSITIONS). Optionally sets the followup_action.
+ * Returns the updated request on success, or null if the transition was
+ * invalid or the prior state didn't match.
+ */
+export function progressFollowupState(
+  id: string,
+  newState: FollowupState,
+  action?: FollowupAction,
+): GuardianActionRequest | null {
+  const request = getGuardianActionRequest(id);
+  if (!request) return null;
+
+  const allowed = FOLLOWUP_TRANSITIONS[request.followupState];
+  if (!allowed.includes(newState)) return null;
+
+  const db = getDb();
+  const now = Date.now();
+
+  const updates: Record<string, unknown> = {
+    followupState: newState,
+    updatedAt: now,
+  };
+  if (action !== undefined) updates.followupAction = action;
+
+  db.update(guardianActionRequests)
+    .set(updates)
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'expired'),
+        eq(guardianActionRequests.followupState, request.followupState),
+      ),
+    )
+    .run();
+
+  if (rawChanges() === 0) return null;
+  return getGuardianActionRequest(id);
+}
+
+/**
+ * Finalize a follow-up by setting the terminal followup_state and
+ * recording followup_completed_at. Only succeeds from a non-terminal state
+ * and only on expired requests.
+ */
+export function finalizeFollowup(
+  id: string,
+  finalState: 'completed' | 'declined' | 'failed',
+): GuardianActionRequest | null {
+  const request = getGuardianActionRequest(id);
+  if (!request) return null;
+
+  const allowed = FOLLOWUP_FINALIZE_TRANSITIONS[request.followupState];
+  if (!allowed?.includes(finalState)) return null;
+
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(guardianActionRequests)
+    .set({
+      followupState: finalState,
+      followupCompletedAt: now,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'expired'),
+        eq(guardianActionRequests.followupState, request.followupState),
+      ),
+    )
+    .run();
+
+  if (rawChanges() === 0) return null;
+  return getGuardianActionRequest(id);
+}
+
 // ---------------------------------------------------------------------------
 // Guardian Action Deliveries
 // ---------------------------------------------------------------------------
@@ -384,6 +615,16 @@ export function getPendingDeliveriesByDestination(
  * Look up a pending delivery by destination conversation ID (for mac channel routing).
  */
 export function getPendingDeliveryByConversation(conversationId: string): GuardianActionDelivery | null {
+  const all = getPendingDeliveriesByConversation(conversationId);
+  return all.length > 0 ? all[0] : null;
+}
+
+/**
+ * Look up all pending deliveries by destination conversation ID.
+ * Used for disambiguation when a reused vellum thread has multiple active
+ * guardian requests.
+ */
+export function getPendingDeliveriesByConversation(conversationId: string): GuardianActionDelivery[] {
   try {
     const db = getDb();
     const rows = db
@@ -401,11 +642,183 @@ export function getPendingDeliveryByConversation(conversationId: string): Guardi
         ),
       )
       .all();
-    return rows.length > 0 ? rowToDelivery(rows[0].delivery) : null;
+    return rows.map((r) => rowToDelivery(r.delivery));
   } catch (err) {
     if (err instanceof Error && err.message.includes('no such table')) {
       log.warn({ err }, 'guardian tables not yet created');
-      return null;
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * Look up sent deliveries for expired requests eligible for follow-up.
+ * Used by inbound message routing to match late guardian answers to expired requests.
+ */
+export function getExpiredDeliveriesByDestination(
+  assistantId: string,
+  channel: string,
+  chatId: string,
+): GuardianActionDelivery[] {
+  try {
+    const db = getDb();
+
+    const rows = db
+      .select({
+        delivery: guardianActionDeliveries,
+      })
+      .from(guardianActionDeliveries)
+      .innerJoin(
+        guardianActionRequests,
+        eq(guardianActionDeliveries.requestId, guardianActionRequests.id),
+      )
+      .where(
+        and(
+          eq(guardianActionRequests.assistantId, assistantId),
+          eq(guardianActionRequests.status, 'expired'),
+          eq(guardianActionRequests.followupState, 'none'),
+          eq(guardianActionDeliveries.destinationChannel, channel),
+          eq(guardianActionDeliveries.destinationChatId, chatId),
+          eq(guardianActionDeliveries.status, 'expired'),
+        ),
+      )
+      .all();
+
+    return rows.map((r) => rowToDelivery(r.delivery));
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('no such table')) {
+      log.warn({ err }, 'guardian tables not yet created');
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * Look up an expired delivery by destination conversation ID (for mac channel routing).
+ */
+export function getExpiredDeliveryByConversation(conversationId: string): GuardianActionDelivery | null {
+  const all = getExpiredDeliveriesByConversation(conversationId);
+  return all.length > 0 ? all[0] : null;
+}
+
+/**
+ * Look up all expired deliveries by destination conversation ID.
+ * Used for disambiguation when a reused vellum thread has multiple expired
+ * guardian requests eligible for follow-up.
+ */
+export function getExpiredDeliveriesByConversation(conversationId: string): GuardianActionDelivery[] {
+  try {
+    const db = getDb();
+    const rows = db
+      .select({ delivery: guardianActionDeliveries })
+      .from(guardianActionDeliveries)
+      .innerJoin(
+        guardianActionRequests,
+        eq(guardianActionDeliveries.requestId, guardianActionRequests.id),
+      )
+      .where(
+        and(
+          eq(guardianActionDeliveries.destinationConversationId, conversationId),
+          eq(guardianActionDeliveries.status, 'expired'),
+          eq(guardianActionRequests.status, 'expired'),
+          eq(guardianActionRequests.followupState, 'none'),
+        ),
+      )
+      .all();
+    return rows.map((r) => rowToDelivery(r.delivery));
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('no such table')) {
+      log.warn({ err }, 'guardian tables not yet created');
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * Look up deliveries for requests in `awaiting_guardian_choice` follow-up state.
+ * Used by inbound message routing to intercept guardian follow-up replies
+ * on channel paths (Telegram, SMS).
+ */
+export function getFollowupDeliveriesByDestination(
+  assistantId: string,
+  channel: string,
+  chatId: string,
+): GuardianActionDelivery[] {
+  try {
+    const db = getDb();
+
+    const rows = db
+      .select({
+        delivery: guardianActionDeliveries,
+      })
+      .from(guardianActionDeliveries)
+      .innerJoin(
+        guardianActionRequests,
+        eq(guardianActionDeliveries.requestId, guardianActionRequests.id),
+      )
+      .where(
+        and(
+          eq(guardianActionRequests.assistantId, assistantId),
+          eq(guardianActionRequests.status, 'expired'),
+          eq(guardianActionRequests.followupState, 'awaiting_guardian_choice'),
+          eq(guardianActionDeliveries.destinationChannel, channel),
+          eq(guardianActionDeliveries.destinationChatId, chatId),
+          eq(guardianActionDeliveries.status, 'expired'),
+        ),
+      )
+      .all();
+
+    return rows.map((r) => rowToDelivery(r.delivery));
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('no such table')) {
+      log.warn({ err }, 'guardian tables not yet created');
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * Look up a delivery for a request in `awaiting_guardian_choice` follow-up
+ * state by destination conversation ID (for mac channel routing).
+ */
+export function getFollowupDeliveryByConversation(conversationId: string): GuardianActionDelivery | null {
+  const all = getFollowupDeliveriesByConversation(conversationId);
+  return all.length > 0 ? all[0] : null;
+}
+
+/**
+ * Look up all deliveries for requests in `awaiting_guardian_choice` follow-up
+ * state by destination conversation ID. Used for disambiguation when a reused
+ * vellum thread has multiple follow-up guardian requests.
+ */
+export function getFollowupDeliveriesByConversation(conversationId: string): GuardianActionDelivery[] {
+  try {
+    const db = getDb();
+    const rows = db
+      .select({ delivery: guardianActionDeliveries })
+      .from(guardianActionDeliveries)
+      .innerJoin(
+        guardianActionRequests,
+        eq(guardianActionDeliveries.requestId, guardianActionRequests.id),
+      )
+      .where(
+        and(
+          eq(guardianActionDeliveries.destinationConversationId, conversationId),
+          eq(guardianActionDeliveries.status, 'expired'),
+          eq(guardianActionRequests.status, 'expired'),
+          eq(guardianActionRequests.followupState, 'awaiting_guardian_choice'),
+        ),
+      )
+      .all();
+    return rows.map((r) => rowToDelivery(r.delivery));
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('no such table')) {
+      log.warn({ err }, 'guardian tables not yet created');
+      return [];
     }
     throw err;
   }