@vellumai/assistant 0.3.5 → 0.3.7

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

@@ -0,0 +1,430 @@
+/**
+ * Store for cross-channel guardian action requests and deliveries.
+ *
+ * Guardian action requests are created when a voice call's ASK_GUARDIAN
+ * marker fires, and deliveries track per-channel dispatch (telegram, sms, mac).
+ * Resolution uses first-response-wins semantics: the first channel to
+ * answer resolves the request and all other deliveries are marked answered.
+ */
+
+import { and, eq, lt, inArray } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import { getDb, rawChanges } from './db.js';
+import {
+  guardianActionRequests,
+  guardianActionDeliveries,
+} from './schema.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('guardian-action-store');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type GuardianActionRequestStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
+export type GuardianActionDeliveryStatus = 'pending' | 'sent' | 'failed' | 'answered' | 'expired' | 'cancelled';
+
+export interface GuardianActionRequest {
+  id: string;
+  assistantId: string;
+  kind: string;
+  sourceChannel: string;
+  sourceConversationId: string;
+  callSessionId: string;
+  pendingQuestionId: string;
+  questionText: string;
+  requestCode: string;
+  status: GuardianActionRequestStatus;
+  answerText: string | null;
+  answeredByChannel: string | null;
+  answeredByExternalUserId: string | null;
+  answeredAt: number | null;
+  expiresAt: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface GuardianActionDelivery {
+  id: string;
+  requestId: string;
+  destinationChannel: string;
+  destinationConversationId: string | null;
+  destinationChatId: string | null;
+  destinationExternalUserId: string | null;
+  status: GuardianActionDeliveryStatus;
+  sentAt: number | null;
+  respondedAt: number | null;
+  lastError: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToRequest(row: typeof guardianActionRequests.$inferSelect): GuardianActionRequest {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    kind: row.kind,
+    sourceChannel: row.sourceChannel,
+    sourceConversationId: row.sourceConversationId,
+    callSessionId: row.callSessionId,
+    pendingQuestionId: row.pendingQuestionId,
+    questionText: row.questionText,
+    requestCode: row.requestCode,
+    status: row.status as GuardianActionRequestStatus,
+    answerText: row.answerText,
+    answeredByChannel: row.answeredByChannel,
+    answeredByExternalUserId: row.answeredByExternalUserId,
+    answeredAt: row.answeredAt,
+    expiresAt: row.expiresAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function rowToDelivery(row: typeof guardianActionDeliveries.$inferSelect): GuardianActionDelivery {
+  return {
+    id: row.id,
+    requestId: row.requestId,
+    destinationChannel: row.destinationChannel,
+    destinationConversationId: row.destinationConversationId,
+    destinationChatId: row.destinationChatId,
+    destinationExternalUserId: row.destinationExternalUserId,
+    status: row.status as GuardianActionDeliveryStatus,
+    sentAt: row.sentAt,
+    respondedAt: row.respondedAt,
+    lastError: row.lastError,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/** Generate a short human-readable request code (6 hex chars). */
+function generateRequestCode(): string {
+  return uuid().replace(/-/g, '').slice(0, 6).toUpperCase();
+}
+
+// ---------------------------------------------------------------------------
+// Guardian Action Requests
+// ---------------------------------------------------------------------------
+
+export function createGuardianActionRequest(params: {
+  assistantId?: string;
+  kind: string;
+  sourceChannel: string;
+  sourceConversationId: string;
+  callSessionId: string;
+  pendingQuestionId: string;
+  questionText: string;
+  expiresAt: number;
+}): GuardianActionRequest {
+  const db = getDb();
+  const now = Date.now();
+  const id = uuid();
+
+  const row = {
+    id,
+    assistantId: params.assistantId ?? 'self',
+    kind: params.kind,
+    sourceChannel: params.sourceChannel,
+    sourceConversationId: params.sourceConversationId,
+    callSessionId: params.callSessionId,
+    pendingQuestionId: params.pendingQuestionId,
+    questionText: params.questionText,
+    requestCode: generateRequestCode(),
+    status: 'pending' as const,
+    answerText: null,
+    answeredByChannel: null,
+    answeredByExternalUserId: null,
+    answeredAt: null,
+    expiresAt: params.expiresAt,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(guardianActionRequests).values(row).run();
+  return rowToRequest(row);
+}
+
+export function getGuardianActionRequest(id: string): GuardianActionRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(guardianActionRequests)
+    .where(eq(guardianActionRequests.id, id))
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+export function getByPendingQuestionId(questionId: string): GuardianActionRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(guardianActionRequests)
+    .where(eq(guardianActionRequests.pendingQuestionId, questionId))
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+/**
+ * First-response-wins resolution. Checks that the request is still
+ * 'pending' before updating; returns the updated request on success
+ * or null if the request was already resolved.
+ */
+export function resolveGuardianActionRequest(
+  id: string,
+  answerText: string,
+  answeredByChannel: string,
+  answeredByExternalUserId?: string,
+): GuardianActionRequest | null {
+  const db = getDb();
+  const now = Date.now();
+
+  // Atomically check-and-update: only update if status is still 'pending'
+  db.update(guardianActionRequests)
+    .set({
+      status: 'answered',
+      answerText,
+      answeredByChannel,
+      answeredByExternalUserId: answeredByExternalUserId ?? null,
+      answeredAt: now,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'pending'),
+      ),
+    )
+    .run();
+
+  // Check if the update took effect
+  if (rawChanges() === 0) return null;
+
+  // Mark all deliveries as 'answered'
+  db.update(guardianActionDeliveries)
+    .set({ status: 'answered', respondedAt: now, updatedAt: now })
+    .where(eq(guardianActionDeliveries.requestId, id))
+    .run();
+
+  return getGuardianActionRequest(id);
+}
+
+/**
+ * Expire a guardian action request and all its deliveries.
+ */
+export function expireGuardianActionRequest(id: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(guardianActionRequests)
+    .set({ status: 'expired', updatedAt: now })
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'pending'),
+      ),
+    )
+    .run();
+
+  db.update(guardianActionDeliveries)
+    .set({ status: 'expired', updatedAt: now })
+    .where(
+      and(
+        eq(guardianActionDeliveries.requestId, id),
+        inArray(guardianActionDeliveries.status, ['pending', 'sent']),
+      ),
+    )
+    .run();
+}
+
+/**
+ * Get all pending guardian action requests that have expired.
+ */
+export function getExpiredGuardianActionRequests(): GuardianActionRequest[] {
+  const db = getDb();
+  const now = Date.now();
+  return db
+    .select()
+    .from(guardianActionRequests)
+    .where(
+      and(
+        eq(guardianActionRequests.status, 'pending'),
+        lt(guardianActionRequests.expiresAt, now),
+      ),
+    )
+    .all()
+    .map(rowToRequest);
+}
+
+/**
+ * Get all deliveries for a specific request.
+ */
+export function getDeliveriesByRequestId(requestId: string): GuardianActionDelivery[] {
+  const db = getDb();
+  return db
+    .select()
+    .from(guardianActionDeliveries)
+    .where(eq(guardianActionDeliveries.requestId, requestId))
+    .all()
+    .map(rowToDelivery);
+}
+
+/**
+ * Cancel a guardian action request and all its deliveries.
+ */
+export function cancelGuardianActionRequest(id: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(guardianActionRequests)
+    .set({ status: 'cancelled', updatedAt: now })
+    .where(
+      and(
+        eq(guardianActionRequests.id, id),
+        eq(guardianActionRequests.status, 'pending'),
+      ),
+    )
+    .run();
+
+  db.update(guardianActionDeliveries)
+    .set({ status: 'cancelled', updatedAt: now })
+    .where(
+      and(
+        eq(guardianActionDeliveries.requestId, id),
+        inArray(guardianActionDeliveries.status, ['pending', 'sent']),
+      ),
+    )
+    .run();
+}
+
+// ---------------------------------------------------------------------------
+// Guardian Action Deliveries
+// ---------------------------------------------------------------------------
+
+export function createGuardianActionDelivery(params: {
+  requestId: string;
+  destinationChannel: string;
+  destinationConversationId?: string;
+  destinationChatId?: string;
+  destinationExternalUserId?: string;
+}): GuardianActionDelivery {
+  const db = getDb();
+  const now = Date.now();
+  const id = uuid();
+
+  const row = {
+    id,
+    requestId: params.requestId,
+    destinationChannel: params.destinationChannel,
+    destinationConversationId: params.destinationConversationId ?? null,
+    destinationChatId: params.destinationChatId ?? null,
+    destinationExternalUserId: params.destinationExternalUserId ?? null,
+    status: 'pending' as const,
+    sentAt: null,
+    respondedAt: null,
+    lastError: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(guardianActionDeliveries).values(row).run();
+  return rowToDelivery(row);
+}
+
+/**
+ * Look up pending deliveries for a specific destination.
+ * Used by inbound message routing to match incoming answers to deliveries.
+ */
+export function getPendingDeliveriesByDestination(
+  assistantId: string,
+  channel: string,
+  chatId: string,
+): GuardianActionDelivery[] {
+  try {
+    const db = getDb();
+
+    // Join deliveries with requests to filter by assistantId
+    const rows = db
+      .select({
+        delivery: guardianActionDeliveries,
+      })
+      .from(guardianActionDeliveries)
+      .innerJoin(
+        guardianActionRequests,
+        eq(guardianActionDeliveries.requestId, guardianActionRequests.id),
+      )
+      .where(
+        and(
+          eq(guardianActionRequests.assistantId, assistantId),
+          eq(guardianActionRequests.status, 'pending'),
+          eq(guardianActionDeliveries.destinationChannel, channel),
+          eq(guardianActionDeliveries.destinationChatId, chatId),
+          eq(guardianActionDeliveries.status, 'sent'),
+        ),
+      )
+      .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 pending delivery by destination conversation ID (for mac channel routing).
+ */
+export function getPendingDeliveryByConversation(conversationId: string): GuardianActionDelivery | null {
+  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, 'sent'),
+          eq(guardianActionRequests.status, 'pending'),
+        ),
+      )
+      .all();
+    return rows.length > 0 ? rowToDelivery(rows[0].delivery) : null;
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('no such table')) {
+      log.warn({ err }, 'guardian tables not yet created');
+      return null;
+    }
+    throw err;
+  }
+}
+
+export function updateDeliveryStatus(
+  deliveryId: string,
+  status: GuardianActionDeliveryStatus,
+  error?: string,
+): void {
+  const db = getDb();
+  const now = Date.now();
+
+  const updates: Record<string, unknown> = { status, updatedAt: now };
+  if (status === 'sent') updates.sentAt = now;
+  if (status === 'answered') updates.respondedAt = now;
+  if (error !== undefined) updates.lastError = error;
+
+  db.update(guardianActionDeliveries)
+    .set(updates)
+    .where(eq(guardianActionDeliveries.id, deliveryId))
+    .run();
+}

package/src/memory/inbox-escalation-projection.ts

@@ -0,0 +1,59 @@
+/**
+ * Projects escalation state from channel_guardian_approval_requests onto
+ * assistant_inbox_thread_state.
+ *
+ * Keeps the inbox UI's escalation badges (pending_escalation_count,
+ * has_pending_escalation) in sync with the current set of pending
+ * guardian approval requests.
+ */
+
+import { countPendingByConversation } from './channel-guardian-store.js';
+import { updateEscalationState } from './inbox-thread-store.js';
+import { getDb } from './db.js';
+import { getSqliteFrom } from './db-connection.js';
+
+/**
+ * Recompute pending escalation counts for all inbox threads and update
+ * the thread state rows. Called periodically or after approval decisions
+ * to keep the inbox UI's escalation badges accurate.
+ *
+ * Uses a single SQL UPDATE to set counts for all threads in one shot,
+ * handling both new escalations and cleared ones atomically.
+ */
+export function refreshEscalationProjection(assistantId: string = 'self'): void {
+  const db = getDb();
+  const sqlite = getSqliteFrom(db);
+  const now = Date.now();
+
+  sqlite
+    .query(
+      `UPDATE assistant_inbox_thread_state
+       SET pending_escalation_count = (
+         SELECT COUNT(*) FROM channel_guardian_approval_requests
+         WHERE channel_guardian_approval_requests.conversation_id = assistant_inbox_thread_state.conversation_id
+           AND channel_guardian_approval_requests.status = 'pending'
+           AND channel_guardian_approval_requests.assistant_id = ?1
+       ),
+       has_pending_escalation = CASE WHEN (
+         SELECT COUNT(*) FROM channel_guardian_approval_requests
+         WHERE channel_guardian_approval_requests.conversation_id = assistant_inbox_thread_state.conversation_id
+           AND channel_guardian_approval_requests.status = 'pending'
+           AND channel_guardian_approval_requests.assistant_id = ?1
+       ) > 0 THEN 1 ELSE 0 END,
+       updated_at = ?2
+       WHERE assistant_id = ?1`,
+    )
+    .run(assistantId, now);
+}
+
+/**
+ * Refresh escalation state for a single thread. More efficient than
+ * refreshing all threads when only one conversation changed.
+ */
+export function refreshThreadEscalation(
+  conversationId: string,
+  assistantId: string = 'self',
+): void {
+  const pendingCount = countPendingByConversation(conversationId, assistantId);
+  updateEscalationState(conversationId, pendingCount);
+}

package/src/memory/inbox-thread-store.ts

@@ -0,0 +1,218 @@
+/**
+ * Query helpers for the assistant_inbox_thread_state table.
+ *
+ * Provides CRUD operations for inbox thread state — the denormalized
+ * view that powers the assistant's inbox UI with per-thread metadata
+ * (unread counts, escalation state, last activity timestamps).
+ */
+
+import { and, eq, sql } from 'drizzle-orm';
+import { getDb } from './db.js';
+import { assistantInboxThreadState } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type InboxThread = typeof assistantInboxThreadState.$inferSelect;
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+/**
+ * List inbox threads ordered by most recent activity.
+ * NULL last_message_at values sort last.
+ */
+export function listThreads(params?: {
+  assistantId?: string;
+  limit?: number;
+  offset?: number;
+}): InboxThread[] {
+  const db = getDb();
+  const assistantId = params?.assistantId ?? 'self';
+  const limit = params?.limit ?? 50;
+  const offset = params?.offset ?? 0;
+
+  return db
+    .select()
+    .from(assistantInboxThreadState)
+    .where(eq(assistantInboxThreadState.assistantId, assistantId))
+    .orderBy(sql`${assistantInboxThreadState.lastMessageAt} DESC NULLS LAST`)
+    .limit(limit)
+    .offset(offset)
+    .all();
+}
+
+/**
+ * Get a single thread by its conversation ID (the primary key).
+ */
+export function getThread(conversationId: string): InboxThread | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(assistantInboxThreadState)
+    .where(eq(assistantInboxThreadState.conversationId, conversationId))
+    .get();
+
+  return row ?? null;
+}
+
+/**
+ * Look up a thread by its unique binding (assistant_id, source_channel, external_chat_id).
+ */
+export function getThreadByBinding(
+  assistantId: string,
+  sourceChannel: string,
+  externalChatId: string,
+): InboxThread | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(assistantInboxThreadState)
+    .where(
+      and(
+        eq(assistantInboxThreadState.assistantId, assistantId),
+        eq(assistantInboxThreadState.sourceChannel, sourceChannel),
+        eq(assistantInboxThreadState.externalChatId, externalChatId),
+      ),
+    )
+    .get();
+
+  return row ?? null;
+}
+
+/**
+ * Create or update an inbox thread state row.
+ * If a row with the given conversationId exists, updates display fields and updated_at.
+ * Otherwise, creates a new row with counters initialized to 0.
+ */
+export function upsertThread(params: {
+  conversationId: string;
+  assistantId?: string;
+  sourceChannel: string;
+  externalChatId: string;
+  externalUserId?: string;
+  displayName?: string;
+  username?: string;
+}): InboxThread {
+  const db = getDb();
+  const now = Date.now();
+  const assistantId = params.assistantId ?? 'self';
+
+  const existing = getThread(params.conversationId);
+
+  if (existing) {
+    db.update(assistantInboxThreadState)
+      .set({
+        displayName: params.displayName ?? existing.displayName,
+        username: params.username ?? existing.username,
+        externalUserId: params.externalUserId ?? existing.externalUserId,
+        updatedAt: now,
+      })
+      .where(eq(assistantInboxThreadState.conversationId, params.conversationId))
+      .run();
+
+    return {
+      ...existing,
+      displayName: params.displayName ?? existing.displayName,
+      username: params.username ?? existing.username,
+      externalUserId: params.externalUserId ?? existing.externalUserId,
+      updatedAt: now,
+    };
+  }
+
+  const row = {
+    conversationId: params.conversationId,
+    assistantId,
+    sourceChannel: params.sourceChannel,
+    externalChatId: params.externalChatId,
+    externalUserId: params.externalUserId ?? null,
+    displayName: params.displayName ?? null,
+    username: params.username ?? null,
+    lastInboundAt: null,
+    lastOutboundAt: null,
+    lastMessageAt: null,
+    unreadCount: 0,
+    pendingEscalationCount: 0,
+    hasPendingEscalation: 0,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(assistantInboxThreadState).values(row).run();
+
+  return row;
+}
+
+/**
+ * Record message activity on a thread.
+ * - inbound: updates last_inbound_at, last_message_at, increments unread_count
+ * - outbound: updates last_outbound_at, last_message_at, resets unread_count to 0
+ */
+export function updateThreadActivity(
+  conversationId: string,
+  direction: 'inbound' | 'outbound',
+): void {
+  const db = getDb();
+  const now = Date.now();
+
+  if (direction === 'inbound') {
+    db.update(assistantInboxThreadState)
+      .set({
+        lastInboundAt: now,
+        lastMessageAt: now,
+        unreadCount: sql`${assistantInboxThreadState.unreadCount} + 1`,
+        updatedAt: now,
+      })
+      .where(eq(assistantInboxThreadState.conversationId, conversationId))
+      .run();
+  } else {
+    db.update(assistantInboxThreadState)
+      .set({
+        lastOutboundAt: now,
+        lastMessageAt: now,
+        unreadCount: 0,
+        updatedAt: now,
+      })
+      .where(eq(assistantInboxThreadState.conversationId, conversationId))
+      .run();
+  }
+}
+
+/**
+ * Mark a thread as read by resetting its unread count.
+ */
+export function markThreadRead(conversationId: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(assistantInboxThreadState)
+    .set({
+      unreadCount: 0,
+      updatedAt: now,
+    })
+    .where(eq(assistantInboxThreadState.conversationId, conversationId))
+    .run();
+}
+
+/**
+ * Update the escalation state for a thread.
+ * Sets pending_escalation_count and derives has_pending_escalation from it.
+ */
+export function updateEscalationState(
+  conversationId: string,
+  pendingCount: number,
+): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(assistantInboxThreadState)
+    .set({
+      pendingEscalationCount: pendingCount,
+      hasPendingEscalation: pendingCount > 0 ? 1 : 0,
+      updatedAt: now,
+    })
+    .where(eq(assistantInboxThreadState.conversationId, conversationId))
+    .run();
+}