claude-mpm 4.0.3__py3-none-any.whl → 4.0.4__py3-none-any.whl

claude_mpm/services/port_manager.py

@@ -8,17 +8,28 @@ Ensures only one instance runs per port and provides fallback port selection.
 
 import json
 import os
+import signal
 import socket
 import subprocess
 import time
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple, NamedTuple
 
 import psutil
 
 from ..core.logging_config import get_logger
 
 
+class ProcessInfo(NamedTuple):
+    """Information about a process using a port."""
+    pid: int
+    name: str
+    cmdline: str
+    is_ours: bool
+    is_debug: bool
+    is_daemon: bool
+
+
 class PortManager:
     """Manages port allocation and instance detection for SocketIO servers."""
 
@@ -42,6 +53,254 @@ class PortManager:
                 return True
         except OSError:
             return False
+    
+    def get_process_on_port(self, port: int) -> Optional[ProcessInfo]:
+        """Get information about the process using a specific port.
+        
+        WHY: We need to identify what process is using a port to make intelligent
+        decisions about whether we can reclaim it (our debug scripts) or must
+        avoid it (external processes or our daemons).
+        
+        Returns:
+            ProcessInfo with details about the process, or None if port is free
+        """
+        try:
+            # First try using lsof as it's more reliable for port detection
+            try:
+                result = subprocess.run(
+                    ['lsof', '-i', f':{port}', '-sTCP:LISTEN', '-t'],
+                    capture_output=True,
+                    text=True,
+                    timeout=2
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    # Get the PID from lsof output
+                    pid = int(result.stdout.strip().split()[0])
+                    try:
+                        process = psutil.Process(pid)
+                        cmdline = ' '.join(process.cmdline())
+                        
+                        # Determine if this is our process and what type
+                        is_ours = self._is_our_process(pid, cmdline)
+                        is_debug = self._is_debug_process(cmdline) if is_ours else False
+                        is_daemon = self._is_daemon_process(cmdline) if is_ours else False
+                        
+                        return ProcessInfo(
+                            pid=pid,
+                            name=process.name(),
+                            cmdline=cmdline,
+                            is_ours=is_ours,
+                            is_debug=is_debug,
+                            is_daemon=is_daemon
+                        )
+                    except (psutil.NoSuchProcess, psutil.AccessDenied) as e:
+                        # Process exists but we can't access it
+                        return ProcessInfo(
+                            pid=pid,
+                            name="unknown",
+                            cmdline="<permission denied>",
+                            is_ours=False,
+                            is_debug=False,
+                            is_daemon=False
+                        )
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                # lsof not available or timed out, fall back to psutil
+                pass
+            
+            # Fallback to psutil method
+            for conn in psutil.net_connections(kind='inet'):
+                if conn.laddr.port == port and conn.status == 'LISTEN':
+                    try:
+                        process = psutil.Process(conn.pid)
+                        cmdline = ' '.join(process.cmdline())
+                        
+                        # Determine if this is our process and what type
+                        is_ours = self._is_our_process(conn.pid, cmdline)
+                        is_debug = self._is_debug_process(cmdline) if is_ours else False
+                        is_daemon = self._is_daemon_process(cmdline) if is_ours else False
+                        
+                        return ProcessInfo(
+                            pid=conn.pid,
+                            name=process.name(),
+                            cmdline=cmdline,
+                            is_ours=is_ours,
+                            is_debug=is_debug,
+                            is_daemon=is_daemon
+                        )
+                    except (psutil.NoSuchProcess, psutil.AccessDenied):
+                        # Can't access process details, mark as unknown external
+                        return ProcessInfo(
+                            pid=conn.pid,
+                            name="unknown",
+                            cmdline="<permission denied>",
+                            is_ours=False,
+                            is_debug=False,
+                            is_daemon=False
+                        )
+        except psutil.AccessDenied:
+            # No permission to check network connections
+            # Try socket binding as last resort
+            if not self.is_port_available(port):
+                # Port is in use but we can't determine by what
+                return ProcessInfo(
+                    pid=0,
+                    name="unknown",
+                    cmdline="<unable to determine>",
+                    is_ours=False,
+                    is_debug=False,
+                    is_daemon=False
+                )
+        except Exception as e:
+            self.logger.debug(f"Error getting process on port {port}: {e}")
+        
+        return None
+    
+    def _is_our_process(self, pid: int, cmdline: str = None) -> bool:
+        """Check if a process belongs to claude-mpm.
+        
+        WHY: We need to distinguish our processes from external ones to know
+        which ports we can potentially reclaim.
+        """
+        try:
+            if cmdline is None:
+                process = psutil.Process(pid)
+                cmdline = ' '.join(process.cmdline())
+            
+            cmdline_lower = cmdline.lower()
+            
+            # Check for claude-mpm related patterns
+            our_patterns = [
+                'claude-mpm',
+                'claude_mpm',
+                'socketio_debug',
+                'socketio_daemon',
+                'socketio_server',
+                str(self.project_root).lower(),  # Running from our project directory
+                'scripts/test_',  # Our test scripts
+                'scripts/debug_',  # Our debug scripts
+                'scripts/demo_',  # Our demo scripts
+                'scripts/run_',  # Our run scripts
+                'scripts/validate_',  # Our validation scripts
+            ]
+            
+            return any(pattern in cmdline_lower for pattern in our_patterns)
+            
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            return False
+    
+    def _is_debug_process(self, cmdline: str) -> bool:
+        """Check if a process is a debug/test script (safe to kill).
+        
+        WHY: Debug and test scripts can be safely terminated to reclaim ports,
+        unlike production daemons which should be preserved.
+        """
+        cmdline_lower = cmdline.lower()
+        
+        debug_patterns = [
+            'socketio_debug.py',
+            'run_socketio_debug.py',
+            'test_',
+            'debug_',
+            'demo_',
+            'validate_',
+            'scripts/test',
+            'scripts/debug',
+            'scripts/demo',
+            'scripts/validate',
+        ]
+        
+        # Also check if NOT a daemon (daemons are not debug scripts)
+        is_not_daemon = 'daemon' not in cmdline_lower or 'debug' in cmdline_lower
+        
+        return any(pattern in cmdline_lower for pattern in debug_patterns) and is_not_daemon
+    
+    def _is_daemon_process(self, cmdline: str) -> bool:
+        """Check if a process is a daemon (should be preserved).
+        
+        WHY: Daemon processes are production services that should not be
+        automatically killed. Users must explicitly stop them.
+        """
+        cmdline_lower = cmdline.lower()
+        
+        daemon_patterns = [
+            'socketio_daemon',
+            'claude-mpm monitor',
+            'daemon',
+        ]
+        
+        # Exclude debug daemons
+        if 'debug' in cmdline_lower:
+            return False
+        
+        return any(pattern in cmdline_lower for pattern in daemon_patterns)
+    
+    def kill_process_on_port(self, port: int, force: bool = False) -> bool:
+        """Kill a process using a specific port if it's safe to do so.
+        
+        WHY: Automatically reclaim ports from our debug scripts while preserving
+        daemons and avoiding external processes.
+        
+        Args:
+            port: Port number to reclaim
+            force: If True, kill even daemon processes (requires explicit user action)
+            
+        Returns:
+            True if process was killed or port is now free, False otherwise
+        """
+        process_info = self.get_process_on_port(port)
+        
+        if not process_info:
+            self.logger.info(f"Port {port} is already free")
+            return True
+        
+        if not process_info.is_ours:
+            self.logger.warning(
+                f"Port {port} is used by external process '{process_info.name}' "
+                f"(PID: {process_info.pid}). Cannot reclaim."
+            )
+            return False
+        
+        if process_info.is_daemon and not force:
+            self.logger.warning(
+                f"Port {port} is used by our daemon process (PID: {process_info.pid}). "
+                f"Use --force flag or stop the daemon explicitly."
+            )
+            return False
+        
+        if process_info.is_debug or force:
+            try:
+                self.logger.info(
+                    f"Killing {'debug' if process_info.is_debug else 'daemon'} process "
+                    f"{process_info.pid} on port {port}"
+                )
+                
+                # Try graceful termination first
+                os.kill(process_info.pid, signal.SIGTERM)
+                
+                # Wait up to 2 seconds for graceful shutdown
+                for _ in range(20):
+                    time.sleep(0.1)
+                    if not psutil.pid_exists(process_info.pid):
+                        self.logger.info(f"Process {process_info.pid} terminated gracefully")
+                        return True
+                
+                # Force kill if still running
+                self.logger.warning(f"Process {process_info.pid} didn't terminate, forcing kill")
+                os.kill(process_info.pid, signal.SIGKILL)
+                time.sleep(0.5)
+                
+                if not psutil.pid_exists(process_info.pid):
+                    self.logger.info(f"Process {process_info.pid} force killed")
+                    return True
+                else:
+                    self.logger.error(f"Failed to kill process {process_info.pid}")
+                    return False
+                    
+            except Exception as e:
+                self.logger.error(f"Error killing process {process_info.pid}: {e}")
+                return False
+        
+        return False
 
     def is_claude_mpm_instance(self, port: int) -> Tuple[bool, Optional[Dict]]:
         """Check if a port is being used by a claude-mpm SocketIO instance."""
@@ -82,29 +341,61 @@ class PortManager:
             return False
 
     def find_available_port(
-        self, preferred_port: Optional[int] = None
+        self, preferred_port: Optional[int] = None, reclaim: bool = True
     ) -> Optional[int]:
-        """Find an available port, preferring the specified port if given."""
+        """Find an available port, preferring the specified port if given.
+        
+        WHY: Enhanced to intelligently reclaim ports from our debug processes
+        while avoiding external processes and preserving daemons.
+        
+        Args:
+            preferred_port: Port to try first
+            reclaim: If True, try to reclaim ports from our debug scripts
+            
+        Returns:
+            Available port number or None if no ports available
+        """
         # Try preferred port first
         if preferred_port and preferred_port in self.PORT_RANGE:
             if self.is_port_available(preferred_port):
-                is_ours, instance_info = self.is_claude_mpm_instance(preferred_port)
-                if not is_ours:
-                    return preferred_port
-                else:
-                    self.logger.warning(
-                        f"Port {preferred_port} is already used by claude-mpm instance: {instance_info}"
+                return preferred_port
+            
+            # Port is in use - check if we can reclaim it
+            if reclaim:
+                process_info = self.get_process_on_port(preferred_port)
+                if process_info and process_info.is_ours and process_info.is_debug:
+                    self.logger.info(
+                        f"Port {preferred_port} used by our debug process, attempting to reclaim"
                     )
+                    if self.kill_process_on_port(preferred_port):
+                        time.sleep(0.5)  # Brief pause for port to be released
+                        if self.is_port_available(preferred_port):
+                            return preferred_port
+                elif process_info:
+                    if process_info.is_daemon:
+                        self.logger.warning(
+                            f"Port {preferred_port} used by our daemon (PID: {process_info.pid})"
+                        )
+                    elif not process_info.is_ours:
+                        self.logger.warning(
+                            f"Port {preferred_port} used by external process '{process_info.name}'"
+                        )
 
         # Try default port
         if self.is_port_available(self.DEFAULT_PORT):
-            is_ours, instance_info = self.is_claude_mpm_instance(self.DEFAULT_PORT)
-            if not is_ours:
-                return self.DEFAULT_PORT
-            else:
+            return self.DEFAULT_PORT
+        
+        # Check if we can reclaim default port
+        if reclaim:
+            process_info = self.get_process_on_port(self.DEFAULT_PORT)
+            if process_info and process_info.is_ours and process_info.is_debug:
                 self.logger.info(
-                    f"Default port {self.DEFAULT_PORT} is already used by claude-mpm instance"
+                    f"Default port {self.DEFAULT_PORT} used by our debug process, attempting to reclaim"
                 )
+                if self.kill_process_on_port(self.DEFAULT_PORT):
+                    time.sleep(0.5)
+                    if self.is_port_available(self.DEFAULT_PORT):
+                        return self.DEFAULT_PORT
 
         # Try other ports in range
         for port in self.PORT_RANGE:
@@ -112,10 +403,20 @@ class PortManager:
                 continue  # Already tried
 
             if self.is_port_available(port):
-                is_ours, instance_info = self.is_claude_mpm_instance(port)
-                if not is_ours:
-                    self.logger.info(f"Selected available port: {port}")
-                    return port
+                return port
+            
+            # Try to reclaim if it's our debug process
+            if reclaim:
+                process_info = self.get_process_on_port(port)
+                if process_info and process_info.is_ours and process_info.is_debug:
+                    self.logger.info(
+                        f"Port {port} used by our debug process, attempting to reclaim"
+                    )
+                    if self.kill_process_on_port(port):
+                        time.sleep(0.5)
+                        if self.is_port_available(port):
+                            self.logger.info(f"Reclaimed port {port}")
+                            return port
 
         self.logger.error(
             f"No available ports in range {self.PORT_RANGE.start}-{self.PORT_RANGE.stop-1}"
@@ -221,3 +522,54 @@ class PortManager:
                     return instance_info
 
         return None
+    
+    def get_port_status(self, port: int) -> Dict[str, any]:
+        """Get detailed status of a port including what's using it.
+        
+        WHY: Provides comprehensive information for users to understand
+        port conflicts and make informed decisions.
+        
+        Returns:
+            Dictionary with port status details
+        """
+        status = {
+            "port": port,
+            "available": self.is_port_available(port),
+            "process": None,
+            "instance": None,
+            "recommendation": None
+        }
+        
+        # Check for process using the port
+        process_info = self.get_process_on_port(port)
+        if process_info:
+            status["process"] = {
+                "pid": process_info.pid,
+                "name": process_info.name,
+                "is_ours": process_info.is_ours,
+                "is_debug": process_info.is_debug,
+                "is_daemon": process_info.is_daemon,
+                "cmdline": process_info.cmdline[:100] + "..." if len(process_info.cmdline) > 100 else process_info.cmdline
+            }
+            
+            # Provide recommendation based on process type
+            if process_info.is_ours:
+                if process_info.is_debug:
+                    status["recommendation"] = "Can be automatically reclaimed (debug process)"
+                elif process_info.is_daemon:
+                    status["recommendation"] = "Stop daemon with 'claude-mpm monitor stop' or use --force"
+                else:
+                    status["recommendation"] = "Our process, consider stopping it manually"
+            else:
+                status["recommendation"] = "External process, choose a different port"
+        
+        # Check for registered instance
+        instance_info = self.get_instance_by_port(port)
+        if instance_info:
+            status["instance"] = {
+                "id": instance_info.get("instance_id"),
+                "pid": instance_info.get("pid"),
+                "start_time": instance_info.get("start_time")
+            }
+        
+        return status

claude_mpm/services/socketio/handlers/connection.py

@@ -88,7 +88,7 @@ class ConnectionEventHandler(BaseEventHandler):
                 )
 
         @self.sio.event
-        async def get_status(sid, data=None):
+        async def get_status(sid):
             """Handle status request.
 
             WHY: Clients need to query current server status on demand
@@ -151,27 +151,45 @@ class ConnectionEventHandler(BaseEventHandler):
             self.logger.info(f"🔵 Received claude_event from {sid}: {data}")
             
             # Check if this is a hook event and route to HookEventHandler
-            if isinstance(data, dict) and data.get("type") == "hook":
-                # Get the hook handler if available
-                hook_handler = None
-                # Check if event_registry exists and has handlers
-                if hasattr(self.server, 'event_registry') and self.server.event_registry and hasattr(self.server.event_registry, 'handlers'):
-                    for handler in self.server.event_registry.handlers:
-                        if handler.__class__.__name__ == "HookEventHandler":
-                            hook_handler = handler
-                            break
-                
-                if hook_handler and hasattr(hook_handler, "process_hook_event"):
-                    # Let the hook handler process this event
-                    await hook_handler.process_hook_event(data)
-                    # Don't double-store or double-broadcast, return early
-                    return
+            # Hook events have types like "hook.user_prompt", "hook.pre_tool", etc.
+            if isinstance(data, dict):
+                event_type = data.get("type", "")
+                if isinstance(event_type, str) and event_type.startswith("hook."):
+                    # Get the hook handler if available
+                    hook_handler = None
+                    # Check if event_registry exists and has handlers
+                    if hasattr(self.server, 'event_registry') and self.server.event_registry:
+                        if hasattr(self.server.event_registry, 'handlers'):
+                            for handler in self.server.event_registry.handlers:
+                                if handler.__class__.__name__ == "HookEventHandler":
+                                    hook_handler = handler
+                                    break
+                    
+                    if hook_handler and hasattr(hook_handler, "process_hook_event"):
+                        # Let the hook handler process this event
+                        await hook_handler.process_hook_event(data)
+                        # Don't double-store or double-broadcast, return early
+                        return
             
             # Normalize event format before storing in history
             normalized_event = self._normalize_event(data)
             
-            # Store in history
-            self.event_history.append(normalized_event)
+            # Store in history - flatten if it's a nested structure
+            # If the normalized event has data.event, promote it to top level
+            if isinstance(normalized_event, dict) and 'data' in normalized_event:
+                if isinstance(normalized_event['data'], dict) and 'event' in normalized_event['data']:
+                    # This is a nested event, flatten it
+                    flattened = {
+                        'type': normalized_event.get('type', 'unknown'),
+                        'event': normalized_event['data'].get('event'),
+                        'timestamp': normalized_event.get('timestamp') or normalized_event['data'].get('timestamp'),
+                        'data': normalized_event['data'].get('data', {})
+                    }
+                    self.event_history.append(flattened)
+                else:
+                    self.event_history.append(normalized_event)
+            else:
+                self.event_history.append(normalized_event)
             self.logger.info(
                 f"📚 Event from client stored in history (total: {len(self.event_history)})"
             )
@@ -186,7 +204,8 @@ class ConnectionEventHandler(BaseEventHandler):
         
         WHY: Different clients may send events in different formats.
         This ensures all events have a consistent 'type' field for
-        proper display in the dashboard.
+        proper display in the dashboard, while preserving the original
+        'event' field for hook events.
         """
         if not isinstance(event_data, dict):
             return event_data
@@ -210,6 +229,9 @@ class ConnectionEventHandler(BaseEventHandler):
             else:
                 # Default to system type for unknown events
                 normalized['type'] = 'system'
+            
+            # Note: We keep the 'event' field for backward compatibility
+            # Dashboard may use it for display purposes
         
         # Ensure there's always a type field
         if 'type' not in normalized:

claude_mpm/services/socketio/handlers/hook.py

@@ -32,26 +32,41 @@ class HookEventHandler(BaseEventHandler):
         """Process a hook event received from ConnectionEventHandler.
         
         WHY: This method is called by ConnectionEventHandler when it receives
-        a claude_event with type 'hook'. This separation avoids handler conflicts.
+        a claude_event with type starting with 'hook.'. This separation avoids handler conflicts.
         
         Args:
-            data: The complete event data including type, event, and data fields
+            data: The complete event data including type, timestamp, and data fields
         """
         if not isinstance(data, dict):
             return
             
         # Extract hook event details
-        hook_event = data.get("event")
+        # Hook events come as: { type: "hook.user_prompt", timestamp: "...", data: {...} }
+        event_type = data.get("type", "")
+        
+        # Extract the actual hook event name from the type (e.g., "hook.user_prompt" -> "user_prompt")
+        if event_type.startswith("hook."):
+            hook_event = event_type[5:]  # Remove "hook." prefix
+        else:
+            hook_event = data.get("event", "")  # Fallback for legacy format
+            
         hook_data = data.get("data", {})
         
-        # Add the event to history for replay
-        self.add_to_history("hook", {
+        # Create properly formatted event for history
+        # Note: add_to_history expects the event data directly, not wrapped
+        history_event = {
+            "type": "hook",
             "event": hook_event,
             "data": hook_data,
-            "timestamp": datetime.now().isoformat()
-        })
+            "timestamp": data.get("timestamp") or datetime.now().isoformat()
+        }
+        
+        # Add the event to history for replay
+        # The base handler's add_to_history will wrap it properly
+        self.event_history.append(history_event)
         
-        # Broadcast the event to all connected clients
+        # Broadcast the original event to all connected clients
+        # (preserves all original fields)
         await self.broadcast_event("claude_event", data)
         
         # Track sessions based on hook events