@vellumai/assistant 0.3.7 → 0.3.9

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

package/src/notifications/preference-extractor.ts

@@ -0,0 +1,223 @@
+/**
+ * Preference extraction pipeline.
+ *
+ * Detects notification-related user statements in conversation messages
+ * and extracts structured preference data. Uses a small/fast model
+ * (haiku) with a focused prompt for lightweight detection + extraction.
+ *
+ * Examples of statements it should detect:
+ * - "Use Telegram for urgent alerts"
+ * - "Don't notify me on desktop during work calls"
+ * - "Weeknights after 10pm: only critical notifications"
+ */
+
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import { getConfiguredProvider, createTimeout, extractToolUse, userMessage } from '../providers/provider-send-message.js';
+import type { AppliesWhenConditions } from './preferences-store.js';
+
+const log = getLogger('notification-preference-extractor');
+
+const EXTRACTION_TIMEOUT_MS = 10_000;
+
+// ── Extraction result ──────────────────────────────────────────────────
+
+export interface ExtractedPreference {
+  preferenceText: string;
+  appliesWhen: AppliesWhenConditions;
+  priority: number;
+}
+
+export interface ExtractionResult {
+  detected: boolean;
+  preferences: ExtractedPreference[];
+}
+
+// ── System prompt ──────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are a notification preference detector. Given a user message from a conversation, determine if it contains any notification preferences or routing instructions.
+
+Notification preferences are statements about HOW, WHEN, or WHERE the user wants to receive notifications. Examples:
+- "Use Telegram for urgent alerts"
+- "Don't notify me on desktop during work calls"
+- "Weeknights after 10pm: only critical notifications"
+- "Send me everything on macOS"
+- "Only bug me for high priority stuff"
+- "Mute notifications between 11pm and 7am"
+- "I prefer Telegram over desktop notifications"
+
+If the message does NOT contain any notification preferences, respond with the tool setting detected=false and an empty preferences array.
+
+If it DOES contain preferences, extract each one as a separate entry with:
+- preferenceText: the natural language preference as stated
+- appliesWhen: structured conditions (timeRange, channels, urgencyLevels, contexts)
+- priority: 0 for general defaults, 1 for specific overrides, 2 for critical/urgent overrides
+
+You MUST respond using the \`extract_notification_preferences\` tool.`;
+
+// ── Tool definition ────────────────────────────────────────────────────
+
+const EXTRACTION_TOOL = {
+  name: 'extract_notification_preferences',
+  description: 'Extract notification preferences from a user message',
+  input_schema: {
+    type: 'object' as const,
+    properties: {
+      detected: {
+        type: 'boolean',
+        description: 'Whether the message contains notification preferences',
+      },
+      preferences: {
+        type: 'array',
+        description: 'Array of extracted preferences (empty if detected=false)',
+        items: {
+          type: 'object',
+          properties: {
+            preferenceText: {
+              type: 'string',
+              description: 'The natural language preference as stated by the user',
+            },
+            appliesWhen: {
+              type: 'object',
+              description: 'Structured conditions for when this preference applies',
+              properties: {
+                timeRange: {
+                  type: 'object',
+                  properties: {
+                    after: { type: 'string', description: 'Start time in HH:MM format' },
+                    before: { type: 'string', description: 'End time in HH:MM format' },
+                  },
+                },
+                channels: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Channels this preference applies to (e.g. telegram, macos)',
+                },
+                urgencyLevels: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Urgency levels this preference applies to (e.g. low, medium, high, critical)',
+                },
+                contexts: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Situational contexts (e.g. work_calls, meetings, sleeping)',
+                },
+              },
+            },
+            priority: {
+              type: 'number',
+              description: 'Priority for conflict resolution: 0=general default, 1=specific override, 2=critical override',
+            },
+          },
+          required: ['preferenceText', 'appliesWhen', 'priority'],
+        },
+      },
+    },
+    required: ['detected', 'preferences'],
+  },
+};
+
+// ── Core extraction function ───────────────────────────────────────────
+
+export async function extractPreferences(message: string): Promise<ExtractionResult> {
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    log.debug('No provider available for preference extraction');
+    return { detected: false, preferences: [] };
+  }
+
+  const config = getConfig();
+  const model = config.notifications.decisionModel;
+
+  const { signal, cleanup } = createTimeout(EXTRACTION_TIMEOUT_MS);
+
+  try {
+    const response = await provider.sendMessage(
+      [userMessage(message)],
+      [EXTRACTION_TOOL],
+      SYSTEM_PROMPT,
+      {
+        config: {
+          model,
+          max_tokens: 1024,
+          tool_choice: { type: 'tool' as const, name: 'extract_notification_preferences' },
+        },
+        signal,
+      },
+    );
+    cleanup();
+
+    const toolBlock = extractToolUse(response);
+    if (!toolBlock) {
+      log.debug('No tool_use block in preference extraction response');
+      return { detected: false, preferences: [] };
+    }
+
+    const input = toolBlock.input as Record<string, unknown>;
+    return validateExtractionOutput(input);
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.debug({ err: errMsg }, 'Preference extraction failed');
+    return { detected: false, preferences: [] };
+  } finally {
+    cleanup();
+  }
+}
+
+// ── Validation ─────────────────────────────────────────────────────────
+
+function validateExtractionOutput(input: Record<string, unknown>): ExtractionResult {
+  if (typeof input.detected !== 'boolean') {
+    return { detected: false, preferences: [] };
+  }
+
+  if (!input.detected || !Array.isArray(input.preferences)) {
+    return { detected: false, preferences: [] };
+  }
+
+  const preferences: ExtractedPreference[] = [];
+
+  for (const raw of input.preferences) {
+    if (typeof raw !== 'object' || raw === null) continue;
+    const p = raw as Record<string, unknown>;
+
+    if (typeof p.preferenceText !== 'string' || !p.preferenceText.trim()) continue;
+
+    const appliesWhen: AppliesWhenConditions = {};
+    if (p.appliesWhen && typeof p.appliesWhen === 'object') {
+      const aw = p.appliesWhen as Record<string, unknown>;
+      if (aw.timeRange && typeof aw.timeRange === 'object') {
+        const tr = aw.timeRange as Record<string, unknown>;
+        appliesWhen.timeRange = {
+          after: typeof tr.after === 'string' ? tr.after : undefined,
+          before: typeof tr.before === 'string' ? tr.before : undefined,
+        };
+      }
+      if (Array.isArray(aw.channels)) {
+        appliesWhen.channels = aw.channels.filter((c): c is string => typeof c === 'string');
+      }
+      if (Array.isArray(aw.urgencyLevels)) {
+        appliesWhen.urgencyLevels = aw.urgencyLevels.filter((u): u is string => typeof u === 'string');
+      }
+      if (Array.isArray(aw.contexts)) {
+        appliesWhen.contexts = aw.contexts.filter((c): c is string => typeof c === 'string');
+      }
+    }
+
+    const priority = typeof p.priority === 'number'
+      ? Math.max(0, Math.min(2, Math.round(p.priority)))
+      : 0;
+
+    preferences.push({
+      preferenceText: p.preferenceText.trim(),
+      appliesWhen,
+      priority,
+    });
+  }
+
+  return {
+    detected: preferences.length > 0,
+    preferences,
+  };
+}

package/src/notifications/preference-summary.ts

@@ -0,0 +1,110 @@
+/**
+ * Preference summary retriever.
+ *
+ * Builds a compact "notification preference summary" string for inclusion
+ * in the decision engine's system prompt. Fetches all stored preferences
+ * for an assistant and merges them into a coherent block that the LLM
+ * can interpret when making routing decisions.
+ */
+
+import { getLogger } from '../util/logger.js';
+import { listPreferences } from './preferences-store.js';
+import type { AppliesWhenConditions } from './preferences-store.js';
+
+const log = getLogger('notification-preference-summary');
+
+/**
+ * Build a compact preference summary for inclusion in the decision engine
+ * system prompt. Returns null if no preferences are stored.
+ */
+export function getPreferenceSummary(assistantId: string): string | null {
+  const preferences = listPreferences(assistantId);
+
+  if (preferences.length === 0) {
+    return null;
+  }
+
+  const lines: string[] = [
+    'The user has set the following notification preferences (ordered by priority, highest first):',
+  ];
+
+  for (const pref of preferences) {
+    const safeText = sanitizePreferenceText(pref.preferenceText);
+    const conditionStr = formatConditions(pref.appliesWhenJson);
+    const priorityLabel = pref.priority >= 2 ? 'CRITICAL' : pref.priority === 1 ? 'override' : 'default';
+    const prefix = `[${priorityLabel}]`;
+
+    if (conditionStr) {
+      lines.push(`${prefix} "${safeText}" (when: ${conditionStr})`);
+    } else {
+      lines.push(`${prefix} "${safeText}"`);
+    }
+  }
+
+  log.debug({ count: preferences.length }, 'Built preference summary');
+
+  return lines.join('\n');
+}
+
+// ── Text sanitization ───────────────────────────────────────────────────
+
+/**
+ * Strip XML/HTML-like tags from preference text to prevent prompt injection.
+ * Replaces angle brackets with harmless unicode equivalents so user-authored
+ * text cannot break the `<user-preferences>` framing in the system prompt.
+ */
+function sanitizePreferenceText(text: string): string {
+  return text.replace(/</g, '\uFF1C').replace(/>/g, '\uFF1E');
+}
+
+/**
+ * Safely convert and sanitize a value to a string.
+ * Coerces to string first (if needed) then sanitizes with sanitizePreferenceText.
+ * This ensures all values are sanitized regardless of their original type,
+ * preventing prompt injection via coerced types.
+ */
+function safeString(value: unknown): string {
+  return sanitizePreferenceText(typeof value === 'string' ? value : String(value ?? ''));
+}
+
+// ── Condition formatting ────────────────────────────────────────────────
+
+function formatConditions(appliesWhenJson: string): string {
+  let conditions: AppliesWhenConditions;
+  try {
+    conditions = JSON.parse(appliesWhenJson);
+  } catch {
+    return '';
+  }
+
+  // Skip empty condition objects
+  if (!conditions || typeof conditions !== 'object') return '';
+
+  const parts: string[] = [];
+
+  if (conditions.timeRange) {
+    const after = conditions.timeRange.after ? safeString(conditions.timeRange.after) : '';
+    const before = conditions.timeRange.before ? safeString(conditions.timeRange.before) : '';
+    if (after && before) {
+      parts.push(`${after}-${before}`);
+    } else if (after) {
+      parts.push(`after ${after}`);
+    } else if (before) {
+      parts.push(`before ${before}`);
+    }
+  }
+
+  if (conditions.channels && conditions.channels.length > 0) {
+    parts.push(`channels: ${conditions.channels.map(safeString).join(', ')}`);
+  }
+
+  if (conditions.urgencyLevels && conditions.urgencyLevels.length > 0) {
+    parts.push(`urgency: ${conditions.urgencyLevels.map(safeString).join(', ')}`);
+  }
+
+  if (conditions.contexts && conditions.contexts.length > 0) {
+    parts.push(`context: ${conditions.contexts.map(safeString).join(', ')}`);
+  }
+
+  return parts.join('; ');
+}