@vellumai/assistant 0.3.8 → 0.3.9

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

package/src/notifications/preferences-store.ts

@@ -0,0 +1,142 @@
+/**
+ * CRUD operations for notification preferences.
+ *
+ * Each row stores a natural-language notification preference expressed by
+ * the user (e.g. "Use Telegram for urgent alerts"), along with structured
+ * conditions for when the preference applies and a priority for conflict
+ * resolution.
+ */
+
+import { and, desc, eq } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import { getDb } from '../memory/db.js';
+import { notificationPreferences } from '../memory/schema.js';
+
+// ── Row type ────────────────────────────────────────────────────────────
+
+export interface NotificationPreferenceRow {
+  id: string;
+  assistantId: string;
+  preferenceText: string;
+  appliesWhenJson: string; // serialised JSON
+  priority: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+function rowToPreference(row: typeof notificationPreferences.$inferSelect): NotificationPreferenceRow {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    preferenceText: row.preferenceText,
+    appliesWhenJson: row.appliesWhenJson,
+    priority: row.priority,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+// ── Structured conditions type ──────────────────────────────────────────
+
+export interface AppliesWhenConditions {
+  timeRange?: { after?: string; before?: string }; // e.g. "22:00", "06:00"
+  channels?: string[];        // e.g. ["telegram", "macos"]
+  urgencyLevels?: string[];   // e.g. ["high", "critical"]
+  contexts?: string[];        // e.g. ["work_calls", "meetings"]
+  [key: string]: unknown;
+}
+
+// ── Create ──────────────────────────────────────────────────────────────
+
+export interface CreatePreferenceParams {
+  assistantId: string;
+  preferenceText: string;
+  appliesWhen?: AppliesWhenConditions;
+  priority?: number;
+}
+
+export function createPreference(params: CreatePreferenceParams): NotificationPreferenceRow {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = {
+    id: uuid(),
+    assistantId: params.assistantId,
+    preferenceText: params.preferenceText,
+    appliesWhenJson: JSON.stringify(params.appliesWhen ?? {}),
+    priority: params.priority ?? 0,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(notificationPreferences).values(row).run();
+
+  return row;
+}
+
+// ── List ────────────────────────────────────────────────────────────────
+
+export function listPreferences(assistantId: string): NotificationPreferenceRow[] {
+  const db = getDb();
+
+  const rows = db
+    .select()
+    .from(notificationPreferences)
+    .where(eq(notificationPreferences.assistantId, assistantId))
+    .orderBy(desc(notificationPreferences.priority))
+    .all();
+
+  return rows.map(rowToPreference);
+}
+
+// ── Update ──────────────────────────────────────────────────────────────
+
+export interface UpdatePreferenceParams {
+  preferenceText?: string;
+  appliesWhen?: AppliesWhenConditions;
+  priority?: number;
+}
+
+export function updatePreference(id: string, params: UpdatePreferenceParams): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const updates: Record<string, unknown> = { updatedAt: now };
+  if (params.preferenceText !== undefined) updates.preferenceText = params.preferenceText;
+  if (params.appliesWhen !== undefined) updates.appliesWhenJson = JSON.stringify(params.appliesWhen);
+  if (params.priority !== undefined) updates.priority = params.priority;
+
+  const result = db
+    .update(notificationPreferences)
+    .set(updates)
+    .where(eq(notificationPreferences.id, id))
+    .run() as unknown as { changes?: number };
+
+  return (result.changes ?? 0) > 0;
+}
+
+// ── Delete ──────────────────────────────────────────────────────────────
+
+export function deletePreference(id: string): boolean {
+  const db = getDb();
+
+  const result = db
+    .delete(notificationPreferences)
+    .where(eq(notificationPreferences.id, id))
+    .run() as unknown as { changes?: number };
+
+  return (result.changes ?? 0) > 0;
+}
+
+// ── Get by ID ───────────────────────────────────────────────────────────
+
+export function getPreferenceById(id: string): NotificationPreferenceRow | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationPreferences)
+    .where(eq(notificationPreferences.id, id))
+    .get();
+  if (!row) return null;
+  return rowToPreference(row);
+}

package/src/notifications/runtime-dispatch.ts

@@ -0,0 +1,100 @@
+/**
+ * In-loop dispatch helper that wires the decision engine output to the
+ * broadcaster/adapters for end-to-end signal → decision → dispatch → delivery.
+ *
+ * Not a standalone service — called inline from the notification processing
+ * loop after the decision engine and deterministic checks have run.
+ */
+
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import type { NotificationBroadcaster } from './broadcaster.js';
+import type { NotificationSignal } from './signal.js';
+import type { NotificationDecision, NotificationDeliveryResult } from './types.js';
+
+const log = getLogger('notification-dispatch');
+
+export interface DispatchResult {
+  dispatched: boolean;
+  reason: string;
+  deliveryResults: NotificationDeliveryResult[];
+}
+
+/**
+ * Dispatch a notification decision through the broadcaster.
+ *
+ * Handles three early-exit cases before delegating to the broadcaster:
+ * 1. shouldNotify === false — the decision says not to notify
+ * 2. Shadow mode — decisions are logged but not actually dispatched
+ * 3. No selected channels — nothing to dispatch
+ */
+export async function dispatchDecision(
+  signal: NotificationSignal,
+  decision: NotificationDecision,
+  broadcaster: NotificationBroadcaster,
+): Promise<DispatchResult> {
+  // No-op when the decision engine says not to notify
+  if (!decision.shouldNotify) {
+    log.info(
+      { signalId: signal.signalId, reason: decision.reasoningSummary },
+      'Decision: do not notify',
+    );
+    return {
+      dispatched: false,
+      reason: 'Decision: shouldNotify=false',
+      deliveryResults: [],
+    };
+  }
+
+  // Shadow mode: log the decision but skip actual delivery
+  const config = getConfig();
+  if (config.notifications.shadowMode) {
+    log.info(
+      {
+        signalId: signal.signalId,
+        channels: decision.selectedChannels,
+        confidence: decision.confidence,
+        fallbackUsed: decision.fallbackUsed,
+      },
+      'Shadow mode: skipping dispatch (decision logged only)',
+    );
+    return {
+      dispatched: false,
+      reason: 'Shadow mode enabled — dispatch skipped',
+      deliveryResults: [],
+    };
+  }
+
+  // Guard against empty channel list
+  if (decision.selectedChannels.length === 0) {
+    log.info(
+      { signalId: signal.signalId },
+      'No channels selected in decision — nothing to dispatch',
+    );
+    return {
+      dispatched: false,
+      reason: 'No channels selected',
+      deliveryResults: [],
+    };
+  }
+
+  // Dispatch through the broadcaster
+  const deliveryResults = await broadcaster.broadcastDecision(signal, decision);
+
+  const sentCount = deliveryResults.filter((r) => r.status === 'sent').length;
+  log.info(
+    {
+      signalId: signal.signalId,
+      channels: decision.selectedChannels,
+      sentCount,
+      totalAttempted: deliveryResults.length,
+    },
+    'Dispatch complete',
+  );
+
+  return {
+    dispatched: true,
+    reason: `Dispatched to ${sentCount}/${deliveryResults.length} channels`,
+    deliveryResults,
+  };
+}

package/src/notifications/signal.ts

@@ -0,0 +1,24 @@
+/**
+ * NotificationSignal -- the flexible input from producers.
+ * Uses free-form event names and structured attention hints that let the
+ * decision engine route contextually.
+ */
+
+export interface AttentionHints {
+  requiresAction: boolean;
+  urgency: 'low' | 'medium' | 'high';
+  deadlineAt?: number; // epoch ms
+  isAsyncBackground: boolean;
+  visibleInSourceNow: boolean;
+}
+
+export interface NotificationSignal {
+  signalId: string;
+  assistantId: string;
+  createdAt: number; // epoch ms
+  sourceChannel: string; // free-form: 'macos', 'telegram', 'voice', 'scheduler', etc.
+  sourceSessionId: string;
+  sourceEventName: string; // free-form: 'reminder_fired', 'schedule_complete', 'guardian_question', etc.
+  contextPayload: Record<string, unknown>;
+  attentionHints: AttentionHints;
+}

package/src/notifications/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Core domain types for the unified notification system.
+ *
+ * Defines the channel-adapter interfaces that the broadcaster and adapters
+ * depend on, plus the decision engine output contract.
+ */
+
+export type NotificationChannel = 'macos' | 'telegram';
+
+export type NotificationDeliveryStatus = 'pending' | 'sent' | 'failed' | 'skipped';
+
+/** Result of attempting to deliver a notification to a single channel. */
+export interface NotificationDeliveryResult {
+  channel: NotificationChannel;
+  destination: string;
+  status: NotificationDeliveryStatus;
+  errorCode?: string;
+  errorMessage?: string;
+  sentAt?: number;
+}
+
+// -- Channel adapter interfaces -----------------------------------------------
+
+/** Result returned by a channel adapter after attempting to send. */
+export interface DeliveryResult {
+  success: boolean;
+  error?: string;
+}
+
+/** Resolved destination for a specific channel. */
+export interface ChannelDestination {
+  channel: NotificationChannel;
+  endpoint?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Delivery payload assembled from the decision engine's rendered copy
+ * plus contextual fields the adapters need for formatting and routing.
+ */
+export interface ChannelDeliveryPayload {
+  sourceEventName: string;
+  copy: RenderedChannelCopy;
+  deepLinkTarget?: Record<string, unknown>;
+}
+
+/** Interface that each channel adapter must implement. */
+export interface ChannelAdapter {
+  channel: NotificationChannel;
+  send(payload: ChannelDeliveryPayload, destination: ChannelDestination): Promise<DeliveryResult>;
+}
+
+// -- Decision engine output ---------------------------------------------------
+
+/** Rendered notification copy for a single channel. */
+export interface RenderedChannelCopy {
+  title: string;
+  body: string;
+  threadTitle?: string;
+  threadSeedMessage?: string;
+}
+
+/** Output produced by the notification decision engine for a given signal. */
+export interface NotificationDecision {
+  shouldNotify: boolean;
+  selectedChannels: NotificationChannel[];
+  reasoningSummary: string;
+  renderedCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>>;
+  deepLinkTarget?: Record<string, unknown>;
+  dedupeKey: string;
+  confidence: number;
+  fallbackUsed: boolean;
+  /** UUID of the persisted decision row (set after persistence in the decision engine). */
+  persistedDecisionId?: string;
+}