@vellumai/assistant 0.3.8 → 0.3.9

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 };
+}

package/src/notifications/emit-signal.ts

@@ -0,0 +1,191 @@
+/**
+ * Single entry point for all notification producers.
+ *
+ * emitNotificationSignal() creates a NotificationSignal, persists the event,
+ * and runs it through the decision engine + deterministic checks + dispatch
+ * pipeline.
+ *
+ * Designed for fire-and-forget usage: errors are logged but never propagated
+ * to the caller. The returned promise resolves even on failure.
+ */
+
+import { v4 as uuid } from 'uuid';
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import { getActiveBinding } from '../memory/channel-guardian-store.js';
+import { createEvent, updateEventDedupeKey } from './events-store.js';
+import { evaluateSignal } from './decision-engine.js';
+import { runDeterministicChecks, type DeterministicCheckContext } from './deterministic-checks.js';
+import { dispatchDecision } from './runtime-dispatch.js';
+import { NotificationBroadcaster } from './broadcaster.js';
+import { MacOSAdapter, type BroadcastFn } from './adapters/macos.js';
+import { TelegramAdapter } from './adapters/telegram.js';
+import type { NotificationSignal, AttentionHints } from './signal.js';
+import type { NotificationChannel } from './types.js';
+
+const log = getLogger('emit-signal');
+
+// ── Broadcaster singleton ──────────────────────────────────────────────
+
+let broadcasterInstance: NotificationBroadcaster | null = null;
+let registeredBroadcastFn: BroadcastFn | null = null;
+
+/**
+ * Register the IPC broadcast function so the macOS adapter can deliver
+ * notifications through the daemon's IPC socket. Must be called once
+ * during daemon startup (before any signals are emitted).
+ */
+export function registerBroadcastFn(fn: BroadcastFn): void {
+  registeredBroadcastFn = fn;
+  // Reset the broadcaster so it picks up the new broadcast function
+  broadcasterInstance = null;
+}
+
+function getBroadcaster(): NotificationBroadcaster {
+  if (!broadcasterInstance) {
+    const adapters = [
+      new TelegramAdapter(),
+    ];
+    if (registeredBroadcastFn) {
+      adapters.unshift(new MacOSAdapter(registeredBroadcastFn));
+    }
+    broadcasterInstance = new NotificationBroadcaster(adapters);
+  }
+  return broadcasterInstance;
+}
+
+// ── Connected channels resolution ──────────────────────────────────────
+
+function getConnectedChannels(assistantId: string): NotificationChannel[] {
+  // macOS is always considered connected (IPC socket is always available
+  // when the daemon is running).
+  const channels: NotificationChannel[] = ['macos'];
+  // Only report Telegram as connected when there is an active guardian
+  // binding for this assistant. Without a binding, the destination
+  // resolver will fail to resolve a chat ID and dispatch will silently
+  // drop the message — which is worse than the decision engine knowing
+  // up front that the channel is unavailable.
+  const telegramBinding = getActiveBinding(assistantId, 'telegram');
+  if (telegramBinding) {
+    channels.push('telegram');
+  }
+  return channels;
+}
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+export interface EmitSignalParams {
+  /** Free-form event name, e.g. 'reminder.fired', 'schedule.complete'. */
+  sourceEventName: string;
+  /** Source channel that produced the event. */
+  sourceChannel: string;
+  /** Session or conversation ID from the source context. */
+  sourceSessionId: string;
+  /** Logical assistant ID (defaults to 'self'). */
+  assistantId?: string;
+  /** Attention hints for the decision engine. */
+  attentionHints: AttentionHints;
+  /** Arbitrary context payload passed to the decision engine. */
+  contextPayload?: Record<string, unknown>;
+  /** Optional deduplication key. */
+  dedupeKey?: string;
+}
+
+/**
+ * Emit a notification signal through the full pipeline:
+ * createEvent -> evaluateSignal -> runDeterministicChecks -> dispatchDecision.
+ *
+ * Fire-and-forget safe: all errors are caught and logged. The caller
+ * should not await this in critical paths unless it needs the result.
+ */
+export async function emitNotificationSignal(params: EmitSignalParams): Promise<void> {
+  const config = getConfig();
+  if (!config.notifications?.enabled) {
+    log.debug({ sourceEventName: params.sourceEventName }, 'Notification system disabled, skipping signal');
+    return;
+  }
+
+  const signalId = uuid();
+  const assistantId = params.assistantId ?? 'self';
+
+  const signal: NotificationSignal = {
+    signalId,
+    assistantId,
+    createdAt: Date.now(),
+    sourceChannel: params.sourceChannel,
+    sourceSessionId: params.sourceSessionId,
+    sourceEventName: params.sourceEventName,
+    contextPayload: params.contextPayload ?? {},
+    attentionHints: params.attentionHints,
+  };
+
+  try {
+    // Step 1: Persist the event
+    const eventRow = createEvent({
+      id: signalId,
+      assistantId,
+      sourceEventName: params.sourceEventName,
+      sourceChannel: params.sourceChannel,
+      sourceSessionId: params.sourceSessionId,
+      attentionHints: params.attentionHints,
+      payload: params.contextPayload ?? {},
+      dedupeKey: params.dedupeKey,
+    });
+
+    if (!eventRow) {
+      log.info({ signalId, dedupeKey: params.dedupeKey }, 'Signal deduplicated at event store level');
+      return;
+    }
+
+    // Step 2: Evaluate the signal through the decision engine
+    const connectedChannels = getConnectedChannels(assistantId);
+    const decision = await evaluateSignal(signal, connectedChannels);
+
+    // Persist model-generated dedupeKey back to the event row so future
+    // signals can deduplicate against it (the event was created with
+    // only the producer's dedupeKey, which may be null).
+    if (decision.dedupeKey && !params.dedupeKey) {
+      try {
+        updateEventDedupeKey(signalId, decision.dedupeKey);
+      } catch (err) {
+        log.warn({ err, signalId }, 'Failed to persist decision dedupeKey to event row');
+      }
+    }
+
+    // Step 3: Run deterministic pre-send checks
+    if (decision.shouldNotify) {
+      const checkContext: DeterministicCheckContext = {
+        connectedChannels,
+      };
+      const checkResult = await runDeterministicChecks(signal, decision, checkContext);
+
+      if (!checkResult.passed) {
+        log.info(
+          { signalId, reason: checkResult.reason },
+          'Signal blocked by deterministic checks',
+        );
+        return;
+      }
+    }
+
+    // Step 4: Dispatch through the broadcaster
+    const broadcaster = getBroadcaster();
+    const dispatchResult = await dispatchDecision(signal, decision, broadcaster);
+
+    log.info(
+      {
+        signalId,
+        sourceEventName: params.sourceEventName,
+        dispatched: dispatchResult.dispatched,
+        reason: dispatchResult.reason,
+      },
+      'Signal pipeline complete',
+    );
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.error(
+      { err: errMsg, signalId, sourceEventName: params.sourceEventName },
+      'Signal pipeline failed',
+    );
+  }
+}

package/src/notifications/events-store.ts

@@ -0,0 +1,145 @@
+/**
+ * Notification event persistence.
+ *
+ * Each row represents a single notification signal that was emitted by
+ * the system. The event captures the source event name, attention hints,
+ * and context payload. Decision/delivery records are tracked separately.
+ */
+
+import { and, desc, eq } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { notificationEvents } from '../memory/schema.js';
+import type { AttentionHints } from './signal.js';
+
+export interface NotificationEventRow {
+  id: string;
+  assistantId: string;
+  sourceEventName: string;
+  sourceChannel: string;
+  sourceSessionId: string;
+  attentionHintsJson: string;
+  payloadJson: string;
+  dedupeKey: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+function rowToEvent(row: typeof notificationEvents.$inferSelect): NotificationEventRow {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    sourceEventName: row.sourceEventName,
+    sourceChannel: row.sourceChannel,
+    sourceSessionId: row.sourceSessionId,
+    attentionHintsJson: row.attentionHintsJson,
+    payloadJson: row.payloadJson,
+    dedupeKey: row.dedupeKey,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export interface CreateEventParams {
+  id: string;
+  assistantId: string;
+  sourceEventName: string;
+  sourceChannel: string;
+  sourceSessionId: string;
+  attentionHints: AttentionHints;
+  payload: Record<string, unknown>;
+  dedupeKey?: string;
+}
+
+/** Create a new notification event. Returns null if a duplicate dedupe_key exists. */
+export function createEvent(params: CreateEventParams): NotificationEventRow | null {
+  const db = getDb();
+  const now = Date.now();
+
+  // Normalize empty strings to null so the falsy check below and the DB
+  // unique index stay in agreement (empty string is falsy in JS but would
+  // be stored as a non-null value in SQLite).
+  const normalizedDedupeKey = params.dedupeKey || null;
+
+  // If there's a dedupe key, check for duplicates first
+  if (normalizedDedupeKey) {
+    const existing = db
+      .select()
+      .from(notificationEvents)
+      .where(
+        and(
+          eq(notificationEvents.assistantId, params.assistantId),
+          eq(notificationEvents.dedupeKey, normalizedDedupeKey),
+        ),
+      )
+      .get();
+    if (existing) return null;
+  }
+
+  const row = {
+    id: params.id,
+    assistantId: params.assistantId,
+    sourceEventName: params.sourceEventName,
+    sourceChannel: params.sourceChannel,
+    sourceSessionId: params.sourceSessionId,
+    attentionHintsJson: JSON.stringify(params.attentionHints),
+    payloadJson: JSON.stringify(params.payload),
+    dedupeKey: normalizedDedupeKey,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(notificationEvents).values(row).run();
+
+  return row;
+}
+
+/** Update the dedupeKey on an existing event (e.g. when the decision engine generates one). */
+export function updateEventDedupeKey(eventId: string, dedupeKey: string): void {
+  const db = getDb();
+  db.update(notificationEvents)
+    .set({ dedupeKey, updatedAt: Date.now() })
+    .where(eq(notificationEvents.id, eventId))
+    .run();
+}
+
+/** Get a single notification event by ID. */
+export function getEventById(id: string): NotificationEventRow | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationEvents)
+    .where(eq(notificationEvents.id, id))
+    .get();
+  if (!row) return null;
+  return rowToEvent(row);
+}
+
+export interface ListEventsFilters {
+  sourceEventName?: string;
+  limit?: number;
+}
+
+/** List notification events for an assistant with optional filters. */
+export function listEvents(
+  assistantId: string,
+  filters?: ListEventsFilters,
+): NotificationEventRow[] {
+  const db = getDb();
+  const conditions = [eq(notificationEvents.assistantId, assistantId)];
+
+  if (filters?.sourceEventName) {
+    conditions.push(eq(notificationEvents.sourceEventName, filters.sourceEventName));
+  }
+
+  const limit = filters?.limit ?? 50;
+
+  const rows = db
+    .select()
+    .from(notificationEvents)
+    .where(and(...conditions))
+    .orderBy(desc(notificationEvents.createdAt))
+    .limit(limit)
+    .all();
+
+  return rows.map(rowToEvent);
+}