ai-or-die 0.1.18 → 0.1.19

package/docs/specs/client-app.md

@@ -104,6 +104,7 @@ The main application controller. Instantiated once on page load.
 - **Connection:** Constructs the URL with the session token via `authManager.getWebSocketUrl()`. Reconnects automatically with exponential backoff up to `maxReconnectAttempts`.
 - **Message handling:** Routes incoming messages by `type` field to appropriate handlers (output rendering, session state updates, usage updates, etc.).
 - **Output rendering:** Writes raw terminal data directly to xterm.js via `terminal.write(data)`. Also feeds data to `planDetector.processOutput(data)` and `sessionTabManager.markSessionActivity()`.
+- **Background session events:** Handles `session_activity`, `session_exit`, `session_error`, `session_started`, and `session_stopped` messages for sessions the client is not actively joined to. These update tab status indicators and feed the notification idle timer. These handlers never modify the terminal or show overlays — they only interact with `SessionTabManager`.
 
 ### Terminal Configuration
 
@@ -240,10 +241,12 @@ When a session transitions from `active` to `idle` in a background tab (not the
 
 - Requests permission on first load (deferred by 2 seconds).
 - Shows a prompt banner if permission is `"default"`.
-- Sends `Notification` when the page is not visible and the event is for a background tab.
+- Sends desktop `Notification` when the page is **not visible** and the event is for a background tab.
+- When the page **is visible** but the event is for a different session tab, shows an in-app toast notification instead of a desktop notification.
 - Falls back to in-page toast notifications + vibration on mobile.
 - Notifications auto-close after 5 seconds.
 - Clicking a notification switches to the relevant tab and focuses the window.
+- Receives lightweight `session_activity` events from the server for sessions the client is not joined to, enabling idle detection and notifications for background tabs without requiring full terminal output.
 
 ### Keyboard Shortcuts
 

package/docs/specs/server.md

@@ -37,6 +37,7 @@ new ClaudeCodeWebServer(options)
 | `sessionStore` | `SessionStore` | Persistence layer for session data |
 | `usageReader` | `UsageReader` | Reads JSONL usage logs from `~/.claude/projects/` |
 | `usageAnalytics` | `UsageAnalytics` | Calculates burn rate, predictions, plan limits |
+| `activityBroadcastTimestamps` | `Map<string, number>` | Per-session throttle timestamps for activity broadcasts |
 | `selectedWorkingDir` | string \| null | Currently selected working directory via folder browser |
 | `baseFolder` | string | `process.cwd()` at startup -- root for path validation |
 | `isShuttingDown` | boolean | Prevents duplicate shutdown sequences |
@@ -250,11 +251,18 @@ All messages are JSON. The `type` field determines the handler.
 | `info` | Informational message (e.g., "No agent is running"). |
 | `pong` | Response to `ping`. |
 | `usage_update` | Usage statistics payload (see Usage Analytics spec). |
+| `session_activity` | Lightweight notification sent to connections NOT joined to the session, indicating new output. Fields: `sessionId`, `sessionName`. Throttled to 1/second per session. |
+| `session_exit` | Sent to non-joined connections when agent exits. Fields: `sessionId`, `sessionName`, `code`, `signal`. |
+| `session_error` | Sent to non-joined connections on error. Fields: `sessionId`, `sessionName`. |
+| `session_started` | Sent to non-joined connections when a tool starts. Fields: `sessionId`, `sessionName`, `agent`. |
+| `session_stopped` | Sent to non-joined connections when a tool stops. Fields: `sessionId`, `sessionName`, `agent`. |
 
 ### Broadcasting
 
 `broadcastToSession(sessionId, data)` iterates the session's `connections` Set, verifies each WebSocket is open and belongs to the correct session, then sends the JSON-serialized message.
 
+`broadcastSessionActivity(sessionId, eventType, extraData)` sends a lightweight event to all WebSocket connections that are NOT joined to the specified session. This enables clients to track activity in background sessions for notification purposes without receiving full terminal output. Events use a `session_` prefix to distinguish cross-session events from in-session events (which are unprefixed like `output`, `exit`). The `session_activity` event is throttled to at most once per second per session to avoid flooding during high-output scenarios.
+
 ---
 
 ## Session Management

package/e2e/playwright.config.js

@@ -33,7 +33,7 @@ module.exports = defineConfig({
     },
     {
       name: 'functional',
-      testMatch: /0[2-7]-.*\.spec\.js/,
+      testMatch: /0[2-7]-.*\.spec\.js|09-background-.*\.spec\.js/,
     },
     {
       name: 'mobile-iphone',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {

package/src/public/app.js

@@ -823,6 +823,49 @@ class ClaudeCodeWebInterface {
                 );
                 break;
                 
+            // Background session activity events (from broadcastSessionActivity)
+            // These handlers must never touch this.terminal or this.showOverlay
+            case 'session_activity':
+                if (this.sessionTabManager && message.sessionId &&
+                    message.sessionId !== this.currentClaudeSessionId) {
+                    this.sessionTabManager.markSessionActivity(message.sessionId, true, '');
+                }
+                break;
+
+            case 'session_exit':
+                if (this.sessionTabManager && message.sessionId &&
+                    message.sessionId !== this.currentClaudeSessionId) {
+                    if (message.code !== 0) {
+                        this.sessionTabManager.markSessionError(message.sessionId, true);
+                    }
+                    this.sessionTabManager.updateTabStatus(message.sessionId, 'idle');
+                }
+                this.loadSessions();
+                break;
+
+            case 'session_error':
+                if (this.sessionTabManager && message.sessionId &&
+                    message.sessionId !== this.currentClaudeSessionId) {
+                    this.sessionTabManager.markSessionError(message.sessionId, true);
+                }
+                break;
+
+            case 'session_started':
+                if (this.sessionTabManager && message.sessionId &&
+                    message.sessionId !== this.currentClaudeSessionId) {
+                    this.sessionTabManager.updateTabStatus(message.sessionId, 'active');
+                }
+                this.loadSessions();
+                break;
+
+            case 'session_stopped':
+                if (this.sessionTabManager && message.sessionId &&
+                    message.sessionId !== this.currentClaudeSessionId) {
+                    this.sessionTabManager.updateTabStatus(message.sessionId, 'idle');
+                }
+                this.loadSessions();
+                break;
+
             default:
                 console.log('Unknown message type:', message.type);
         }

package/src/public/index.html

@@ -426,7 +426,7 @@
                             newWorker.addEventListener('statechange', () => {
                                 if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
                                     // New service worker available, prompt user to refresh
-                                    if (confirm('A new version of Claude Code Web is available. Refresh to update?')) {
+                                    if (confirm('A new version of ai-or-die is available. Refresh to update?')) {
                                         newWorker.postMessage({ type: 'SKIP_WAITING' });
                                         window.location.reload();
                                     }

package/src/public/session-manager.js

@@ -7,6 +7,7 @@ class SessionTabManager {
         this.tabOrder = []; // visual order of tabs
         this.tabHistory = []; // most recently used order
         this.notificationsEnabled = false;
+        this.idleTimeoutMs = 90000;
         this.requestNotificationPermission();
     }
 
@@ -44,36 +45,35 @@ class SessionTabManager {
     sendNotification(title, body, sessionId) {
         // Don't send notification for active tab
         if (sessionId === this.activeTabId) return;
-        
-        // Only send notifications if the page is not visible
-        if (document.visibilityState === 'visible') return;
-        
-        // Try desktop notifications first (won't work on iOS Safari)
-        if ('Notification' in window && Notification.permission === 'granted') {
-            try {
-                const notification = new Notification(title, {
-                    body: body,
-                    icon: '/favicon.ico',
-                    tag: sessionId,
-                    requireInteraction: false,
-                    silent: false
-                });
-                
-                notification.onclick = () => {
-                    window.focus();
-                    this.switchToTab(sessionId);
-                    notification.close();
-                };
-                
-                setTimeout(() => notification.close(), 5000);
-                console.log(`Desktop notification sent: ${title}`);
-                return; // Exit if desktop notification worked
-            } catch (error) {
-                console.error('Desktop notification failed:', error);
+
+        // Try desktop notifications when the page is not visible
+        if (document.visibilityState !== 'visible') {
+            if ('Notification' in window && Notification.permission === 'granted') {
+                try {
+                    const notification = new Notification(title, {
+                        body: body,
+                        icon: '/favicon.ico',
+                        tag: sessionId,
+                        requireInteraction: false,
+                        silent: false
+                    });
+
+                    notification.onclick = () => {
+                        window.focus();
+                        this.switchToTab(sessionId);
+                        notification.close();
+                    };
+
+                    setTimeout(() => notification.close(), 5000);
+                    console.log(`Desktop notification sent: ${title}`);
+                    return; // Desktop notification succeeded; no need for in-app toast
+                } catch (error) {
+                    console.error('Desktop notification failed:', error);
+                }
             }
         }
-        
-        // Fallback for mobile: Use visual + audio/vibration
+
+        // In-app toast: show for background tabs even when page is visible
         this.showMobileNotification(title, body, sessionId);
     }
     
@@ -780,6 +780,13 @@ class SessionTabManager {
         const orderedIds = this.getOrderedTabIds();
         const closedIndex = orderedIds.indexOf(sessionId);
 
+        // Clear any pending notification timers before removing session data
+        const session = this.activeSessions.get(sessionId);
+        if (session) {
+            clearTimeout(session.idleTimeout);
+            clearTimeout(session.workCompleteTimeout);
+        }
+
         // Remove tab
         tab.remove();
         this.tabs.delete(sessionId);
@@ -1032,7 +1039,7 @@ class SessionTabManager {
                         }
                     }
                 }
-            }, 90000); // 90 seconds
+            }, this.idleTimeoutMs);
             
             // Keep the original 5-minute timeout for full idle state
             session.idleTimeout = setTimeout(() => {

package/src/server.js

@@ -46,6 +46,7 @@ class ClaudeCodeWebServer {
       customCostLimit: parseFloat(process.env.CLAUDE_COST_LIMIT || options.customCostLimit || 50.00)
     });
     this.autoSaveInterval = null;
+    this.activityBroadcastTimestamps = new Map(); // sessionId -> last broadcast timestamp
     this.startTime = Date.now(); // Track server start time
     this.isShuttingDown = false; // Flag to prevent duplicate shutdown
     // Commands dropdown removed
@@ -372,6 +373,7 @@ class ClaudeCodeWebServer {
       });
       
       this.claudeSessions.delete(sessionId);
+      this.activityBroadcastTimestamps.delete(sessionId);
 
       // Save sessions after deletion — await to ensure persistence
       await this.saveSessionsToDisk();
@@ -1036,6 +1038,13 @@ class ClaudeCodeWebServer {
             currentSession.outputBuffer.shift();
           }
           this.broadcastToSession(sessionId, { type: 'output', data });
+          // Notify non-joined connections about activity (throttled to 1/sec)
+          const now = Date.now();
+          const lastBroadcast = this.activityBroadcastTimestamps.get(sessionId) || 0;
+          if (now - lastBroadcast > 1000) {
+            this.activityBroadcastTimestamps.set(sessionId, now);
+            this.broadcastSessionActivity(sessionId, 'session_activity');
+          }
         },
         onExit: (code, signal) => {
           const currentSession = this.claudeSessions.get(sessionId);
@@ -1044,6 +1053,8 @@ class ClaudeCodeWebServer {
             currentSession.agent = null;
           }
           this.broadcastToSession(sessionId, { type: 'exit', code, signal });
+          this.activityBroadcastTimestamps.delete(sessionId);
+          this.broadcastSessionActivity(sessionId, 'session_exit', { code, signal });
         },
         onError: (error) => {
           const currentSession = this.claudeSessions.get(sessionId);
@@ -1052,6 +1063,7 @@ class ClaudeCodeWebServer {
             currentSession.agent = null;
           }
           this.broadcastToSession(sessionId, { type: 'error', message: error.message });
+          this.broadcastSessionActivity(sessionId, 'session_error');
         },
         ...options
       });
@@ -1067,6 +1079,7 @@ class ClaudeCodeWebServer {
         type: `${toolName}_started`,
         sessionId: sessionId
       });
+      this.broadcastSessionActivity(sessionId, 'session_started', { agent: toolName });
 
     } catch (error) {
       if (this.dev) {
@@ -1093,6 +1106,8 @@ class ClaudeCodeWebServer {
     session.agent = null;
     session.lastActivity = new Date();
     this.broadcastToSession(sessionId, { type: `${agentType}_stopped` });
+    this.activityBroadcastTimestamps.delete(sessionId);
+    this.broadcastSessionActivity(sessionId, 'session_stopped', { agent: agentType });
   }
 
   sendToWebSocket(ws, data) {
@@ -1108,14 +1123,27 @@ class ClaudeCodeWebServer {
     session.connections.forEach(wsId => {
       const wsInfo = this.webSocketConnections.get(wsId);
       // Double-check that this WebSocket is actually part of this session
-      if (wsInfo && 
-          wsInfo.claudeSessionId === claudeSessionId && 
+      if (wsInfo &&
+          wsInfo.claudeSessionId === claudeSessionId &&
           wsInfo.ws.readyState === WebSocket.OPEN) {
         this.sendToWebSocket(wsInfo.ws, data);
       }
     });
   }
 
+  // Sends a lightweight event to all WebSocket connections that are NOT joined
+  // to the specified session. This enables clients to track activity in background
+  // sessions for notification purposes without receiving full terminal output.
+  broadcastSessionActivity(sessionId, eventType, extraData = {}) {
+    const session = this.claudeSessions.get(sessionId);
+    const sessionName = session ? session.name : '';
+    this.webSocketConnections.forEach((wsInfo, wsId) => {
+      if (wsInfo.claudeSessionId === sessionId) return;
+      if (wsInfo.ws.readyState !== WebSocket.OPEN) return;
+      this.sendToWebSocket(wsInfo.ws, { type: eventType, sessionId, sessionName, ...extraData });
+    });
+  }
+
   cleanupWebSocketConnection(wsId) {
     const wsInfo = this.webSocketConnections.get(wsId);
     if (!wsInfo) return;