feat: introduce notification system and claude notifications

server/claude-sdk.js

@@ -18,6 +18,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { CLAUDE_MODELS } from '../shared/modelConstants.js';
+import { createNotificationEvent, notifyUserIfEnabled } from './services/notification-orchestrator.js';
 
 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
@@ -461,6 +462,14 @@ async function queryClaudeSDK(command, options = {}, ws) {
   let tempImagePaths = [];
   let tempDir = null;
 
+  const emitNotification = (event) => {
+    notifyUserIfEnabled({
+      userId: ws?.userId || null,
+      writer: ws,
+      event
+    });
+  };
+
   try {
     // Map CLI options to SDK format
     const sdkOptions = mapCliOptionsToSDK(options);
@@ -477,6 +486,42 @@ async function queryClaudeSDK(command, options = {}, ws) {
     tempImagePaths = imageResult.tempImagePaths;
     tempDir = imageResult.tempDir;
 
+    sdkOptions.hooks = {
+      Notification: [{
+        matcher: '',
+        hooks: [async (input) => {
+          const message = typeof input?.message === 'string' ? input.message : 'Claude requires your attention.';
+          emitNotification(createNotificationEvent({
+            provider: 'claude',
+            sessionId: capturedSessionId || sessionId || null,
+            kind: 'action_required',
+            code: 'agent.notification',
+            meta: { message },
+            severity: 'warning',
+            requiresUserAction: true,
+            dedupeKey: `claude:hook:notification:${capturedSessionId || sessionId || 'none'}:${message}`
+          }));
+          return {};
+        }]
+      }],
+      Stop: [{
+        matcher: '',
+        hooks: [async (input) => {
+          const stopReason = typeof input?.stop_reason === 'string' ? input.stop_reason : 'completed';
+          emitNotification(createNotificationEvent({
+            provider: 'claude',
+            sessionId: capturedSessionId || sessionId || null,
+            kind: 'stop',
+            code: 'run.stopped',
+            meta: { stopReason },
+            severity: 'info',
+            dedupeKey: `claude:hook:stop:${capturedSessionId || sessionId || 'none'}:${stopReason}`
+          }));
+          return {};
+        }]
+      }]
+    };
+
     sdkOptions.canUseTool = async (toolName, input, context) => {
       const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);
 
@@ -508,6 +553,16 @@ async function queryClaudeSDK(command, options = {}, ws) {
         input,
         sessionId: capturedSessionId || sessionId || null
       });
+      emitNotification(createNotificationEvent({
+        provider: 'claude',
+        sessionId: capturedSessionId || sessionId || null,
+        kind: 'action_required',
+        code: 'permission.required',
+        meta: { toolName },
+        severity: 'warning',
+        requiresUserAction: true,
+        dedupeKey: `claude:permission:${capturedSessionId || sessionId || 'none'}:${requestId}`
+      }));
 
       const decision = await waitForToolApproval(requestId, {
         timeoutMs: requiresInteraction ? 0 : undefined,
@@ -548,10 +603,22 @@ async function queryClaudeSDK(command, options = {}, ws) {
     const prevStreamTimeout = process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT;
     process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT = '300000';
 
-    const queryInstance = query({
-      prompt: finalCommand,
-      options: sdkOptions
-    });
+    let queryInstance;
+    try {
+      queryInstance = query({
+        prompt: finalCommand,
+        options: sdkOptions
+      });
+    } catch (hookError) {
+      // Older/newer SDK versions may not accept hook shapes yet.
+      // Keep notification behavior operational via runtime events even if hook registration fails.
+      console.warn('Failed to initialize Claude query with hooks, retrying without hooks:', hookError?.message || hookError);
+      delete sdkOptions.hooks;
+      queryInstance = query({
+        prompt: finalCommand,
+        options: sdkOptions
+      });
+    }
 
     // Restore immediately — Query constructor already captured the value
     if (prevStreamTimeout !== undefined) {
@@ -653,6 +720,15 @@ async function queryClaudeSDK(command, options = {}, ws) {
       error: error.message,
       sessionId: capturedSessionId || sessionId || null
     });
+    emitNotification(createNotificationEvent({
+      provider: 'claude',
+      sessionId: capturedSessionId || sessionId || null,
+      kind: 'error',
+      code: 'run.failed',
+      meta: { error: error.message },
+      severity: 'error',
+      dedupeKey: `claude:error:${capturedSessionId || sessionId || 'none'}:${error.message}`
+    }));
 
     throw error;
   }

server/database/db.js

@@ -91,6 +91,36 @@ const runMigrations = () => {
       db.exec('ALTER TABLE users ADD COLUMN has_completed_onboarding BOOLEAN DEFAULT 0');
     }
 
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS user_notification_preferences (
+        user_id INTEGER PRIMARY KEY,
+        preferences_json TEXT NOT NULL,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+      )
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS vapid_keys (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        public_key TEXT NOT NULL,
+        private_key TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS push_subscriptions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id INTEGER NOT NULL,
+        endpoint TEXT NOT NULL UNIQUE,
+        keys_p256dh TEXT NOT NULL,
+        keys_auth TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+      )
+    `);
+
     console.log('Database migrations completed successfully');
   } catch (error) {
     console.error('Error running migrations:', error.message);
@@ -348,6 +378,116 @@ const credentialsDb = {
   }
 };
 
+const DEFAULT_NOTIFICATION_PREFERENCES = {
+  channels: {
+    inApp: false,
+    webPush: true
+  },
+  events: {
+    actionRequired: true,
+    stop: true,
+    error: true
+  }
+};
+
+const normalizeNotificationPreferences = (value) => {
+  const source = value && typeof value === 'object' ? value : {};
+
+  return {
+    channels: {
+      inApp: source.channels?.inApp === true,
+      webPush: source.channels?.webPush !== false
+    },
+    events: {
+      actionRequired: source.events?.actionRequired !== false,
+      stop: source.events?.stop !== false,
+      error: source.events?.error !== false
+    }
+  };
+};
+
+const notificationPreferencesDb = {
+  getPreferences: (userId) => {
+    try {
+      const row = db.prepare('SELECT preferences_json FROM user_notification_preferences WHERE user_id = ?').get(userId);
+      if (!row) {
+        const defaults = normalizeNotificationPreferences(DEFAULT_NOTIFICATION_PREFERENCES);
+        db.prepare(
+          'INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)'
+        ).run(userId, JSON.stringify(defaults));
+        return defaults;
+      }
+
+      let parsed;
+      try {
+        parsed = JSON.parse(row.preferences_json);
+      } catch {
+        parsed = DEFAULT_NOTIFICATION_PREFERENCES;
+      }
+      return normalizeNotificationPreferences(parsed);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  updatePreferences: (userId, preferences) => {
+    try {
+      const normalized = normalizeNotificationPreferences(preferences);
+      db.prepare(
+        `INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at)
+         VALUES (?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(user_id) DO UPDATE SET
+           preferences_json = excluded.preferences_json,
+           updated_at = CURRENT_TIMESTAMP`
+      ).run(userId, JSON.stringify(normalized));
+      return normalized;
+    } catch (err) {
+      throw err;
+    }
+  }
+};
+
+const pushSubscriptionsDb = {
+  saveSubscription: (userId, endpoint, keysP256dh, keysAuth) => {
+    try {
+      db.prepare(
+        `INSERT INTO push_subscriptions (user_id, endpoint, keys_p256dh, keys_auth)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(endpoint) DO UPDATE SET
+           user_id = excluded.user_id,
+           keys_p256dh = excluded.keys_p256dh,
+           keys_auth = excluded.keys_auth`
+      ).run(userId, endpoint, keysP256dh, keysAuth);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  getSubscriptions: (userId) => {
+    try {
+      return db.prepare('SELECT endpoint, keys_p256dh, keys_auth FROM push_subscriptions WHERE user_id = ?').all(userId);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  removeSubscription: (endpoint) => {
+    try {
+      db.prepare('DELETE FROM push_subscriptions WHERE endpoint = ?').run(endpoint);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  removeAllForUser: (userId) => {
+    try {
+      db.prepare('DELETE FROM push_subscriptions WHERE user_id = ?').run(userId);
+    } catch (err) {
+      throw err;
+    }
+  }
+};
+
 // Backward compatibility - keep old names pointing to new system
 const githubTokensDb = {
   createGithubToken: (userId, tokenName, githubToken, description = null) => {
@@ -373,5 +513,7 @@ export {
   userDb,
   apiKeysDb,
   credentialsDb,
+  notificationPreferencesDb,
+  pushSubscriptionsDb,
   githubTokensDb // Backward compatibility
-};
+};

server/database/init.sql

@@ -49,4 +49,31 @@ CREATE TABLE IF NOT EXISTS user_credentials (
 
 CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
 CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
+
+-- User notification preferences (backend-owned, provider-agnostic)
+CREATE TABLE IF NOT EXISTS user_notification_preferences (
+    user_id INTEGER PRIMARY KEY,
+    preferences_json TEXT NOT NULL,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+-- VAPID key pair for Web Push notifications
+CREATE TABLE IF NOT EXISTS vapid_keys (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    public_key TEXT NOT NULL,
+    private_key TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Browser push subscriptions
+CREATE TABLE IF NOT EXISTS push_subscriptions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    endpoint TEXT NOT NULL UNIQUE,
+    keys_p256dh TEXT NOT NULL,
+    keys_auth TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);

server/index.js

@@ -62,6 +62,7 @@ import cliAuthRoutes from './routes/cli-auth.js';
 import userRoutes from './routes/user.js';
 import codexRoutes from './routes/codex.js';
 import { initializeDatabase } from './database/db.js';
+import { configureWebPush } from './services/vapid-keys.js';
 import { validateApiKey, authenticateToken, authenticateWebSocket } from './middleware/auth.js';
 import { IS_PLATFORM } from './constants/config.js';
 
@@ -888,7 +889,7 @@ wss.on('connection', (ws, request) => {
     if (pathname === '/shell') {
         handleShellConnection(ws);
     } else if (pathname === '/ws') {
-        handleChatConnection(ws);
+        handleChatConnection(ws, request);
     } else {
         console.log('[WARN] Unknown WebSocket path:', pathname);
         ws.close();
@@ -899,9 +900,10 @@ wss.on('connection', (ws, request) => {
  * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
  */
 class WebSocketWriter {
-  constructor(ws) {
+  constructor(ws, userId = null) {
     this.ws = ws;
     this.sessionId = null;
+    this.userId = userId;
     this.isWebSocketWriter = true;  // Marker for transport detection
   }
 
@@ -922,14 +924,14 @@ class WebSocketWriter {
 }
 
 // Handle chat WebSocket connections
-function handleChatConnection(ws) {
+function handleChatConnection(ws, request) {
     console.log('[INFO] Chat WebSocket connected');
 
     // Add to connected clients for project updates
     connectedClients.add(ws);
 
     // Wrap WebSocket with writer for consistent interface with SSEStreamWriter
-    const writer = new WebSocketWriter(ws);
+    const writer = new WebSocketWriter(ws, request?.user?.id ?? request?.user?.userId ?? null);
 
     ws.on('message', async (message) => {
         try {
@@ -1918,6 +1920,9 @@ async function startServer() {
         // Initialize authentication database
         await initializeDatabase();
 
+        // Configure Web Push (VAPID keys)
+        configureWebPush();
+
         // Check if running in production mode (dist folder exists)
         const distIndexPath = path.join(__dirname, '../dist/index.html');
         const isProduction = fs.existsSync(distIndexPath);

server/middleware/auth.js

@@ -85,7 +85,7 @@ const authenticateWebSocket = (token) => {
     try {
       const user = userDb.getFirstUser();
       if (user) {
-        return { userId: user.id, username: user.username };
+        return { id: user.id, userId: user.id, username: user.username };
       }
       return null;
     } catch (error) {
@@ -101,7 +101,10 @@ const authenticateWebSocket = (token) => {
 
   try {
     const decoded = jwt.verify(token, JWT_SECRET);
-    return decoded;
+    return {
+      ...decoded,
+      id: decoded.userId
+    };
   } catch (error) {
     console.error('WebSocket token verification error:', error);
     return null;
@@ -114,4 +117,4 @@ export {
   generateToken,
   authenticateWebSocket,
   JWT_SECRET
-};
+};

server/routes/settings.js

@@ -1,5 +1,6 @@
 import express from 'express';
-import { apiKeysDb, credentialsDb } from '../database/db.js';
+import { apiKeysDb, credentialsDb, notificationPreferencesDb, pushSubscriptionsDb } from '../database/db.js';
+import { getPublicKey } from '../services/vapid-keys.js';
 
 const router = express.Router();
 
@@ -175,4 +176,70 @@ router.patch('/credentials/:credentialId/toggle', async (req, res) => {
   }
 });
 
+// ===============================
+// Notification Preferences
+// ===============================
+
+router.get('/notification-preferences', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.getPreferences(req.user.id);
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error fetching notification preferences:', error);
+    res.status(500).json({ error: 'Failed to fetch notification preferences' });
+  }
+});
+
+router.put('/notification-preferences', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.updatePreferences(req.user.id, req.body || {});
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error saving notification preferences:', error);
+    res.status(500).json({ error: 'Failed to save notification preferences' });
+  }
+});
+
+// ===============================
+// Push Subscription Management
+// ===============================
+
+router.get('/push/vapid-public-key', async (req, res) => {
+  try {
+    const publicKey = getPublicKey();
+    res.json({ publicKey });
+  } catch (error) {
+    console.error('Error fetching VAPID public key:', error);
+    res.status(500).json({ error: 'Failed to fetch VAPID public key' });
+  }
+});
+
+router.post('/push/subscribe', async (req, res) => {
+  try {
+    const { endpoint, keys } = req.body;
+    if (!endpoint || !keys?.p256dh || !keys?.auth) {
+      return res.status(400).json({ error: 'Missing subscription fields' });
+    }
+    pushSubscriptionsDb.saveSubscription(req.user.id, endpoint, keys.p256dh, keys.auth);
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error saving push subscription:', error);
+    res.status(500).json({ error: 'Failed to save push subscription' });
+  }
+});
+
+router.post('/push/unsubscribe', async (req, res) => {
+  try {
+    const { endpoint } = req.body;
+    if (!endpoint) {
+      return res.status(400).json({ error: 'Missing endpoint' });
+    }
+    pushSubscriptionsDb.removeSubscription(endpoint);
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error removing push subscription:', error);
+    res.status(500).json({ error: 'Failed to remove push subscription' });
+  }
+});
+
 export default router;

server/services/notification-orchestrator.js

@@ -0,0 +1,149 @@
+import webPush from 'web-push';
+import { notificationPreferencesDb, pushSubscriptionsDb } from '../database/db.js';
+
+const KIND_TO_PREF_KEY = {
+  action_required: 'actionRequired',
+  stop: 'stop',
+  error: 'error'
+};
+
+const recentEventKeys = new Map();
+const DEDUPE_WINDOW_MS = 20000;
+
+const cleanupOldEventKeys = () => {
+  const now = Date.now();
+  for (const [key, timestamp] of recentEventKeys.entries()) {
+    if (now - timestamp > DEDUPE_WINDOW_MS) {
+      recentEventKeys.delete(key);
+    }
+  }
+};
+
+function shouldSendPush(preferences, event) {
+  const webPushEnabled = Boolean(preferences?.channels?.webPush);
+  const prefEventKey = KIND_TO_PREF_KEY[event.kind];
+  const eventEnabled = prefEventKey ? Boolean(preferences?.events?.[prefEventKey]) : true;
+
+  return webPushEnabled && eventEnabled;
+}
+
+function isDuplicate(event) {
+  cleanupOldEventKeys();
+  const key = event.dedupeKey || `${event.provider}:${event.kind || 'info'}:${event.code || 'generic'}:${event.sessionId || 'none'}`;
+  if (recentEventKeys.has(key)) {
+    return true;
+  }
+  recentEventKeys.set(key, Date.now());
+  return false;
+}
+
+function createNotificationEvent({
+  provider,
+  sessionId = null,
+  kind = 'info',
+  code = 'generic.info',
+  meta = {},
+  severity = 'info',
+  dedupeKey = null,
+  requiresUserAction = false
+}) {
+  return {
+    provider,
+    sessionId,
+    kind,
+    code,
+    meta,
+    severity,
+    requiresUserAction,
+    dedupeKey,
+    createdAt: new Date().toISOString()
+  };
+}
+
+function buildPushBody(event) {
+  const CODE_MAP = {
+    'permission.required': {
+      title: 'Action Required',
+      body: event.meta?.toolName
+        ? `Tool "${event.meta.toolName}" needs approval`
+        : 'A tool needs your approval'
+    },
+    'run.stopped': {
+      title: 'Run Stopped',
+      body: event.meta?.stopReason || 'The run has stopped'
+    },
+    'run.failed': {
+      title: 'Run Failed',
+      body: event.meta?.error ? String(event.meta.error) : 'The run encountered an error'
+    },
+    'agent.notification': {
+      title: 'Agent Notification',
+      body: event.meta?.message ? String(event.meta.message) : 'You have a new notification'
+    }
+  };
+
+  const mapped = CODE_MAP[event.code];
+  return {
+    title: mapped?.title || 'Claude Code UI',
+    body: mapped?.body || 'You have a new notification',
+    data: {
+      sessionId: event.sessionId || null,
+      code: event.code
+    }
+  };
+}
+
+async function sendWebPush(userId, event) {
+  const subscriptions = pushSubscriptionsDb.getSubscriptions(userId);
+  if (!subscriptions.length) return;
+
+  const payload = JSON.stringify(buildPushBody(event));
+
+  const results = await Promise.allSettled(
+    subscriptions.map((sub) =>
+      webPush.sendNotification(
+        {
+          endpoint: sub.endpoint,
+          keys: {
+            p256dh: sub.keys_p256dh,
+            auth: sub.keys_auth
+          }
+        },
+        payload
+      )
+    )
+  );
+
+  // Clean up gone subscriptions (410 Gone or 404)
+  results.forEach((result, index) => {
+    if (result.status === 'rejected') {
+      const statusCode = result.reason?.statusCode;
+      if (statusCode === 410 || statusCode === 404) {
+        pushSubscriptionsDb.removeSubscription(subscriptions[index].endpoint);
+      }
+    }
+  });
+}
+
+function notifyUserIfEnabled({ userId, event }) {
+  if (!userId || !event) {
+    return;
+  }
+
+  const preferences = notificationPreferencesDb.getPreferences(userId);
+  if (!shouldSendPush(preferences, event)) {
+    return;
+  }
+  if (isDuplicate(event)) {
+    return;
+  }
+
+  sendWebPush(userId, event).catch((err) => {
+    console.error('Web push send error:', err);
+  });
+}
+
+export {
+  createNotificationEvent,
+  notifyUserIfEnabled
+};

server/services/vapid-keys.js

@@ -0,0 +1,35 @@
+import webPush from 'web-push';
+import { db } from '../database/db.js';
+
+let cachedKeys = null;
+
+function ensureVapidKeys() {
+  if (cachedKeys) return cachedKeys;
+
+  const row = db.prepare('SELECT public_key, private_key FROM vapid_keys ORDER BY id DESC LIMIT 1').get();
+  if (row) {
+    cachedKeys = { publicKey: row.public_key, privateKey: row.private_key };
+    return cachedKeys;
+  }
+
+  const keys = webPush.generateVAPIDKeys();
+  db.prepare('INSERT INTO vapid_keys (public_key, private_key) VALUES (?, ?)').run(keys.publicKey, keys.privateKey);
+  cachedKeys = keys;
+  return cachedKeys;
+}
+
+function getPublicKey() {
+  return ensureVapidKeys().publicKey;
+}
+
+function configureWebPush() {
+  const keys = ensureVapidKeys();
+  webPush.setVapidDetails(
+    'mailto:noreply@claudecodeui.local',
+    keys.publicKey,
+    keys.privateKey
+  );
+  console.log('Web Push notifications configured');
+}
+
+export { ensureVapidKeys, getPublicKey, configureWebPush };