claude-mpm 4.1.8__py3-none-any.whl → 4.1.11__py3-none-any.whl

claude_mpm/dashboard/static/js/socket-client.js

@@ -1,74 +1,303 @@
 /**
  * Socket.IO Client for Claude MPM Dashboard
- * Handles WebSocket connections and event processing
+ * 
+ * This module provides real-time WebSocket communication between the Claude MPM dashboard
+ * and the backend Socket.IO server. It handles connection management, event processing,
+ * retry logic, and health monitoring.
+ * 
+ * Architecture:
+ * - Maintains persistent WebSocket connection to Claude MPM backend
+ * - Implements robust retry logic with exponential backoff
+ * - Provides event queuing during disconnections
+ * - Validates event schemas for data integrity
+ * - Monitors connection health with ping/pong mechanisms
+ * 
+ * Event Flow:
+ * 1. Events from Claude Code hooks → Socket.IO server → Dashboard client
+ * 2. Dashboard requests → Socket.IO server → Backend services
+ * 3. Status updates → Socket.IO server → All connected clients
+ * 
+ * Thread Safety:
+ * - Single-threaded JavaScript execution model ensures safety
+ * - Event callbacks are queued and executed sequentially
+ * - Connection state changes are atomic
+ * 
+ * Performance Considerations:
+ * - Event queue limited to 100 items to prevent memory leaks
+ * - Health checks run every 45s to match server ping interval
+ * - Exponential backoff prevents connection spam
+ * - Lazy event validation reduces overhead
+ * 
+ * Security:
+ * - Connects only to localhost to prevent external access
+ * - Event schema validation prevents malformed data processing
+ * - Connection timeout prevents hanging connections
+ * 
+ * @author Claude MPM Team
+ * @version 1.0
+ * @since v4.0.25
  */
 
 // Access the global io from window object in ES6 module context
+// WHY: Socket.IO is loaded via CDN in HTML, available as window.io
 const io = window.io;
 
+/**
+ * Primary Socket.IO client for dashboard communication.
+ * 
+ * Manages WebSocket connection lifecycle, event processing, and error handling.
+ * Implements connection resilience with automatic retry and health monitoring.
+ * 
+ * Key Features:
+ * - Automatic connection retry with exponential backoff
+ * - Event queue management during disconnections  
+ * - Schema validation for incoming events
+ * - Health monitoring with ping/pong
+ * - Session management and event history
+ * 
+ * Connection States:
+ * - isConnected: Currently connected to server
+ * - isConnecting: Connection attempt in progress
+ * - disconnectTime: Timestamp of last disconnection
+ * 
+ * Event Processing:
+ * - Validates against schema before processing
+ * - Queues events during disconnection (max 100)
+ * - Maintains event history and session tracking
+ * 
+ * @class SocketClient
+ */
 class SocketClient {
+    /**
+     * Initialize Socket.IO client with default configuration.
+     * 
+     * Sets up connection management, event processing, and health monitoring.
+     * Configures retry logic and event queue management.
+     * 
+     * WHY this initialization approach:
+     * - Lazy socket creation allows for port specification
+     * - Event queue prevents data loss during reconnections
+     * - Health monitoring detects server issues early
+     * - Schema validation ensures data integrity
+     * 
+     * @constructor
+     */
     constructor() {
+        /**
+         * Socket.IO connection instance.
+         * @type {Socket|null}
+         * @private
+         */
         this.socket = null;
+        
+        /**
+         * Current connection port.
+         * @type {string|null}
+         * @private
+         */
         this.port = null; // Store the current port
+        
+        /**
+         * Event callback registry for connection lifecycle events.
+         * WHY: Allows multiple components to register for connection events.
+         * @type {Object.<string, Function[]>}
+         * @private
+         */
         this.connectionCallbacks = {
-            connect: [],
-            disconnect: [],
-            error: [],
-            event: []
+            connect: [],    // Called on successful connection
+            disconnect: [], // Called on disconnection  
+            error: [],      // Called on connection errors
+            event: []       // Called on incoming events
         };
         
-        // Event schema validation
+        /**
+         * Event schema definition for validation.
+         * WHY: Ensures data integrity and prevents processing malformed events.
+         * @type {Object}
+         * @private
+         */
         this.eventSchema = {
             required: ['source', 'type', 'subtype', 'timestamp', 'data'],
             optional: ['event', 'session_id']
         };
 
-        // Connection state
+        /**
+         * Current connection state.
+         * @type {boolean}
+         * @private
+         */
         this.isConnected = false;
+        
+        /**
+         * Connection attempt in progress flag.
+         * WHY: Prevents multiple simultaneous connection attempts.
+         * @type {boolean}
+         * @private
+         */
         this.isConnecting = false;
+        
+        /**
+         * Timestamp of last successful connection.
+         * @type {number|null}
+         * @private
+         */
         this.lastConnectTime = null;
+        
+        /**
+         * Timestamp of last disconnection.
+         * WHY: Used to calculate downtime and trigger reconnection logic.
+         * @type {number|null}
+         * @private
+         */
         this.disconnectTime = null;
 
-        // Event processing
+        /**
+         * Event history storage.
+         * WHY: Maintains event history for dashboard display and analysis.
+         * @type {Array.<Object>}
+         * @private
+         */
         this.events = [];
+        
+        /**
+         * Session tracking map.
+         * WHY: Groups events by session for better organization.
+         * @type {Map<string, Object>}
+         * @private
+         */
         this.sessions = new Map();
+        
+        /**
+         * Current active session identifier.
+         * @type {string|null}
+         * @private
+         */
         this.currentSessionId = null;
 
-        // Event queue for disconnection periods
+        /**
+         * Event queue for disconnection periods.
+         * WHY: Prevents event loss during temporary disconnections.
+         * @type {Array.<Object>}
+         * @private
+         */
         this.eventQueue = [];
+        
+        /**
+         * Maximum queue size to prevent memory leaks.
+         * WHY: Limits memory usage during extended disconnections.
+         * @type {number}
+         * @private
+         * @const
+         */
         this.maxQueueSize = 100;
         
-        // Retry configuration - Match server settings
+        /**
+         * Current retry attempt counter.
+         * WHY: Tracks retry attempts for exponential backoff logic.
+         * @type {number}
+         * @private
+         */
         this.retryAttempts = 0;
+        
+        /**
+         * Maximum retry attempts before giving up.
+         * WHY: Prevents infinite retry loops that could impact performance.
+         * @type {number}
+         * @private
+         * @const
+         */
         this.maxRetryAttempts = 5;  // Increased from 3 to 5 for better stability
+        
+        /**
+         * Retry delay intervals in milliseconds (exponential backoff).
+         * WHY: Prevents server overload during connection issues.
+         * @type {number[]}
+         * @private
+         * @const
+         */
         this.retryDelays = [1000, 2000, 3000, 4000, 5000]; // Exponential backoff with 5 attempts
+        
+        /**
+         * Map of pending emissions for retry logic.
+         * WHY: Tracks failed emissions that need to be retried.
+         * @type {Map<string, Object>}
+         * @private
+         */
         this.pendingEmissions = new Map(); // Track pending emissions for retry
         
-        // Health monitoring
+        /**
+         * Timestamp of last ping sent to server.
+         * WHY: Used for health monitoring and connection validation.
+         * @type {number|null}
+         * @private
+         */
         this.lastPingTime = null;
+        
+        /**
+         * Timestamp of last pong received from server.
+         * WHY: Confirms server is responsive and connection is healthy.
+         * @type {number|null}
+         * @private
+         */
         this.lastPongTime = null;
+        
+        /**
+         * Health check timeout in milliseconds.
+         * WHY: More lenient than Socket.IO timeout to prevent false positives.
+         * @type {number}
+         * @private
+         * @const
+         */
         this.pingTimeout = 90000; // 90 seconds for health check (more lenient than Socket.IO timeout)
+        
+        /**
+         * Health check interval timer.
+         * @type {number|null}
+         * @private
+         */
         this.healthCheckInterval = null;
         
-        // Start periodic status check as fallback mechanism
+        // Initialize background monitoring
         this.startStatusCheckFallback();
         this.startHealthMonitoring();
     }
 
     /**
-     * Connect to Socket.IO server
-     * @param {string} port - Port number to connect to
+     * Connect to Socket.IO server on specified port.
+     * 
+     * Initiates WebSocket connection to the Claude MPM Socket.IO server.
+     * Handles connection conflicts and ensures clean state transitions.
+     * 
+     * Connection Process:
+     * 1. Validates port and constructs localhost URL
+     * 2. Checks for existing connections and cleans up if needed
+     * 3. Delegates to doConnect() for actual connection logic
+     * 
+     * Thread Safety:
+     * - Uses setTimeout for async cleanup to prevent race conditions
+     * - Connection state flags prevent multiple simultaneous attempts
+     * 
+     * @param {string} [port='8765'] - Port number to connect to (defaults to 8765)
+     * 
+     * @throws {Error} If Socket.IO library is not loaded
+     * 
+     * @example
+     * // Connect to default port
+     * socketClient.connect();
+     * 
+     * // Connect to specific port
+     * socketClient.connect('8766');
      */
     connect(port = '8765') {
-        // Store the port for later use
+        // Store the port for later use in reconnections
         this.port = port;
         const url = `http://localhost:${port}`;
 
-        // Prevent multiple simultaneous connections
+        // WHY this check: Prevents connection conflicts that can cause memory leaks
         if (this.socket && (this.socket.connected || this.socket.connecting)) {
             console.log('Already connected or connecting, disconnecting first...');
             this.socket.disconnect();
-            // Wait a moment for cleanup
+            // WHY 100ms delay: Allows cleanup to complete before new connection
             setTimeout(() => this.doConnect(url), 100);
             return;
         }
@@ -77,8 +306,28 @@ class SocketClient {
     }
 
     /**
-     * Perform the actual connection
-     * @param {string} url - Socket.IO server URL
+     * Execute the actual Socket.IO connection with full configuration.
+     * 
+     * Creates and configures Socket.IO client with appropriate timeouts,
+     * retry logic, and transport settings. Sets up event handlers for
+     * connection lifecycle management.
+     * 
+     * Configuration Details:
+     * - autoConnect: true - Immediate connection attempt
+     * - reconnection: true - Built-in reconnection enabled
+     * - pingInterval: 45000ms - Matches server configuration
+     * - pingTimeout: 20000ms - Health check timeout
+     * - transports: ['websocket', 'polling'] - Fallback options
+     * 
+     * WHY these settings:
+     * - Ping intervals must match server to prevent timeouts
+     * - Limited reconnection attempts prevent infinite loops
+     * - forceNew prevents socket reuse issues
+     * 
+     * @param {string} url - Complete Socket.IO server URL (http://localhost:port)
+     * @private
+     * 
+     * @throws {Error} If Socket.IO library is not available
      */
     doConnect(url) {
         console.log(`Connecting to Socket.IO server at ${url}`);
@@ -132,6 +381,10 @@ class SocketClient {
             
             this.notifyConnectionStatus('Connected', 'connected');
 
+            // Expose socket globally for components that need direct access
+            window.socket = this.socket;
+            console.log('SocketClient: Exposed socket globally as window.socket');
+
             // Emit connect callback
             this.connectionCallbacks.connect.forEach(callback =>
                 callback(this.socket.id)
@@ -222,6 +475,12 @@ class SocketClient {
                 return;
             }
             
+            // Code analysis events are now allowed to flow through to the events list for troubleshooting
+            // They will appear in both the Events tab and the Code tab
+            if (validatedEvent.type && validatedEvent.type.startsWith('code:')) {
+                console.log('Code analysis event received via claude_event, adding to events list for troubleshooting:', validatedEvent.type);
+            }
+            
             // Transform event to match expected format (for backward compatibility)
             const transformedEvent = this.transformEvent(validatedEvent);
             console.log('Transformed event:', transformedEvent);
@@ -291,6 +550,57 @@ class SocketClient {
             this.addEvent({ type: 'log', subtype: 'entry', timestamp: new Date().toISOString(), data });
         });
 
+        // Code analysis events - now allowed to flow through for troubleshooting
+        // These are ALSO handled by the code-tree component and shown in the footer
+        // They will appear in both places: Events tab (for troubleshooting) and Code tab (for visualization)
+        this.socket.on('code:analysis:queued', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code analysis queued event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'analysis:queued', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:analysis:accepted', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code analysis accepted event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'analysis:accepted', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:analysis:start', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code analysis start event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'analysis:start', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:analysis:complete', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code analysis complete event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'analysis:complete', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:analysis:error', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code analysis error event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'analysis:error', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:file:start', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code file start event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'file:start', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:node:found', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code node found event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'node:found', timestamp: new Date().toISOString(), data });
+        });
+        
+        this.socket.on('code:analysis:progress', (data) => {
+            // Add to events list for troubleshooting
+            console.log('Code analysis progress event received, adding to events list for troubleshooting');
+            this.addEvent({ type: 'code', subtype: 'analysis:progress', timestamp: new Date().toISOString(), data });
+        });
+
         this.socket.on('history', (data) => {
             console.log('Received event history:', data);
             if (data && Array.isArray(data.events)) {
@@ -528,12 +838,44 @@ class SocketClient {
                     id: sessionId,
                     startTime: eventData.timestamp,
                     lastActivity: eventData.timestamp,
-                    eventCount: 0
+                    eventCount: 0,
+                    working_directory: null,
+                    git_branch: null
                 });
             }
             const session = this.sessions.get(sessionId);
             session.lastActivity = eventData.timestamp;
             session.eventCount++;
+            
+            // Extract working directory from event data if available (prioritize newer data)
+            // Check multiple possible locations for working directory
+            const possiblePaths = [
+                eventData.data.cwd,
+                eventData.data.working_directory,
+                eventData.data.working_dir,
+                eventData.data.workingDirectory,
+                eventData.data.instance_info?.working_dir,
+                eventData.data.instance_info?.working_directory,
+                eventData.data.instance_info?.cwd,
+                eventData.cwd,
+                eventData.working_directory,
+                eventData.working_dir
+            ];
+            
+            for (const path of possiblePaths) {
+                if (path && typeof path === 'string' && path.trim()) {
+                    session.working_directory = path;
+                    console.log(`[SOCKET-CLIENT] Found working directory for session ${sessionId}:`, path);
+                    break;
+                }
+            }
+            
+            // Extract git branch if available
+            if (eventData.data.git_branch) {
+                session.git_branch = eventData.data.git_branch;
+            } else if (eventData.data.instance_info && eventData.data.instance_info.git_branch) {
+                session.git_branch = eventData.data.instance_info.git_branch;
+            }
         }
 
         if (notify) {
@@ -604,6 +946,32 @@ class SocketClient {
         this.connectionCallbacks.event.push(callback);
     }
 
+    /**
+     * Subscribe to socket events (proxy to underlying socket)
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function
+     */
+    on(event, callback) {
+        if (this.socket) {
+            return this.socket.on(event, callback);
+        } else {
+            console.warn(`Cannot subscribe to '${event}': socket not initialized`);
+        }
+    }
+
+    /**
+     * Unsubscribe from socket events (proxy to underlying socket)
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function (optional)
+     */
+    off(event, callback) {
+        if (this.socket) {
+            return this.socket.off(event, callback);
+        } else {
+            console.warn(`Cannot unsubscribe from '${event}': socket not initialized`);
+        }
+    }
+
     /**
      * Notify connection status change
      * @param {string} status - Status message
@@ -722,6 +1090,7 @@ class SocketClient {
         // 1. Hook events: { type: 'hook.pre_tool', timestamp: '...', data: {...} }
         // 2. Legacy events: { event: 'TestStart', timestamp: '...', ... }
         // 3. Standard events: { type: 'session', subtype: 'started', ... }
+        // 4. Normalized events: { type: 'code', subtype: 'progress', ... } - already normalized, keep as-is
 
         if (!eventData) {
             return eventData; // Return as-is if null/undefined
@@ -729,8 +1098,26 @@ class SocketClient {
 
         let transformedEvent = { ...eventData };
 
+        // Check if event is already normalized (has both type and subtype as separate fields)
+        // This prevents double-transformation of events that were normalized on the backend
+        const isAlreadyNormalized = eventData.type && eventData.subtype && 
+                                   !eventData.type.includes('.') && 
+                                   !eventData.type.includes(':');
+
+        if (isAlreadyNormalized) {
+            // Event is already properly normalized from backend, just preserve it
+            // Store a composite originalEventName for display if needed
+            if (!transformedEvent.originalEventName) {
+                if (eventData.subtype === 'generic' || eventData.type === eventData.subtype) {
+                    transformedEvent.originalEventName = eventData.type;
+                } else {
+                    transformedEvent.originalEventName = `${eventData.type}.${eventData.subtype}`;
+                }
+            }
+            // Return early to avoid further transformation
+        }
         // Handle legacy format with 'event' field but no 'type'
-        if (!eventData.type && eventData.event) {
+        else if (!eventData.type && eventData.event) {
             // Map common event names to proper type/subtype
             const eventName = eventData.event;
             
@@ -761,8 +1148,10 @@ class SocketClient {
             
             // Remove the 'event' field to avoid confusion
             delete transformedEvent.event;
+            // Store original event name for display purposes
+            transformedEvent.originalEventName = eventName;
         }
-        // Handle standard format with 'type' field
+        // Handle standard format with 'type' field that needs transformation
         else if (eventData.type) {
             const type = eventData.type;
             
@@ -771,25 +1160,43 @@ class SocketClient {
                 const subtype = type.substring(5); // Remove 'hook.' prefix
                 transformedEvent.type = 'hook';
                 transformedEvent.subtype = subtype;
+                transformedEvent.originalEventName = type;
+            }
+            // Transform 'code:*' events to proper code type
+            // Handle multi-level subtypes like 'code:analysis:queued'
+            else if (type.startsWith('code:')) {
+                transformedEvent.type = 'code';
+                // Replace colons with underscores in subtype for consistency
+                const subtypePart = type.substring(5); // Remove 'code:' prefix
+                transformedEvent.subtype = subtypePart.replace(/:/g, '_');
+                transformedEvent.originalEventName = type;
             }
             // Transform other dotted types like 'session.started' -> type: 'session', subtype: 'started'
             else if (type.includes('.')) {
                 const [mainType, ...subtypeParts] = type.split('.');
                 transformedEvent.type = mainType;
                 transformedEvent.subtype = subtypeParts.join('.');
+                transformedEvent.originalEventName = type;
+            }
+            // Transform any remaining colon-separated types generically
+            else if (type.includes(':')) {
+                const parts = type.split(':', 2); // Split into max 2 parts
+                transformedEvent.type = parts[0];
+                // Replace any remaining colons with underscores in subtype
+                transformedEvent.subtype = parts.length > 1 ? parts[1].replace(/:/g, '_') : 'generic';
+                transformedEvent.originalEventName = type;
+            }
+            // If type doesn't need transformation but has no subtype, set a default
+            else if (!eventData.subtype) {
+                transformedEvent.subtype = 'generic';
+                transformedEvent.originalEventName = type;
             }
         }
         // If no type and no event field, mark as unknown
         else {
             transformedEvent.type = 'unknown';
             transformedEvent.subtype = '';
-        }
-
-        // Store original event name for display purposes (before any transformation)
-        if (!eventData.type && eventData.event) {
-            transformedEvent.originalEventName = eventData.event;
-        } else if (eventData.type) {
-            transformedEvent.originalEventName = eventData.type;
+            transformedEvent.originalEventName = 'unknown';
         }
 
         // Extract and flatten data fields to top level for dashboard compatibility
@@ -820,11 +1227,40 @@ class SocketClient {
             transformedEvent.data = eventData.data;
         }
 
+        // Add hook_event_name for ActivityTree compatibility
+        // Map the type/subtype structure to the expected hook_event_name format
+        if (transformedEvent.type === 'hook') {
+            if (transformedEvent.subtype === 'pre_tool') {
+                transformedEvent.hook_event_name = 'PreToolUse';
+            } else if (transformedEvent.subtype === 'post_tool') {
+                transformedEvent.hook_event_name = 'PostToolUse';
+            } else if (transformedEvent.subtype === 'subagent_start') {
+                transformedEvent.hook_event_name = 'SubagentStart';
+            } else if (transformedEvent.subtype === 'subagent_stop') {
+                transformedEvent.hook_event_name = 'SubagentStop';
+            } else if (transformedEvent.subtype === 'todo_write') {
+                transformedEvent.hook_event_name = 'TodoWrite';
+            } else if (transformedEvent.subtype === 'start') {
+                transformedEvent.hook_event_name = 'Start';
+            } else if (transformedEvent.subtype === 'stop') {
+                transformedEvent.hook_event_name = 'Stop';
+            }
+        } else if (transformedEvent.type === 'subagent') {
+            if (transformedEvent.subtype === 'start') {
+                transformedEvent.hook_event_name = 'SubagentStart';
+            } else if (transformedEvent.subtype === 'stop') {
+                transformedEvent.hook_event_name = 'SubagentStop';
+            }
+        } else if (transformedEvent.type === 'todo' && transformedEvent.subtype === 'updated') {
+            transformedEvent.hook_event_name = 'TodoWrite';
+        }
+
         // Debug logging for tool events
         if (transformedEvent.type === 'hook' && (transformedEvent.subtype === 'pre_tool' || transformedEvent.subtype === 'post_tool')) {
             console.log('Transformed tool event:', {
                 type: transformedEvent.type,
                 subtype: transformedEvent.subtype,
+                hook_event_name: transformedEvent.hook_event_name,
                 tool_name: transformedEvent.tool_name,
                 has_tool_parameters: !!transformedEvent.tool_parameters,
                 tool_parameters: transformedEvent.tool_parameters,