@vellumai/assistant 0.3.8 → 0.3.9

package/src/memory/schema.ts

@@ -900,3 +900,62 @@ export const assistantInboxThreadState = sqliteTable('assistant_inbox_thread_sta
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
 });
+
+// ── Notification System ──────────────────────────────────────────────
+
+export const notificationEvents = sqliteTable('notification_events', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull(),
+  sourceEventName: text('source_event_name').notNull(),
+  sourceChannel: text('source_channel').notNull(),
+  sourceSessionId: text('source_session_id').notNull(),
+  attentionHintsJson: text('attention_hints_json').notNull().default('{}'),
+  payloadJson: text('payload_json').notNull().default('{}'),
+  dedupeKey: text('dedupe_key'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const notificationDecisions = sqliteTable('notification_decisions', {
+  id: text('id').primaryKey(),
+  notificationEventId: text('notification_event_id')
+    .notNull()
+    .references(() => notificationEvents.id, { onDelete: 'cascade' }),
+  shouldNotify: integer('should_notify').notNull(),
+  selectedChannels: text('selected_channels').notNull().default('[]'),
+  reasoningSummary: text('reasoning_summary').notNull(),
+  confidence: real('confidence').notNull(),
+  fallbackUsed: integer('fallback_used').notNull().default(0),
+  promptVersion: text('prompt_version'),
+  validationResults: text('validation_results'),
+  createdAt: integer('created_at').notNull(),
+});
+
+export const notificationPreferences = sqliteTable('notification_preferences', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull(),
+  preferenceText: text('preference_text').notNull(),
+  appliesWhenJson: text('applies_when_json').notNull().default('{}'),
+  priority: integer('priority').notNull().default(0),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const notificationDeliveries = sqliteTable('notification_deliveries', {
+  id: text('id').primaryKey(),
+  notificationDecisionId: text('notification_decision_id')
+    .notNull()
+    .references(() => notificationDecisions.id, { onDelete: 'cascade' }),
+  assistantId: text('assistant_id').notNull(),
+  channel: text('channel').notNull(),
+  destination: text('destination').notNull(),
+  status: text('status').notNull().default('pending'),
+  attempt: integer('attempt').notNull().default(1),
+  renderedTitle: text('rendered_title'),
+  renderedBody: text('rendered_body'),
+  errorCode: text('error_code'),
+  errorMessage: text('error_message'),
+  sentAt: integer('sent_at'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});

package/src/notifications/README.md

@@ -0,0 +1,134 @@
+# Notification System
+
+Signal-driven notification architecture where producers emit free-form events and an LLM-backed decision engine determines whether, where, and how to notify the user.
+
+## Lifecycle
+
+```
+Producer → NotificationSignal → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Adapters → Delivery
+                                       ↑
+                               Preference Summary
+```
+
+### 1. Signal
+
+A producer calls `emitNotificationSignal()` with a free-form event name, attention hints (urgency, requiresAction, deadlineAt), and a context payload. The signal is persisted as a `notification_events` row.
+
+### 2. Decision
+
+The decision engine (`decision-engine.ts`) sends the signal to an LLM (configured via `notifications.decisionModel`) along with available channels and the user's preference summary. The LLM responds with a structured decision: whether to notify, which channels, rendered copy per channel, and a deduplication key.
+
+When the LLM is unavailable or returns invalid output, a deterministic fallback fires: high-urgency + requires-action signals notify on all channels; everything else is suppressed.
+
+### 3. Deterministic Checks
+
+Hard invariants that the LLM cannot override (`deterministic-checks.ts`):
+
+- **Schema validity** -- fail-closed if the decision is malformed
+- **Source-active suppression** -- if the user is already viewing the source context, suppress
+- **Channel availability** -- at least one selected channel must be connected
+- **Deduplication** -- same `dedupeKey` within the dedupe window (1 hour default) is suppressed
+
+### 4. Dispatch
+
+`runtime-dispatch.ts` handles three early-exit cases (shouldNotify=false, shadow mode, no channels), then delegates to the broadcaster.
+
+### 5. Broadcast and Delivery
+
+The broadcaster (`broadcaster.ts`) iterates over selected channels, resolves destinations via `destination-resolver.ts`, pulls rendered copy from the decision (falling back to `copy-composer.ts` templates), and dispatches through channel adapters. Each delivery attempt is recorded in `notification_deliveries`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `emit-signal.ts` | Single entry point for producers; orchestrates the full pipeline |
+| `signal.ts` | `NotificationSignal` and `AttentionHints` type definitions |
+| `types.ts` | Channel adapter interfaces, delivery types, decision output contract |
+| `decision-engine.ts` | LLM-based routing with forced tool_choice; deterministic fallback |
+| `deterministic-checks.ts` | Pre-send gate checks (dedupe, source-active, channel availability) |
+| `runtime-dispatch.ts` | Dispatch gating (shadow mode, no-op decisions) |
+| `broadcaster.ts` | Fan-out to channel adapters with delivery audit trail |
+| `copy-composer.ts` | Template-based fallback copy when LLM copy is unavailable |
+| `destination-resolver.ts` | Resolves per-channel endpoints (macOS IPC, Telegram chat ID) |
+| `adapters/macos.ts` | macOS adapter -- broadcasts `notification_intent` via IPC |
+| `adapters/telegram.ts` | Telegram adapter -- POSTs to gateway `/deliver/telegram` |
+| `preference-extractor.ts` | Detects notification preferences in conversation messages |
+| `preference-summary.ts` | Builds preference context string for the decision engine prompt |
+| `preferences-store.ts` | CRUD for `notification_preferences` table |
+| `events-store.ts` | CRUD for `notification_events` table |
+| `decisions-store.ts` | CRUD for `notification_decisions` table |
+| `deliveries-store.ts` | CRUD for `notification_deliveries` table |
+
+## How to Add a New Notification Producer
+
+1. Import `emitNotificationSignal` from `./emit-signal.js`.
+2. Call it with the signal parameters:
+
+```ts
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+
+await emitNotificationSignal({
+  sourceEventName: 'your_event_name',
+  sourceChannel: 'scheduler',       // where the event originated
+  sourceSessionId: sessionId,
+  attentionHints: {
+    requiresAction: true,
+    urgency: 'high',
+    isAsyncBackground: false,
+    visibleInSourceNow: false,
+  },
+  contextPayload: { /* arbitrary data for the decision engine */ },
+});
+```
+
+3. Optionally add a fallback copy template in `copy-composer.ts` keyed by your `sourceEventName`. Without a template, the generic fallback produces a human-readable version of the event name.
+
+The call is fire-and-forget safe -- errors are caught and logged internally.
+
+## Audit Trail
+
+Three SQLite tables form the audit chain:
+
+- **`notification_events`** -- every signal that entered the pipeline, with attention hints and context payload
+- **`notification_decisions`** -- the routing decision for each event (shouldNotify, selectedChannels, reasoning, confidence, whether fallback was used)
+- **`notification_deliveries`** -- per-channel delivery attempts with status (pending/sent/failed/skipped), rendered copy, and error details
+
+Query examples:
+
+```sql
+-- Recent decisions that resulted in notifications
+SELECT e.source_event_name, d.should_notify, d.selected_channels, d.reasoning_summary
+FROM notification_decisions d
+JOIN notification_events e ON d.notification_event_id = e.id
+WHERE d.should_notify = 1
+ORDER BY d.created_at DESC
+LIMIT 20;
+
+-- Failed deliveries
+SELECT d.channel, d.error_message, d.rendered_title
+FROM notification_deliveries d
+WHERE d.status = 'failed'
+ORDER BY d.created_at DESC;
+```
+
+## Conversational Preferences
+
+Users express notification preferences in natural language during conversations (e.g., "Use Telegram for urgent alerts", "Mute notifications after 10pm"). The system:
+
+1. **Detects** preferences via `preference-extractor.ts` -- an LLM call that runs on each user message in `session-process.ts`
+2. **Stores** them in `notification_preferences` with structured conditions (`appliesWhen`: timeRange, channels, urgencyLevels, contexts) and a priority level (0=default, 1=override, 2=critical)
+3. **Summarizes** them at decision time via `preference-summary.ts`, which builds a compact text block injected into the decision engine's system prompt
+
+Preferences are sanitized against prompt injection (angle brackets replaced with harmless unicode equivalents).
+
+## Configuration
+
+All settings live under the `notifications` key in `config.json`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `notifications.enabled` | boolean | `false` | Master switch for the notification pipeline |
+| `notifications.shadowMode` | boolean | `true` | When true, decisions are logged but not dispatched |
+| `notifications.decisionModel` | string | `"claude-haiku-4-5-20251001"` | Model used for both the decision engine and preference extraction |
+
+Shadow mode is useful for validating decision quality before enabling live delivery. The audit trail (events + decisions) is written regardless of shadow mode.

package/src/notifications/adapters/macos.ts

@@ -0,0 +1,55 @@
+/**
+ * macOS channel adapter — delivers notifications to connected desktop
+ * clients via the daemon's IPC broadcast mechanism.
+ *
+ * The adapter broadcasts a `notification_intent` message that the macOS
+ * client can use to display a native notification (e.g. NSUserNotification
+ * or UNUserNotificationCenter).
+ */
+
+import { getLogger } from '../../util/logger.js';
+import type { ServerMessage } from '../../daemon/ipc-contract.js';
+import type {
+  NotificationChannel,
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+} from '../types.js';
+
+const log = getLogger('notif-adapter-macos');
+
+export type BroadcastFn = (msg: ServerMessage) => void;
+
+export class MacOSAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = 'macos';
+
+  private broadcast: BroadcastFn;
+
+  constructor(broadcast: BroadcastFn) {
+    this.broadcast = broadcast;
+  }
+
+  async send(payload: ChannelDeliveryPayload, _destination: ChannelDestination): Promise<DeliveryResult> {
+    try {
+      this.broadcast({
+        type: 'notification_intent',
+        sourceEventName: payload.sourceEventName,
+        title: payload.copy.title,
+        body: payload.copy.body,
+        deepLinkMetadata: payload.deepLinkTarget,
+      } as ServerMessage);
+
+      log.info(
+        { sourceEventName: payload.sourceEventName, title: payload.copy.title },
+        'macOS notification intent broadcast',
+      );
+
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err, sourceEventName: payload.sourceEventName }, 'Failed to broadcast macOS notification intent');
+      return { success: false, error: message };
+    }
+  }
+}

package/src/notifications/adapters/telegram.ts

@@ -0,0 +1,65 @@
+/**
+ * Telegram channel adapter — delivers notifications to Telegram chats
+ * via the gateway's channel-reply endpoint.
+ *
+ * Follows the same delivery pattern used by guardian-dispatch: POST to
+ * the gateway's `/deliver/telegram` endpoint with a chat ID and text
+ * payload. The gateway forwards the message to the Telegram Bot API.
+ */
+
+import { getLogger } from '../../util/logger.js';
+import { getGatewayInternalBaseUrl } from '../../config/env.js';
+import { deliverChannelReply } from '../../runtime/gateway-client.js';
+import { readHttpToken } from '../../util/platform.js';
+import type {
+  NotificationChannel,
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+} from '../types.js';
+
+const log = getLogger('notif-adapter-telegram');
+
+export class TelegramAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = 'telegram';
+
+  async send(payload: ChannelDeliveryPayload, destination: ChannelDestination): Promise<DeliveryResult> {
+    const chatId = destination.endpoint;
+    if (!chatId) {
+      log.warn({ sourceEventName: payload.sourceEventName }, 'Telegram destination has no chat ID — skipping');
+      return { success: false, error: 'No chat ID configured for Telegram destination' };
+    }
+
+    const gatewayBase = getGatewayInternalBaseUrl();
+    const deliverUrl = `${gatewayBase}/deliver/telegram`;
+
+    // Format copy for Telegram as plain text (no parse_mode set on gateway side)
+    let messageText = payload.copy.title + '\n\n' + payload.copy.body;
+    if (payload.copy.threadTitle) {
+      messageText += '\n\nThread: ' + payload.copy.threadTitle;
+    }
+
+    try {
+      await deliverChannelReply(
+        deliverUrl,
+        { chatId, text: messageText },
+        readHttpToken() ?? undefined,
+      );
+
+      log.info(
+        { sourceEventName: payload.sourceEventName, chatId },
+        'Telegram notification delivered',
+      );
+
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, sourceEventName: payload.sourceEventName, chatId },
+        'Failed to deliver Telegram notification',
+      );
+      return { success: false, error: message };
+    }
+  }
+}

package/src/notifications/broadcaster.ts

@@ -0,0 +1,175 @@
+/**
+ * NotificationBroadcaster -- dispatches a notification decision to all
+ * selected channels through their respective adapters.
+ *
+ * For each channel in the decision's selectedChannels:
+ *   1. Resolves the destination via the destination-resolver
+ *   2. Pulls rendered copy from the decision (or falls back to copy-composer)
+ *   3. Dispatches through the channel adapter
+ *   4. Records a delivery audit row in the deliveries-store
+ */
+
+import { v4 as uuid } from 'uuid';
+import { getLogger } from '../util/logger.js';
+import { composeFallbackCopy } from './copy-composer.js';
+import { resolveDestinations } from './destination-resolver.js';
+import { createDelivery, updateDeliveryStatus } from './deliveries-store.js';
+import type { NotificationSignal } from './signal.js';
+import type {
+  NotificationChannel,
+  NotificationDecision,
+  NotificationDeliveryResult,
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  RenderedChannelCopy,
+} from './types.js';
+
+const log = getLogger('notif-broadcaster');
+
+export class NotificationBroadcaster {
+  private adapters: Map<NotificationChannel, ChannelAdapter>;
+
+  constructor(adapters: ChannelAdapter[]) {
+    this.adapters = new Map();
+    for (const adapter of adapters) {
+      this.adapters.set(adapter.channel, adapter);
+    }
+  }
+
+  /**
+   * Broadcast a notification decision to all selected channels.
+   *
+   * The decision carries rendered copy per channel. When the decision was
+   * produced by the fallback path (fallbackUsed === true) and is missing
+   * copy for a channel, the copy-composer generates deterministic fallback copy.
+   *
+   * Returns an array of delivery results -- one per channel attempted.
+   */
+  async broadcastDecision(
+    signal: NotificationSignal,
+    decision: NotificationDecision,
+  ): Promise<NotificationDeliveryResult[]> {
+    const destinations = resolveDestinations(signal.assistantId, decision.selectedChannels);
+
+    // Pre-compute fallback copy in case any channel is missing rendered copy
+    let fallbackCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> | null = null;
+
+    const results: NotificationDeliveryResult[] = [];
+
+    for (const channel of decision.selectedChannels) {
+      const adapter = this.adapters.get(channel);
+      if (!adapter) {
+        log.warn({ channel, signalId: signal.signalId }, 'No adapter registered for channel -- skipping');
+        results.push({
+          channel,
+          destination: '',
+          status: 'skipped',
+          errorMessage: `No adapter for channel: ${channel}`,
+        });
+        continue;
+      }
+
+      const destination = destinations.get(channel);
+      if (!destination) {
+        log.warn({ channel, signalId: signal.signalId }, 'Could not resolve destination -- skipping');
+        results.push({
+          channel,
+          destination: '',
+          status: 'skipped',
+          errorMessage: `Destination not resolved for channel: ${channel}`,
+        });
+        continue;
+      }
+
+      // Pull rendered copy from the decision; fall back to copy-composer if missing
+      let copy = decision.renderedCopy[channel];
+      if (!copy) {
+        if (!fallbackCopy) {
+          fallbackCopy = composeFallbackCopy(signal, decision.selectedChannels);
+        }
+        copy = fallbackCopy[channel] ?? { title: 'Notification', body: signal.sourceEventName };
+      }
+
+      const payload: ChannelDeliveryPayload = {
+        sourceEventName: signal.sourceEventName,
+        copy,
+        deepLinkTarget: decision.deepLinkTarget,
+      };
+
+      const deliveryId = uuid();
+      const destinationLabel = destination.endpoint ?? channel;
+
+      // Only create a delivery audit record when we have a persisted decision ID
+      // for the FK. If decision persistence failed (persistedDecisionId is
+      // undefined), we still dispatch via the adapter but skip the delivery
+      // record — using dedupeKey would violate the FK constraint.
+      const persistedDecisionId = decision.persistedDecisionId;
+      const hasPersistedDecision = typeof persistedDecisionId === 'string';
+
+      try {
+        if (hasPersistedDecision) {
+          createDelivery({
+            id: deliveryId,
+            notificationDecisionId: persistedDecisionId,
+            assistantId: signal.assistantId,
+            channel,
+            destination: destinationLabel,
+            status: 'pending',
+            attempt: 1,
+            renderedTitle: copy.title,
+            renderedBody: copy.body,
+          });
+        } else {
+          log.warn(
+            { channel, signalId: signal.signalId },
+            'No persisted decision ID -- skipping delivery record creation',
+          );
+        }
+
+        const adapterResult = await adapter.send(payload, destination);
+
+        if (adapterResult.success) {
+          if (hasPersistedDecision) {
+            updateDeliveryStatus(deliveryId, 'sent');
+          }
+          results.push({
+            channel,
+            destination: destinationLabel,
+            status: 'sent',
+            sentAt: Date.now(),
+          });
+        } else {
+          if (hasPersistedDecision) {
+            updateDeliveryStatus(deliveryId, 'failed', { message: adapterResult.error });
+          }
+          results.push({
+            channel,
+            destination: destinationLabel,
+            status: 'failed',
+            errorMessage: adapterResult.error,
+          });
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        log.error({ err, channel, signalId: signal.signalId }, 'Unexpected error during channel delivery');
+
+        if (hasPersistedDecision) {
+          try {
+            updateDeliveryStatus(deliveryId, 'failed', { message: errorMessage });
+          } catch {
+            // Swallow -- the delivery record may not exist if createDelivery failed
+          }
+        }
+
+        results.push({
+          channel,
+          destination: destinationLabel,
+          status: 'failed',
+          errorMessage,
+        });
+      }
+    }
+
+    return results;
+  }
+}

package/src/notifications/copy-composer.ts

@@ -0,0 +1,118 @@
+/**
+ * Deterministic, template-based copy generation for notification deliveries.
+ *
+ * This is the fallback path used when the decision engine's LLM-generated
+ * copy is unavailable (fallbackUsed === true). It generates reasonable
+ * copy from the signal's sourceEventName, contextPayload, and attentionHints.
+ *
+ * Each source event name has a set of fallback templates that interpolate
+ * values from the context payload.
+ */
+
+import type { NotificationSignal } from './signal.js';
+import type { NotificationChannel, RenderedChannelCopy } from './types.js';
+
+type CopyTemplate = (payload: Record<string, unknown>) => RenderedChannelCopy;
+
+function str(value: unknown, fallback: string): string {
+  if (typeof value === 'string' && value.length > 0) return value;
+  return fallback;
+}
+
+// Templates keyed by dot-separated sourceEventName strings matching producers.
+const TEMPLATES: Record<string, CopyTemplate> = {
+  'reminder.fired': (payload) => ({
+    title: 'Reminder',
+    body: str(payload.message, str(payload.label, 'A reminder has fired')),
+  }),
+
+  'schedule.complete': (payload) => ({
+    title: 'Schedule Complete',
+    body: `${str(payload.name, 'A schedule')} has finished running`,
+  }),
+
+  'guardian.question': (payload) => ({
+    title: 'Guardian Question',
+    body: str(payload.questionText, 'A guardian question needs your attention'),
+  }),
+
+  'ingress.escalation': (payload) => ({
+    title: 'Escalation',
+    body: str(payload.senderIdentifier, 'An incoming message') + ' needs attention',
+  }),
+
+  'watcher.notification': (payload) => ({
+    title: str(payload.title, 'Watcher Notification'),
+    body: str(payload.body, 'A watcher event occurred'),
+  }),
+
+  'watcher.escalation': (payload) => ({
+    title: str(payload.title, 'Watcher Escalation'),
+    body: str(payload.body, 'A watcher event requires your attention'),
+  }),
+
+  'tool_confirmation.required_action': (payload) => ({
+    title: 'Tool Confirmation',
+    body: str(payload.toolName, 'A tool') + ' requires your confirmation',
+  }),
+
+  'activity.complete': (payload) => ({
+    title: 'Activity Complete',
+    body: str(payload.summary, 'An activity has completed'),
+  }),
+
+  'quick_chat.response_ready': (payload) => ({
+    title: 'Response Ready',
+    body: str(payload.preview, 'Your quick chat response is ready'),
+  }),
+
+  'voice.response_ready': (payload) => ({
+    title: 'Voice Response',
+    body: str(payload.preview, 'A voice response is ready'),
+  }),
+
+  'ride_shotgun.invitation': (payload) => ({
+    title: 'Ride Shotgun',
+    body: str(payload.message, 'You have been invited to ride shotgun'),
+  }),
+};
+
+/**
+ * Compose fallback notification copy for a signal when the decision
+ * engine's LLM path is unavailable.
+ *
+ * Returns a map of channel -> RenderedChannelCopy for the requested channels.
+ * All channels currently receive the same template output; per-channel
+ * customisation can be layered on later.
+ */
+export function composeFallbackCopy(
+  signal: NotificationSignal,
+  channels: NotificationChannel[],
+): Partial<Record<NotificationChannel, RenderedChannelCopy>> {
+  const template = TEMPLATES[signal.sourceEventName];
+
+  const baseCopy: RenderedChannelCopy = template
+    ? template(signal.contextPayload)
+    : buildGenericCopy(signal);
+
+  const result: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {};
+  for (const ch of channels) {
+    result[ch] = { ...baseCopy };
+  }
+  return result;
+}
+
+/**
+ * Build generic copy when no template matches. Uses the signal's
+ * sourceEventName and attention hints to produce something reasonable.
+ */
+function buildGenericCopy(signal: NotificationSignal): RenderedChannelCopy {
+  const humanName = signal.sourceEventName.replace(/[._]/g, ' ');
+  const urgencyPrefix = signal.attentionHints.urgency === 'high' ? 'Urgent: ' : '';
+  const actionSuffix = signal.attentionHints.requiresAction ? ' — action required' : '';
+
+  return {
+    title: 'Notification',
+    body: `${urgencyPrefix}${humanName}${actionSuffix}`,
+  };
+}