@vellumai/assistant 0.3.8 → 0.3.9

package/src/config/notifications-schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export const NotificationsConfigSchema = z.object({
+  enabled: z
+    .boolean({ error: 'notifications.enabled must be a boolean' })
+    .default(false),
+  shadowMode: z
+    .boolean({ error: 'notifications.shadowMode must be a boolean' })
+    .default(true),
+  decisionModel: z
+    .string({ error: 'notifications.decisionModel must be a string' })
+    .default('claude-haiku-4-5-20251001'),
+});
+
+export type NotificationsConfig = z.infer<typeof NotificationsConfigSchema>;

package/src/config/schema.ts

@@ -90,6 +90,13 @@ export type {
   WorkspaceGitConfig,
 } from './agent-schema.js';
 
+export {
+  NotificationsConfigSchema,
+} from './notifications-schema.js';
+export type {
+  NotificationsConfig,
+} from './notifications-schema.js';
+
 export {
   TimeoutConfigSchema,
   RateLimitConfigSchema,
@@ -129,6 +136,7 @@ import { CallsConfigSchema } from './calls-schema.js';
 import { SandboxConfigSchema } from './sandbox-schema.js';
 import { SkillsConfigSchema } from './skills-schema.js';
 import { AgentHeartbeatConfigSchema, SwarmConfigSchema, WorkspaceGitConfigSchema } from './agent-schema.js';
+import { NotificationsConfigSchema } from './notifications-schema.js';
 import {
   TimeoutConfigSchema,
   RateLimitConfigSchema,
@@ -437,6 +445,11 @@ export const AssistantConfigSchema = z.object({
     sigkillGracePeriodMs: 2000,
     titleGenerationMaxTokens: 30,
   }),
+  notifications: NotificationsConfigSchema.default({
+    enabled: false,
+    shadowMode: true,
+    decisionModel: 'claude-haiku-4-5-20251001',
+  }),
 }).superRefine((config, ctx) => {
   if (config.contextWindow.targetInputTokens >= config.contextWindow.maxInputTokens) {
     ctx.addIssue({

package/src/config/types.ts

@@ -39,5 +39,6 @@ export type {
   CallerIdentityConfig,
   SmsConfig,
   IngressConfig,
+  NotificationsConfig,
   DaemonConfig,
 } from './schema.js';

package/src/daemon/ipc-contract/notifications.ts

@@ -0,0 +1,9 @@
+/** Broadcast to connected macOS clients when a notification should be displayed. */
+export interface NotificationIntent {
+  type: 'notification_intent';
+  sourceEventName: string;
+  title: string;
+  body: string;
+  /** Optional deep-link metadata so the client can navigate to the relevant context. */
+  deepLinkMetadata?: Record<string, unknown>;
+}

package/src/daemon/ipc-contract-inventory.json

@@ -201,6 +201,7 @@
     "MessageQueued",
     "MessageQueuedDeleted",
     "ModelInfo",
+    "NotificationIntent",
     "OpenBundleResponse",
     "OpenTasksWindow",
     "OpenUrl",
@@ -486,6 +487,7 @@
     "message_queued",
     "message_queued_deleted",
     "model_info",
+    "notification_intent",
     "open_bundle_response",
     "open_tasks_window",
     "open_url",

package/src/daemon/ipc-contract.ts

@@ -27,6 +27,7 @@ export * from './ipc-contract/diagnostics.js';
 export * from './ipc-contract/parental-control.js';
 export * from './ipc-contract/inbox.js';
 export * from './ipc-contract/pairing.js';
+export * from './ipc-contract/notifications.js';
 
 // Import types needed for aggregate unions and SubagentEvent
 import type { AuthMessage, PingMessage, CancelRequest, DeleteQueuedMessage, ModelGetRequest, ModelSetRequest, ImageGenModelSetRequest, HistoryRequest, UndoRequest, RegenerateRequest, UsageRequest, SandboxSetRequest, SessionListRequest, SessionCreateRequest, SessionSwitchRequest, SessionRenameRequest, SessionsClearRequest, ConversationSearchRequest } from './ipc-contract/sessions.js';
@@ -64,6 +65,7 @@ import type { SchedulesList, ScheduleToggle, ScheduleRemove, ScheduleRunNow, Rem
 import type { ParentalControlGetRequest, ParentalControlVerifyPinRequest, ParentalControlSetPinRequest, ParentalControlUpdateRequest, ParentalControlGetResponse, ParentalControlVerifyPinResponse, ParentalControlSetPinResponse, ParentalControlUpdateResponse } from './ipc-contract/parental-control.js';
 import type { IngressInviteRequest, IngressMemberRequest, AssistantInboxRequest, AssistantInboxEscalationRequest, AssistantInboxReplyRequest, IngressInviteResponse, IngressMemberResponse, AssistantInboxResponse, AssistantInboxEscalationResponse, AssistantInboxReplyResponse } from './ipc-contract/inbox.js';
 import type { PairingApprovalResponse, ApprovedDevicesList, ApprovedDeviceRemove, ApprovedDevicesClear, PairingApprovalRequest, ApprovedDevicesListResponse, ApprovedDeviceRemoveResponse } from './ipc-contract/pairing.js';
+import type { NotificationIntent } from './ipc-contract/notifications.js';
 
 // === SubagentEvent — defined here because it references ServerMessage ===
 
@@ -361,7 +363,8 @@ export type ServerMessage =
   | AssistantInboxReplyResponse
   | PairingApprovalRequest
   | ApprovedDevicesListResponse
-  | ApprovedDeviceRemoveResponse;
+  | ApprovedDeviceRemoveResponse
+  | NotificationIntent;
 
 // === Contract schema ===
 

package/src/daemon/lifecycle.ts

@@ -26,6 +26,7 @@ import { ensurePromptFiles } from '../config/system-prompt.js';
 import { loadPrebuiltHtml } from '../home-base/prebuilt/seed.js';
 import { DaemonServer } from './server.js';
 import { setRelayBroadcast } from '../calls/relay-server.js';
+import { setVoiceBridgeOrchestrator } from '../calls/voice-session-bridge.js';
 import { listWorkItems, updateWorkItem } from '../work-items/work-item-store.js';
 import { getLogger, initLogger } from '../util/logger.js';
 import { initSentry } from '../instrument.js';
@@ -44,6 +45,7 @@ import { HeartbeatService } from '../workspace/heartbeat-service.js';
 import { AgentHeartbeatService } from '../agent-heartbeat/agent-heartbeat-service.js';
 import { reconcileCallsOnStartup } from '../calls/call-recovery.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
+import { emitNotificationSignal, registerBroadcastFn } from '../notifications/emit-signal.js';
 import { createApprovalCopyGenerator, createApprovalConversationGenerator } from './approval-generators.js';
 import { initializeProvidersAndTools, registerWatcherProviders, registerMessagingProviders } from './providers-setup.js';
 import { installShutdownHandlers } from './shutdown-handlers.js';
@@ -187,38 +189,112 @@ export async function runDaemon(): Promise<void> {
   registerWatcherProviders();
   registerMessagingProviders();
 
+  // Register the IPC broadcast function for the notification signal pipeline's
+  // macOS adapter so it can deliver notification_intent messages to desktop clients.
+  registerBroadcastFn((msg) => server.broadcast(msg));
+
   const scheduler = startScheduler(
     async (conversationId, message) => {
       await server.processMessage(conversationId, message);
     },
     (reminder) => {
+      // Legacy IPC broadcast for backward compatibility with desktop client UI
       server.broadcast({
         type: 'reminder_fired',
         reminderId: reminder.id,
         label: reminder.label,
         message: reminder.message,
       });
+      // Signal pipeline: fire-and-forget
+      void emitNotificationSignal({
+        sourceEventName: 'reminder.fired',
+        sourceChannel: 'scheduler',
+        sourceSessionId: reminder.id,
+        attentionHints: {
+          requiresAction: true,
+          urgency: 'high',
+          isAsyncBackground: false,
+          visibleInSourceNow: false,
+        },
+        contextPayload: {
+          reminderId: reminder.id,
+          label: reminder.label,
+          message: reminder.message,
+        },
+        dedupeKey: `reminder:${reminder.id}`,
+      });
     },
     (schedule) => {
+      // Legacy IPC broadcast for backward compatibility with desktop client UI
       server.broadcast({
         type: 'schedule_complete',
         scheduleId: schedule.id,
         name: schedule.name,
       });
+      // Signal pipeline: fire-and-forget
+      void emitNotificationSignal({
+        sourceEventName: 'schedule.complete',
+        sourceChannel: 'scheduler',
+        sourceSessionId: schedule.id,
+        attentionHints: {
+          requiresAction: false,
+          urgency: 'medium',
+          isAsyncBackground: true,
+          visibleInSourceNow: false,
+        },
+        contextPayload: {
+          scheduleId: schedule.id,
+          name: schedule.name,
+        },
+      });
     },
     (notification) => {
+      // Legacy IPC broadcast for backward compatibility with desktop client UI
       server.broadcast({
         type: 'watcher_notification',
         title: notification.title,
         body: notification.body,
       });
+      // Signal pipeline: fire-and-forget
+      void emitNotificationSignal({
+        sourceEventName: 'watcher.notification',
+        sourceChannel: 'watcher',
+        sourceSessionId: `watcher-${Date.now()}`,
+        attentionHints: {
+          requiresAction: false,
+          urgency: 'low',
+          isAsyncBackground: true,
+          visibleInSourceNow: false,
+        },
+        contextPayload: {
+          title: notification.title,
+          body: notification.body,
+        },
+      });
     },
     (params) => {
+      // Legacy IPC broadcast for backward compatibility with desktop client UI
       server.broadcast({
         type: 'watcher_escalation',
         title: params.title,
         body: params.body,
       });
+      // Signal pipeline: fire-and-forget
+      void emitNotificationSignal({
+        sourceEventName: 'watcher.escalation',
+        sourceChannel: 'watcher',
+        sourceSessionId: `watcher-escalation-${Date.now()}`,
+        attentionHints: {
+          requiresAction: true,
+          urgency: 'high',
+          isAsyncBackground: false,
+          visibleInSourceNow: false,
+        },
+        contextPayload: {
+          title: params.title,
+          body: params.body,
+        },
+      });
     },
   );
 
@@ -250,6 +326,8 @@ export async function runDaemon(): Promise<void> {
 
   const hostname = getRuntimeHttpHost();
 
+  const runOrchestrator = server.createRunOrchestrator();
+
   runtimeHttp = new RuntimeHttpServer({
     port: httpPort,
     hostname,
@@ -258,7 +336,7 @@ export async function runDaemon(): Promise<void> {
       server.processMessage(conversationId, content, attachmentIds, options, sourceChannel),
     persistAndProcessMessage: (conversationId, content, attachmentIds, options, sourceChannel) =>
       server.persistAndProcessMessage(conversationId, content, attachmentIds, options, sourceChannel),
-    runOrchestrator: server.createRunOrchestrator(),
+    runOrchestrator,
     interfacesDir: getInterfacesDir(),
     approvalCopyGenerator: createApprovalCopyGenerator(),
     approvalConversationGenerator: createApprovalConversationGenerator(),
@@ -275,6 +353,11 @@ export async function runDaemon(): Promise<void> {
         })),
     },
   });
+
+  // Inject the voice bridge orchestrator BEFORE attempting to start the HTTP
+  // server. The bridge only needs the RunOrchestrator instance (already created
+  // above) and must be available even when the HTTP server fails to bind.
+  setVoiceBridgeOrchestrator(runOrchestrator);
   try {
     await runtimeHttp.start();
     setRelayBroadcast((msg) => server.broadcast(msg));

package/src/daemon/session-agent-loop.ts

@@ -100,6 +100,7 @@ export interface AgentLoopSessionContext {
   channelCapabilities?: ChannelCapabilities;
   commandIntent?: { type: string; payload?: string; languageCode?: string };
   guardianContext?: GuardianRuntimeContext;
+  voiceCallControlPrompt?: string;
 
   readonly coreToolNames: Set<string>;
   allowedToolNames?: Set<string>;
@@ -321,6 +322,7 @@ export async function runAgentLoopImpl(
       channelTurnContext,
       guardianContext: ctx.guardianContext ?? null,
       temporalContext,
+      voiceCallControlPrompt: ctx.voiceCallControlPrompt ?? null,
     });
 
     // Pre-run repair
@@ -431,6 +433,7 @@ export async function runAgentLoopImpl(
           channelTurnContext,
           guardianContext: ctx.guardianContext ?? null,
           temporalContext,
+          voiceCallControlPrompt: ctx.voiceCallControlPrompt ?? null,
         });
         preRepairMessages = runMessages;
         preRunHistoryLength = runMessages.length;
@@ -466,6 +469,7 @@ export async function runAgentLoopImpl(
             channelTurnContext,
             guardianContext: ctx.guardianContext ?? null,
             temporalContext,
+            voiceCallControlPrompt: ctx.voiceCallControlPrompt ?? null,
           });
           preRepairMessages = runMessages;
           preRunHistoryLength = runMessages.length;

package/src/daemon/session-process.ts

@@ -24,6 +24,8 @@ import {
 import { answerCall } from '../calls/call-domain.js';
 import { resolveSlash, type SlashContext } from './session-slash.js';
 import { getConfig } from '../config/loader.js';
+import { extractPreferences } from '../notifications/preference-extractor.js';
+import { createPreference } from '../notifications/preferences-store.js';
 import { getLogger } from '../util/logger.js';
 
 const log = getLogger('session-process');
@@ -68,6 +70,8 @@ export interface ProcessSessionContext {
   readonly usageStats: UsageStats;
   /** Request-scoped skill IDs preactivated via slash resolution. */
   preactivatedSkillIds?: string[];
+  /** Assistant identity — used for scoping notification preferences. */
+  readonly assistantId?: string;
   persistUserMessage(content: string, attachments: UserMessageAttachment[], requestId?: string, metadata?: Record<string, unknown>): string;
   runAgentLoop(
     content: string,
@@ -231,6 +235,29 @@ export function drainQueue(session: ProcessSessionContext, reason: QueueDrainRea
   session.currentActiveSurfaceId = next.activeSurfaceId;
   session.currentPage = next.currentPage;
 
+  // Fire-and-forget: detect notification preferences in the queued message
+  // and persist any that are found, mirroring the logic in processMessage.
+  if (session.assistantId && getConfig().notifications.enabled) {
+    const aid = session.assistantId;
+    extractPreferences(resolvedContent)
+      .then((result) => {
+        if (!result.detected) return;
+        for (const pref of result.preferences) {
+          createPreference({
+            assistantId: aid,
+            preferenceText: pref.preferenceText,
+            appliesWhen: pref.appliesWhen,
+            priority: pref.priority,
+          });
+        }
+        log.info({ count: result.preferences.length, conversationId: session.conversationId }, 'Persisted extracted notification preferences (queued)');
+      })
+      .catch((err) => {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log.warn({ err: errMsg, conversationId: session.conversationId }, 'Background preference extraction failed (queued)');
+      });
+  }
+
   // Fire-and-forget: persistUserMessage set session.processing = true
   // so subsequent messages will still be enqueued.
   // runAgentLoop's finally block will call drainQueue when this run completes.
@@ -375,6 +402,30 @@ export async function processMessage(
     return '';
   }
 
+  // Fire-and-forget: detect notification preferences in the user message
+  // and persist any that are found. Runs in the background so it doesn't
+  // block the main conversation flow.
+  if (session.assistantId && getConfig().notifications.enabled) {
+    const aid = session.assistantId;
+    extractPreferences(resolvedContent)
+      .then((result) => {
+        if (!result.detected) return;
+        for (const pref of result.preferences) {
+          createPreference({
+            assistantId: aid,
+            preferenceText: pref.preferenceText,
+            appliesWhen: pref.appliesWhen,
+            priority: pref.priority,
+          });
+        }
+        log.info({ count: result.preferences.length, conversationId: session.conversationId }, 'Persisted extracted notification preferences');
+      })
+      .catch((err) => {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log.warn({ err: errMsg, conversationId: session.conversationId }, 'Background preference extraction failed');
+      });
+  }
+
   await session.runAgentLoop(resolvedContent, userMessageId, onEvent);
   return userMessageId;
 }

package/src/daemon/session-runtime-assembly.ts

@@ -261,6 +261,26 @@ export function injectActiveSurfaceContext(message: Message, ctx: ActiveSurfaceC
   };
 }
 
+/**
+ * Append voice call-control protocol instructions to the last user
+ * message so the model knows how to emit control markers during voice
+ * turns routed through the session pipeline.
+ */
+export function injectVoiceCallControlContext(message: Message, prompt: string): Message {
+  return {
+    ...message,
+    content: [
+      ...message.content,
+      { type: 'text', text: prompt },
+    ],
+  };
+}
+
+/** Strip `<voice_call_control>` blocks injected by `injectVoiceCallControlContext`. */
+export function stripVoiceCallControlContext(messages: Message[]): Message[] {
+  return stripUserTextBlocksByPrefix(messages, ['<voice_call_control>']);
+}
+
 /**
  * Prepend channel capability context to the last user message so the
  * model knows what the current channel can and cannot do.
@@ -514,6 +534,7 @@ const RUNTIME_INJECTION_PREFIXES = [
   '<channel_command_context>',
   '<channel_turn_context>',
   '<guardian_context>',
+  '<voice_call_control>',
   '<workspace_top_level>',
   TEMPORAL_INJECTED_PREFIX,
   '<active_workspace>',
@@ -558,10 +579,21 @@ export function applyRuntimeInjections(
     channelTurnContext?: ChannelTurnContextParams | null;
     guardianContext?: GuardianRuntimeContext | null;
     temporalContext?: string | null;
+    voiceCallControlPrompt?: string | null;
   },
 ): Message[] {
   let result = runMessages;
 
+  if (options.voiceCallControlPrompt) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectVoiceCallControlContext(userTail, options.voiceCallControlPrompt),
+      ];
+    }
+  }
+
   if (options.softConflictInstruction) {
     const userTail = result[result.length - 1];
     if (userTail && userTail.role === 'user') {

package/src/daemon/session.ts

@@ -130,6 +130,7 @@ export class Session {
   /** @internal */ currentPage?: string;
   /** @internal */ channelCapabilities?: ChannelCapabilities;
   /** @internal */ guardianContext?: GuardianRuntimeContext;
+  /** @internal */ voiceCallControlPrompt?: string;
   /** @internal */ assistantId?: string;
   /** @internal */ commandIntent?: { type: string; payload?: string; languageCode?: string };
   /** @internal */ pendingSurfaceActions = new Map<string, { surfaceType: SurfaceType }>();
@@ -344,6 +345,10 @@ export class Session {
     this.guardianContext = ctx ?? undefined;
   }
 
+  setVoiceCallControlPrompt(prompt: string | null): void {
+    this.voiceCallControlPrompt = prompt ?? undefined;
+  }
+
   setAssistantId(assistantId: string | null): void {
     this.assistantId = assistantId ?? undefined;
   }

package/src/memory/db-init.ts

@@ -16,6 +16,7 @@ import {
   migrateGuardianActionTables,
   migrateBackfillInboxThreadStateFromBindings,
   migrateDropActiveSearchIndex,
+  migrateNotificationTablesSchema,
   migrateMemorySegmentsIndexes,
   migrateMemoryItemsIndexes,
   migrateRemainingTableIndexes,
@@ -1276,5 +1277,84 @@ export function initializeDb(): void {
 
   migrateRemainingTableIndexes(database);
 
+  // ── Notification System ──────────────────────────────────────────────
+
+  // Migration: drop legacy enum-based notification tables if old schema detected.
+  // Guarded behind a one-time check for the old `notification_type` column.
+  migrateNotificationTablesSchema(database);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_preferences (
+      id TEXT PRIMARY KEY,
+      assistant_id TEXT NOT NULL,
+      preference_text TEXT NOT NULL,
+      applies_when_json TEXT NOT NULL DEFAULT '{}',
+      priority INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_id ON notification_preferences(assistant_id)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_priority ON notification_preferences(assistant_id, priority DESC)`);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_events (
+      id TEXT PRIMARY KEY,
+      assistant_id TEXT NOT NULL,
+      source_event_name TEXT NOT NULL,
+      source_channel TEXT NOT NULL,
+      source_session_id TEXT NOT NULL,
+      attention_hints_json TEXT NOT NULL DEFAULT '{}',
+      payload_json TEXT NOT NULL DEFAULT '{}',
+      dedupe_key TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_events_assistant_event_created ON notification_events(assistant_id, source_event_name, created_at)`);
+  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_events_dedupe ON notification_events(assistant_id, dedupe_key) WHERE dedupe_key IS NOT NULL`);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_decisions (
+      id TEXT PRIMARY KEY,
+      notification_event_id TEXT NOT NULL REFERENCES notification_events(id) ON DELETE CASCADE,
+      should_notify INTEGER NOT NULL,
+      selected_channels TEXT NOT NULL DEFAULT '[]',
+      reasoning_summary TEXT NOT NULL,
+      confidence REAL NOT NULL,
+      fallback_used INTEGER NOT NULL DEFAULT 0,
+      prompt_version TEXT,
+      validation_results TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_decisions_event_id ON notification_decisions(notification_event_id)`);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_deliveries (
+      id TEXT PRIMARY KEY,
+      notification_decision_id TEXT NOT NULL REFERENCES notification_decisions(id) ON DELETE CASCADE,
+      assistant_id TEXT NOT NULL,
+      channel TEXT NOT NULL,
+      destination TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      attempt INTEGER NOT NULL DEFAULT 1,
+      rendered_title TEXT,
+      rendered_body TEXT,
+      error_code TEXT,
+      error_message TEXT,
+      sent_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_deliveries_unique ON notification_deliveries(notification_decision_id, channel, destination, attempt)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_decision_id ON notification_deliveries(notification_decision_id)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_assistant_status ON notification_deliveries(assistant_id, status)`)
+
   validateMigrationState(database);
 }

package/src/memory/guardian-action-store.ts

@@ -7,7 +7,7 @@
  * answer resolves the request and all other deliveries are marked answered.
  */
 
-import { and, eq, lt, inArray } from 'drizzle-orm';
+import { and, eq, inArray, lt } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb, rawChanges } from './db.js';
 import {
@@ -337,7 +337,7 @@ export function createGuardianActionDelivery(params: {
 }
 
 /**
- * Look up pending deliveries for a specific destination.
+ * Look up sent deliveries for a specific destination.
  * Used by inbound message routing to match incoming answers to deliveries.
  */
 export function getPendingDeliveriesByDestination(

package/src/memory/migrations/019-notification-tables-schema-migration.ts

@@ -0,0 +1,70 @@
+import { getSqliteFrom, type DrizzleDb } from '../db-connection.js';
+
+/**
+ * One-time migration: drop legacy enum-based notification tables so they can
+ * be recreated with the new signal-contract schema.
+ *
+ * Guard: only runs when the old `notification_type` column exists on the
+ * `notification_events` table (the old enum-based schema).  On fresh installs
+ * the table either doesn't exist yet or was created with the new schema, so
+ * CREATE TABLE IF NOT EXISTS in db-init handles idempotent creation.
+ *
+ * Drop order matters because of FK references:
+ *   notification_deliveries -> notification_events  (old schema FK)
+ *   notification_decisions  -> notification_events  (new schema FK, may exist from partial upgrade)
+ *   notification_events     (the table being rebuilt)
+ *   notification_preferences (fully removed, replaced by decision engine)
+ */
+export function migrateNotificationTablesSchema(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  const checkpointKey = 'migration_notification_tables_schema_v1';
+  const checkpoint = raw.query(
+    `SELECT 1 FROM memory_checkpoints WHERE key = ?`,
+  ).get(checkpointKey);
+  if (checkpoint) return;
+
+  // Check if the old schema is present: the legacy notification_events table
+  // had a `notification_type` column that the new schema does not.
+  const hasOldSchema = raw.query(
+    `SELECT COUNT(*) as cnt FROM pragma_table_info('notification_events') WHERE name = 'notification_type'`,
+  ).get() as { cnt: number } | undefined;
+
+  if (hasOldSchema && hasOldSchema.cnt > 0) {
+    try {
+      raw.exec('BEGIN');
+
+      // Drop in FK-safe order: children before parents
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_deliveries`);
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_decisions`);
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_events`);
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_preferences`);
+
+      raw.query(
+        `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
+      ).run(checkpointKey, Date.now());
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    }
+  } else {
+    // No old schema detected (fresh install or already migrated).
+    // Still clean up notification_preferences if it exists, since we want
+    // to ensure it's removed regardless.
+    try {
+      raw.exec('BEGIN');
+
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_preferences`);
+
+      raw.query(
+        `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
+      ).run(checkpointKey, Date.now());
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    }
+  }
+}

package/src/memory/migrations/index.ts

@@ -22,3 +22,4 @@ export { migrateDropActiveSearchIndex } from './015-drop-active-search-index.js'
 export { migrateMemorySegmentsIndexes } from './016-memory-segments-indexes.js';
 export { migrateMemoryItemsIndexes } from './017-memory-items-indexes.js';
 export { migrateRemainingTableIndexes } from './018-remaining-table-indexes.js';
+export { migrateNotificationTablesSchema } from './019-notification-tables-schema-migration.js';

package/src/memory/migrations/registry.ts

@@ -69,6 +69,11 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 9,
     description: 'Drop old idx_memory_items_active_search so it can be recreated with updated covering columns',
   },
+  {
+    key: 'migration_notification_tables_schema_v1',
+    version: 10,
+    description: 'Drop legacy enum-based notification tables so they can be recreated with the new signal-contract schema',
+  },
 ];
 
 export interface MigrationValidationResult {

package/src/memory/schema-migration.ts

@@ -19,6 +19,7 @@ export {
   migrateGuardianActionTables,
   migrateBackfillInboxThreadStateFromBindings,
   migrateDropActiveSearchIndex,
+  migrateNotificationTablesSchema,
   migrateMemorySegmentsIndexes,
   migrateMemoryItemsIndexes,
   migrateRemainingTableIndexes,