@vellumai/assistant 0.3.7 → 0.3.9

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

package/src/notifications/decision-engine.ts

@@ -0,0 +1,391 @@
+/**
+ * Notification decision engine.
+ *
+ * Evaluates a NotificationSignal against available channels and user
+ * preferences, producing a NotificationDecision that tells the broadcaster
+ * whether and how to notify the user. Uses the provider abstraction to
+ * call the LLM with forced tool_choice output, falling back to a
+ * deterministic heuristic when the model is unavailable or returns
+ * invalid output.
+ */
+
+import { v4 as uuid } from 'uuid';
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import { getConfiguredProvider, createTimeout, extractToolUse, userMessage } from '../providers/provider-send-message.js';
+import { createDecision } from './decisions-store.js';
+import { getPreferenceSummary } from './preference-summary.js';
+import type { NotificationSignal } from './signal.js';
+import type { NotificationChannel, NotificationDecision, RenderedChannelCopy } from './types.js';
+
+const log = getLogger('notification-decision-engine');
+
+const DECISION_TIMEOUT_MS = 15_000;
+const PROMPT_VERSION = 'v1';
+
+// ── System prompt ──────────────────────────────────────────────────────
+
+function buildSystemPrompt(
+  availableChannels: NotificationChannel[],
+  preferenceContext?: string,
+): string {
+  const sections: string[] = [
+    `You are a notification routing engine. Given a signal describing an event, decide whether the user should be notified, on which channel(s), and compose the notification copy.`,
+    ``,
+    `Available notification channels: ${availableChannels.join(', ')}`,
+  ];
+
+  if (preferenceContext) {
+    sections.push(
+      ``,
+      `<user-preferences>`,
+      preferenceContext,
+      `</user-preferences>`,
+    );
+  }
+
+  sections.push(
+    ``,
+    `Guidelines:`,
+    `- Only notify when the signal genuinely warrants user attention.`,
+    `- Prefer fewer channels unless the signal is urgent.`,
+    `- For high-urgency signals that require action, notify on all available channels.`,
+    `- For low-urgency background events, suppress unless they match user preferences.`,
+    `- Keep notification copy concise and actionable.`,
+    `- Generate a stable dedupeKey derived from the signal context so duplicate signals can be suppressed.`,
+    ``,
+    `You MUST respond using the \`record_notification_decision\` tool. Do not respond with text.`,
+  );
+
+  return sections.join('\n');
+}
+
+// ── User prompt ────────────────────────────────────────────────────────
+
+function buildUserPrompt(signal: NotificationSignal): string {
+  const parts: string[] = [
+    `Signal ID: ${signal.signalId}`,
+    `Source event: ${signal.sourceEventName}`,
+    `Source channel: ${signal.sourceChannel}`,
+    `Urgency: ${signal.attentionHints.urgency}`,
+    `Requires action: ${signal.attentionHints.requiresAction}`,
+    `Is async background: ${signal.attentionHints.isAsyncBackground}`,
+    `User is viewing source now: ${signal.attentionHints.visibleInSourceNow}`,
+  ];
+
+  if (signal.attentionHints.deadlineAt) {
+    parts.push(`Deadline: ${new Date(signal.attentionHints.deadlineAt).toISOString()}`);
+  }
+
+  const payloadStr = JSON.stringify(signal.contextPayload);
+  if (payloadStr.length > 2) {
+    parts.push(``, `Context payload:`, payloadStr);
+  }
+
+  return `Evaluate this notification signal:\n\n${parts.join('\n')}`;
+}
+
+// ── Tool definition ────────────────────────────────────────────────────
+
+function buildDecisionTool(availableChannels: NotificationChannel[]) {
+  return {
+    name: 'record_notification_decision',
+    description: 'Record the notification routing decision for this signal',
+    input_schema: {
+      type: 'object' as const,
+      properties: {
+        shouldNotify: {
+          type: 'boolean',
+          description: 'Whether the user should be notified about this signal',
+        },
+        selectedChannels: {
+          type: 'array',
+          items: {
+            type: 'string',
+            enum: availableChannels,
+          },
+          description: 'Which channels to deliver the notification on',
+        },
+        reasoningSummary: {
+          type: 'string',
+          description: 'Brief explanation of why this routing decision was made',
+        },
+        renderedCopy: {
+          type: 'object',
+          description: 'Notification copy keyed by channel name',
+          properties: Object.fromEntries(
+            availableChannels.map((ch) => [
+              ch,
+              {
+                type: 'object',
+                properties: {
+                  title: { type: 'string', description: 'Short notification title' },
+                  body: { type: 'string', description: 'Notification body text' },
+                  threadTitle: { type: 'string', description: 'Optional thread title for grouped notifications' },
+                  threadSeedMessage: { type: 'string', description: 'Optional seed message for a new thread' },
+                },
+                required: ['title', 'body'],
+              },
+            ]),
+          ),
+        },
+        deepLinkTarget: {
+          type: 'object',
+          description: 'Optional deep link metadata for navigating to the source context',
+        },
+        dedupeKey: {
+          type: 'string',
+          description: 'A stable key derived from the signal to deduplicate repeated notifications for the same event',
+        },
+        confidence: {
+          type: 'number',
+          description: 'Confidence in the decision (0.0-1.0)',
+        },
+      },
+      required: ['shouldNotify', 'selectedChannels', 'reasoningSummary', 'renderedCopy', 'dedupeKey', 'confidence'],
+    },
+  };
+}
+
+// ── Deterministic fallback ─────────────────────────────────────────────
+
+function buildFallbackDecision(
+  signal: NotificationSignal,
+  availableChannels: NotificationChannel[],
+): NotificationDecision {
+  const isHighUrgencyAction =
+    signal.attentionHints.urgency === 'high' && signal.attentionHints.requiresAction;
+
+  if (isHighUrgencyAction) {
+    const copy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {};
+    for (const ch of availableChannels) {
+      copy[ch] = {
+        title: signal.sourceEventName,
+        body: `Action required: ${signal.sourceEventName}`,
+      };
+    }
+
+    return {
+      shouldNotify: true,
+      selectedChannels: [...availableChannels],
+      reasoningSummary: 'Fallback: high urgency + requires action',
+      renderedCopy: copy,
+      dedupeKey: `fallback:${signal.sourceEventName}:${signal.sourceSessionId}:${signal.createdAt}`,
+      confidence: 0.3,
+      fallbackUsed: true,
+    };
+  }
+
+  return {
+    shouldNotify: false,
+    selectedChannels: [],
+    reasoningSummary: 'Fallback: suppressed (not high urgency + requires action)',
+    renderedCopy: {},
+    dedupeKey: `fallback:${signal.sourceEventName}:${signal.sourceSessionId}:${signal.createdAt}`,
+    confidence: 0.3,
+    fallbackUsed: true,
+  };
+}
+
+// ── Validation ─────────────────────────────────────────────────────────
+
+const VALID_CHANNELS = new Set<string>(['macos', 'telegram']);
+
+function validateDecisionOutput(
+  input: Record<string, unknown>,
+  availableChannels: NotificationChannel[],
+): NotificationDecision | null {
+  if (typeof input.shouldNotify !== 'boolean') return null;
+  if (typeof input.reasoningSummary !== 'string') return null;
+  if (typeof input.dedupeKey !== 'string') return null;
+
+  if (!Array.isArray(input.selectedChannels)) return null;
+  const validatedChannels = (input.selectedChannels as unknown[]).filter(
+    (ch): ch is NotificationChannel =>
+      typeof ch === 'string' && VALID_CHANNELS.has(ch) && availableChannels.includes(ch as NotificationChannel),
+  );
+  const validChannels = [...new Set(validatedChannels)];
+
+  const confidence = typeof input.confidence === 'number'
+    ? Math.max(0, Math.min(1, input.confidence))
+    : 0.5;
+
+  // Validate renderedCopy
+  const renderedCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {};
+  if (input.renderedCopy && typeof input.renderedCopy === 'object') {
+    const copyObj = input.renderedCopy as Record<string, unknown>;
+    for (const ch of validChannels) {
+      const chCopy = copyObj[ch];
+      if (chCopy && typeof chCopy === 'object') {
+        const c = chCopy as Record<string, unknown>;
+        if (typeof c.title === 'string' && typeof c.body === 'string') {
+          renderedCopy[ch] = {
+            title: c.title,
+            body: c.body,
+            threadTitle: typeof c.threadTitle === 'string' ? c.threadTitle : undefined,
+            threadSeedMessage: typeof c.threadSeedMessage === 'string' ? c.threadSeedMessage : undefined,
+          };
+        }
+      }
+    }
+  }
+
+  const deepLinkTarget = input.deepLinkTarget && typeof input.deepLinkTarget === 'object'
+    ? input.deepLinkTarget as Record<string, unknown>
+    : undefined;
+
+  return {
+    shouldNotify: input.shouldNotify,
+    selectedChannels: validChannels,
+    reasoningSummary: input.reasoningSummary,
+    renderedCopy,
+    deepLinkTarget,
+    dedupeKey: input.dedupeKey,
+    confidence,
+    fallbackUsed: false,
+  };
+}
+
+// ── Core evaluation function ───────────────────────────────────────────
+
+export interface EvaluateSignalOptions {
+  shadowMode?: boolean;
+}
+
+export async function evaluateSignal(
+  signal: NotificationSignal,
+  availableChannels: NotificationChannel[],
+  preferenceContext?: string,
+  options?: EvaluateSignalOptions,
+): Promise<NotificationDecision> {
+  const config = getConfig();
+  const decisionModel = config.notifications.decisionModel;
+
+  // When no explicit preference context is provided, load the user's
+  // stored notification preferences from the memory-backed store.
+  // Wrapped in try/catch so a DB failure doesn't break the decision path.
+  let resolvedPreferenceContext = preferenceContext;
+  if (resolvedPreferenceContext === undefined) {
+    try {
+      resolvedPreferenceContext = getPreferenceSummary(signal.assistantId) ?? undefined;
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.warn({ err: errMsg, assistantId: signal.assistantId }, 'Failed to load preference summary, proceeding without preferences');
+      resolvedPreferenceContext = undefined;
+    }
+  }
+
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    log.warn('Configured provider unavailable for notification decision, using fallback');
+    const decision = buildFallbackDecision(signal, availableChannels);
+    decision.persistedDecisionId = persistDecision(signal, decision);
+    return decision;
+  }
+
+  let decision: NotificationDecision;
+  try {
+    decision = await classifyWithLLM(signal, availableChannels, resolvedPreferenceContext, decisionModel);
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.warn({ err: errMsg }, 'Notification decision LLM call failed, using fallback');
+    decision = buildFallbackDecision(signal, availableChannels);
+  }
+
+  decision.persistedDecisionId = persistDecision(signal, decision);
+
+  if (options?.shadowMode ?? config.notifications.shadowMode) {
+    log.info(
+      {
+        signalId: signal.signalId,
+        shouldNotify: decision.shouldNotify,
+        channels: decision.selectedChannels,
+        fallbackUsed: decision.fallbackUsed,
+        confidence: decision.confidence,
+      },
+      'Shadow mode: decision logged but not dispatched',
+    );
+  }
+
+  return decision;
+}
+
+// ── LLM classification ────────────────────────────────────────────────
+
+async function classifyWithLLM(
+  signal: NotificationSignal,
+  availableChannels: NotificationChannel[],
+  preferenceContext: string | undefined,
+  model: string,
+): Promise<NotificationDecision> {
+  const provider = getConfiguredProvider()!;
+  const { signal: abortSignal, cleanup } = createTimeout(DECISION_TIMEOUT_MS);
+
+  const systemPrompt = buildSystemPrompt(availableChannels, preferenceContext);
+  const prompt = buildUserPrompt(signal);
+  const tool = buildDecisionTool(availableChannels);
+
+  try {
+    const response = await provider.sendMessage(
+      [userMessage(prompt)],
+      [tool],
+      systemPrompt,
+      {
+        config: {
+          model,
+          max_tokens: 2048,
+          tool_choice: { type: 'tool' as const, name: 'record_notification_decision' },
+        },
+        signal: abortSignal,
+      },
+    );
+    cleanup();
+
+    const toolBlock = extractToolUse(response);
+    if (!toolBlock) {
+      log.warn('No tool_use block in notification decision response, using fallback');
+      return buildFallbackDecision(signal, availableChannels);
+    }
+
+    const validated = validateDecisionOutput(
+      toolBlock.input as Record<string, unknown>,
+      availableChannels,
+    );
+    if (!validated) {
+      log.warn('Invalid notification decision output from LLM, using fallback');
+      return buildFallbackDecision(signal, availableChannels);
+    }
+
+    return validated;
+  } finally {
+    cleanup();
+  }
+}
+
+// ── Persistence ────────────────────────────────────────────────────────
+
+function persistDecision(signal: NotificationSignal, decision: NotificationDecision): string | undefined {
+  try {
+    const decisionId = uuid();
+    createDecision({
+      id: decisionId,
+      notificationEventId: signal.signalId,
+      shouldNotify: decision.shouldNotify,
+      selectedChannels: decision.selectedChannels,
+      reasoningSummary: decision.reasoningSummary,
+      confidence: decision.confidence,
+      fallbackUsed: decision.fallbackUsed,
+      promptVersion: PROMPT_VERSION,
+      validationResults: {
+        dedupeKey: decision.dedupeKey,
+        channelCount: decision.selectedChannels.length,
+        hasCopy: Object.keys(decision.renderedCopy).length > 0,
+      },
+    });
+    return decisionId;
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.warn({ err: errMsg }, 'Failed to persist notification decision');
+    return undefined;
+  }
+}