@vellumai/assistant 0.3.7 → 0.3.9

package/src/notifications/decisions-store.ts

@@ -0,0 +1,158 @@
+/**
+ * CRUD operations for notification decisions.
+ *
+ * Each row records the routing decision made by the decision engine for
+ * a given notification event: whether to notify, which channels, and the
+ * reasoning behind it. This provides a full audit trail of how signals
+ * were routed.
+ */
+
+import { and, desc, eq } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { notificationDecisions, notificationEvents } from '../memory/schema.js';
+
+export interface NotificationDecisionRow {
+  id: string;
+  notificationEventId: string;
+  shouldNotify: boolean;
+  selectedChannels: string; // JSON array
+  reasoningSummary: string;
+  confidence: number;
+  fallbackUsed: boolean;
+  promptVersion: string | null;
+  validationResults: string | null; // JSON
+  createdAt: number;
+}
+
+function rowToDecision(row: typeof notificationDecisions.$inferSelect): NotificationDecisionRow {
+  return {
+    id: row.id,
+    notificationEventId: row.notificationEventId,
+    shouldNotify: row.shouldNotify === 1,
+    selectedChannels: row.selectedChannels,
+    reasoningSummary: row.reasoningSummary,
+    confidence: row.confidence,
+    fallbackUsed: row.fallbackUsed === 1,
+    promptVersion: row.promptVersion,
+    validationResults: row.validationResults,
+    createdAt: row.createdAt,
+  };
+}
+
+export interface CreateDecisionParams {
+  id: string;
+  notificationEventId: string;
+  shouldNotify: boolean;
+  selectedChannels: string[]; // will be serialised to JSON
+  reasoningSummary: string;
+  confidence: number;
+  fallbackUsed: boolean;
+  promptVersion?: string;
+  validationResults?: Record<string, unknown>;
+}
+
+/** Insert a new decision record. */
+export function createDecision(params: CreateDecisionParams): NotificationDecisionRow {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = {
+    id: params.id,
+    notificationEventId: params.notificationEventId,
+    shouldNotify: params.shouldNotify ? 1 : 0,
+    selectedChannels: JSON.stringify(params.selectedChannels),
+    reasoningSummary: params.reasoningSummary,
+    confidence: params.confidence,
+    fallbackUsed: params.fallbackUsed ? 1 : 0,
+    promptVersion: params.promptVersion ?? null,
+    validationResults: params.validationResults ? JSON.stringify(params.validationResults) : null,
+    createdAt: now,
+  };
+
+  db.insert(notificationDecisions).values(row).run();
+
+  return {
+    ...row,
+    shouldNotify: params.shouldNotify,
+    fallbackUsed: params.fallbackUsed,
+  };
+}
+
+/** Fetch a single decision by ID. */
+export function getDecisionById(id: string): NotificationDecisionRow | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationDecisions)
+    .where(eq(notificationDecisions.id, id))
+    .get();
+  if (!row) return null;
+  return rowToDecision(row);
+}
+
+/** Fetch a decision by its parent event ID. */
+export function getDecisionByEventId(eventId: string): NotificationDecisionRow | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationDecisions)
+    .where(eq(notificationDecisions.notificationEventId, eventId))
+    .get();
+  if (!row) return null;
+  return rowToDecision(row);
+}
+
+export interface ListDecisionsFilters {
+  shouldNotify?: boolean;
+  limit?: number;
+}
+
+/** List decisions for an assistant with optional filters. */
+export function listDecisions(
+  assistantId: string,
+  filters?: ListDecisionsFilters,
+): NotificationDecisionRow[] {
+  const db = getDb();
+
+  // Join through notificationEvents to filter by assistantId
+  const conditions = [eq(notificationEvents.assistantId, assistantId)];
+
+  if (filters?.shouldNotify !== undefined) {
+    conditions.push(eq(notificationDecisions.shouldNotify, filters.shouldNotify ? 1 : 0));
+  }
+
+  const limit = filters?.limit ?? 50;
+
+  const rows = db
+    .select({
+      id: notificationDecisions.id,
+      notificationEventId: notificationDecisions.notificationEventId,
+      shouldNotify: notificationDecisions.shouldNotify,
+      selectedChannels: notificationDecisions.selectedChannels,
+      reasoningSummary: notificationDecisions.reasoningSummary,
+      confidence: notificationDecisions.confidence,
+      fallbackUsed: notificationDecisions.fallbackUsed,
+      promptVersion: notificationDecisions.promptVersion,
+      validationResults: notificationDecisions.validationResults,
+      createdAt: notificationDecisions.createdAt,
+    })
+    .from(notificationDecisions)
+    .innerJoin(notificationEvents, eq(notificationDecisions.notificationEventId, notificationEvents.id))
+    .where(and(...conditions))
+    .orderBy(desc(notificationDecisions.createdAt))
+    .limit(limit)
+    .all();
+
+  return rows.map((row) => ({
+    id: row.id,
+    notificationEventId: row.notificationEventId,
+    shouldNotify: row.shouldNotify === 1,
+    selectedChannels: row.selectedChannels,
+    reasoningSummary: row.reasoningSummary,
+    confidence: row.confidence,
+    fallbackUsed: row.fallbackUsed === 1,
+    promptVersion: row.promptVersion,
+    validationResults: row.validationResults,
+    createdAt: row.createdAt,
+  }));
+}

package/src/notifications/deliveries-store.ts

@@ -0,0 +1,130 @@
+/**
+ * Delivery audit records for notifications.
+ *
+ * Each row represents a single attempt to deliver a notification decision
+ * to a specific channel and destination. Multiple attempts for the same
+ * (decision, channel, destination) are tracked via the `attempt` counter.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { notificationDeliveries } from '../memory/schema.js';
+import type { NotificationChannel, NotificationDeliveryStatus } from './types.js';
+
+export interface NotificationDeliveryRow {
+  id: string;
+  notificationDecisionId: string;
+  assistantId: string;
+  channel: string;
+  destination: string;
+  status: string;
+  attempt: number;
+  renderedTitle: string | null;
+  renderedBody: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+  sentAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+function rowToDelivery(row: typeof notificationDeliveries.$inferSelect): NotificationDeliveryRow {
+  return {
+    id: row.id,
+    notificationDecisionId: row.notificationDecisionId,
+    assistantId: row.assistantId,
+    channel: row.channel,
+    destination: row.destination,
+    status: row.status,
+    attempt: row.attempt,
+    renderedTitle: row.renderedTitle,
+    renderedBody: row.renderedBody,
+    errorCode: row.errorCode,
+    errorMessage: row.errorMessage,
+    sentAt: row.sentAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export interface CreateDeliveryParams {
+  id: string;
+  notificationDecisionId: string;
+  assistantId: string;
+  channel: NotificationChannel;
+  destination: string;
+  status: NotificationDeliveryStatus;
+  attempt: number;
+  renderedTitle?: string;
+  renderedBody?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  sentAt?: number;
+}
+
+/** Create a new delivery audit record. */
+export function createDelivery(params: CreateDeliveryParams): NotificationDeliveryRow {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = {
+    id: params.id,
+    notificationDecisionId: params.notificationDecisionId,
+    assistantId: params.assistantId,
+    channel: params.channel,
+    destination: params.destination,
+    status: params.status,
+    attempt: params.attempt,
+    renderedTitle: params.renderedTitle ?? null,
+    renderedBody: params.renderedBody ?? null,
+    errorCode: params.errorCode ?? null,
+    errorMessage: params.errorMessage ?? null,
+    sentAt: params.sentAt ?? null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(notificationDeliveries).values(row).run();
+
+  return row;
+}
+
+/** Update the status of an existing delivery record. */
+export function updateDeliveryStatus(
+  id: string,
+  status: NotificationDeliveryStatus,
+  error?: { code?: string; message?: string },
+): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const updates: Record<string, unknown> = { status, updatedAt: now };
+  if (status === 'sent') {
+    updates.sentAt = now;
+  }
+  if (error?.code) {
+    updates.errorCode = error.code;
+  }
+  if (error?.message) {
+    updates.errorMessage = error.message;
+  }
+
+  const result = db
+    .update(notificationDeliveries)
+    .set(updates)
+    .where(eq(notificationDeliveries.id, id))
+    .run() as unknown as { changes?: number };
+
+  return (result.changes ?? 0) > 0;
+}
+
+/** List all delivery records for a given notification decision. */
+export function listDeliveries(decisionId: string): NotificationDeliveryRow[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(notificationDeliveries)
+    .where(eq(notificationDeliveries.notificationDecisionId, decisionId))
+    .all();
+  return rows.map(rowToDelivery);
+}

package/src/notifications/destination-resolver.ts

@@ -0,0 +1,54 @@
+/**
+ * Resolves per-channel destination endpoints for notification delivery.
+ *
+ * - macOS: no external endpoint needed — delivery goes through the IPC
+ *   broadcast mechanism to connected desktop clients.
+ * - Telegram: requires a chat ID sourced from the guardian binding for the
+ *   assistant.
+ */
+
+import { getActiveBinding } from '../memory/channel-guardian-store.js';
+import type { NotificationChannel, ChannelDestination } from './types.js';
+
+/**
+ * Resolve destination information for each requested channel.
+ *
+ * Returns a map keyed by channel name. Channels that cannot be resolved
+ * (e.g. no Telegram binding configured) are omitted from the result.
+ */
+export function resolveDestinations(
+  assistantId: string,
+  channels: NotificationChannel[],
+): Map<NotificationChannel, ChannelDestination> {
+  const result = new Map<NotificationChannel, ChannelDestination>();
+
+  for (const channel of channels) {
+    switch (channel) {
+      case 'macos': {
+        // macOS delivery is local IPC — no external endpoint required.
+        result.set('macos', { channel: 'macos' });
+        break;
+      }
+      case 'telegram': {
+        const binding = getActiveBinding(assistantId, 'telegram');
+        if (binding) {
+          result.set('telegram', {
+            channel: 'telegram',
+            endpoint: binding.guardianDeliveryChatId,
+            metadata: {
+              externalUserId: binding.guardianExternalUserId,
+            },
+          });
+        }
+        // If no binding exists, skip — the channel is not configured.
+        break;
+      }
+      default: {
+        // Unknown channel — skip silently.
+        break;
+      }
+    }
+  }
+
+  return result;
+}

package/src/notifications/deterministic-checks.ts

@@ -0,0 +1,187 @@
+/**
+ * Deterministic pre-send gate checks for notification decisions.
+ *
+ * These checks run after the decision engine produces a NotificationDecision
+ * and before the broadcaster dispatches. They enforce hard invariants that
+ * the LLM cannot override: channel availability, source-active suppression,
+ * deduplication, and schema validity.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { notificationEvents } from '../memory/schema.js';
+import { getLogger } from '../util/logger.js';
+import type { NotificationSignal } from './signal.js';
+import type { NotificationChannel, NotificationDecision } from './types.js';
+
+const log = getLogger('notification-deterministic-checks');
+
+export interface CheckResult {
+  passed: boolean;
+  reason?: string;
+}
+
+export interface DeterministicCheckContext {
+  /** Channels that are currently connected and available for delivery. */
+  connectedChannels: NotificationChannel[];
+  /** Dedupe window in milliseconds. Events with the same dedupeKey within this window are suppressed. */
+  dedupeWindowMs?: number;
+}
+
+const DEFAULT_DEDUPE_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Run all deterministic pre-send checks against a decision.
+ * Returns passed=false if any check fails, with a reason describing
+ * which check blocked the notification.
+ */
+export async function runDeterministicChecks(
+  signal: NotificationSignal,
+  decision: NotificationDecision,
+  context: DeterministicCheckContext,
+): Promise<CheckResult> {
+  // Check 1: Decision schema validity (fail-closed)
+  const schemaCheck = checkDecisionSchema(decision);
+  if (!schemaCheck.passed) {
+    log.info({ signalId: signal.signalId, reason: schemaCheck.reason }, 'Deterministic check failed: schema');
+    return schemaCheck;
+  }
+
+  // Check 2: Source-active suppression
+  const sourceActiveCheck = checkSourceActiveSuppression(signal);
+  if (!sourceActiveCheck.passed) {
+    log.info({ signalId: signal.signalId, reason: sourceActiveCheck.reason }, 'Deterministic check failed: source active');
+    return sourceActiveCheck;
+  }
+
+  // Check 3: Channel availability
+  const channelCheck = checkChannelAvailability(decision, context.connectedChannels);
+  if (!channelCheck.passed) {
+    log.info({ signalId: signal.signalId, reason: channelCheck.reason }, 'Deterministic check failed: channel availability');
+    return channelCheck;
+  }
+
+  // Check 4: Dedupe
+  const dedupeCheck = checkDedupe(signal, decision, context.dedupeWindowMs ?? DEFAULT_DEDUPE_WINDOW_MS);
+  if (!dedupeCheck.passed) {
+    log.info({ signalId: signal.signalId, reason: dedupeCheck.reason }, 'Deterministic check failed: dedupe');
+    return dedupeCheck;
+  }
+
+  return { passed: true };
+}
+
+// ── Individual checks ──────────────────────────────────────────────────
+
+/**
+ * Fail-closed schema validation. If the decision is missing required
+ * fields or has invalid types, block the notification.
+ */
+function checkDecisionSchema(decision: NotificationDecision): CheckResult {
+  if (typeof decision.shouldNotify !== 'boolean') {
+    return { passed: false, reason: 'Invalid decision: shouldNotify is not a boolean' };
+  }
+  if (!Array.isArray(decision.selectedChannels)) {
+    return { passed: false, reason: 'Invalid decision: selectedChannels is not an array' };
+  }
+  if (typeof decision.reasoningSummary !== 'string') {
+    return { passed: false, reason: 'Invalid decision: reasoningSummary is not a string' };
+  }
+  if (typeof decision.dedupeKey !== 'string' || decision.dedupeKey.length === 0) {
+    return { passed: false, reason: 'Invalid decision: dedupeKey is missing or empty' };
+  }
+  if (typeof decision.confidence !== 'number' || !Number.isFinite(decision.confidence)) {
+    return { passed: false, reason: 'Invalid decision: confidence is not a finite number' };
+  }
+  return { passed: true };
+}
+
+/**
+ * If the user is already looking at the source context (visibleInSourceNow),
+ * suppress the notification to avoid redundant alerts.
+ */
+function checkSourceActiveSuppression(signal: NotificationSignal): CheckResult {
+  if (signal.attentionHints.visibleInSourceNow) {
+    return {
+      passed: false,
+      reason: 'Source-active suppression: user is already viewing the source context',
+    };
+  }
+  return { passed: true };
+}
+
+/**
+ * Verify that at least one of the selected channels is actually
+ * connected and available for delivery.
+ */
+function checkChannelAvailability(
+  decision: NotificationDecision,
+  connectedChannels: NotificationChannel[],
+): CheckResult {
+  if (!decision.shouldNotify) {
+    // Not notifying — channel availability is irrelevant
+    return { passed: true };
+  }
+
+  const connectedSet = new Set(connectedChannels);
+  const availableSelected = decision.selectedChannels.filter((ch) => connectedSet.has(ch));
+
+  if (availableSelected.length === 0) {
+    return {
+      passed: false,
+      reason: `Channel availability: none of the selected channels (${decision.selectedChannels.join(', ')}) are connected`,
+    };
+  }
+
+  return { passed: true };
+}
+
+/**
+ * Check if a signal with the same dedupeKey was already processed
+ * within the dedupe window. Uses the events-store table directly.
+ */
+function checkDedupe(
+  signal: NotificationSignal,
+  decision: NotificationDecision,
+  windowMs: number,
+): CheckResult {
+  if (!decision.dedupeKey) {
+    return { passed: true };
+  }
+
+  try {
+    const db = getDb();
+    const cutoff = Date.now() - windowMs;
+
+    const existing = db
+      .select({ id: notificationEvents.id, createdAt: notificationEvents.createdAt })
+      .from(notificationEvents)
+      .where(
+        and(
+          eq(notificationEvents.assistantId, signal.assistantId),
+          eq(notificationEvents.dedupeKey, decision.dedupeKey),
+        ),
+      )
+      .all();
+
+    // Filter by created_at > cutoff (the events store already checked
+    // dedupe on insert, but this catches cases where the engine is
+    // re-evaluating a signal that was previously stored).
+    for (const row of existing) {
+      // The current signal's own event row should not count as a duplicate
+      if (row.id === signal.signalId) continue;
+      // Only consider events within the dedupe window
+      if (row.createdAt < cutoff) continue;
+      // If any other event with the same dedupeKey exists within the window, suppress
+      return {
+        passed: false,
+        reason: `Dedupe: signal with dedupeKey "${decision.dedupeKey}" was already processed`,
+      };
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.warn({ err: errMsg }, 'Dedupe check failed, allowing notification through');
+  }
+
+  return { passed: true };
+}