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

claude_mpm/services/socketio/handlers/hook.py

@@ -0,0 +1,170 @@
+"""Hook event handlers for Socket.IO.
+
+WHY: This module handles hook events from Claude to track session information,
+agent delegations, and other hook-based activity for the system heartbeat.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from .base import BaseEventHandler
+
+
+class HookEventHandler(BaseEventHandler):
+    """Handles hook events from Claude for session tracking.
+    
+    WHY: Hook events provide rich information about Claude's activity including
+    session starts/stops, agent delegations, and tool usage. This handler
+    extracts session information to populate the system heartbeat data.
+    """
+    
+    def register_events(self) -> None:
+        """Register hook event handlers.
+        
+        NOTE: This handler no longer registers a claude_event handler directly
+        to avoid conflicts with ConnectionEventHandler. Instead, it processes
+        hook events passed from ConnectionEventHandler.
+        """
+        # No direct event registration - events are passed from ConnectionEventHandler
+        pass
+    
+    async def process_hook_event(self, data: Dict[str, Any]) -> None:
+        """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.
+        
+        Args:
+            data: The complete event data including type, event, and data fields
+        """
+        if not isinstance(data, dict):
+            return
+            
+        # Extract hook event details
+        hook_event = data.get("event")
+        hook_data = data.get("data", {})
+        
+        # Add the event to history for replay
+        self.add_to_history("hook", {
+            "event": hook_event,
+            "data": hook_data,
+            "timestamp": datetime.now().isoformat()
+        })
+        
+        # Broadcast the event to all connected clients
+        await self.broadcast_event("claude_event", data)
+        
+        # Track sessions based on hook events
+        if hook_event == "subagent_start":
+            await self._handle_subagent_start(hook_data)
+        elif hook_event == "subagent_stop":
+            await self._handle_subagent_stop(hook_data)
+        elif hook_event == "user_prompt":
+            await self._handle_user_prompt(hook_data)
+        elif hook_event == "pre_tool":
+            await self._handle_pre_tool(hook_data)
+        
+        self.logger.debug(f"Processed hook event: {hook_event}")
+                
+    async def _handle_subagent_start(self, data: Dict[str, Any]):
+        """Handle subagent start events.
+        
+        WHY: When a subagent starts, we track it as an active session
+        with the agent type and start time for the heartbeat.
+        """
+        session_id = data.get("session_id")
+        agent_type = data.get("agent_type", "unknown")
+        
+        if not session_id:
+            return
+            
+        # Update or create session tracking
+        if hasattr(self.server, 'active_sessions'):
+            self.server.active_sessions[session_id] = {
+                "session_id": session_id,
+                "start_time": datetime.now().isoformat(),
+                "agent": agent_type,
+                "status": "active",
+                "prompt": data.get("prompt", "")[:100],  # First 100 chars
+                "last_activity": datetime.now().isoformat(),
+            }
+            
+            self.logger.debug(
+                f"Tracked subagent start: session={session_id[:8]}..., agent={agent_type}"
+            )
+            
+    async def _handle_subagent_stop(self, data: Dict[str, Any]):
+        """Handle subagent stop events.
+        
+        WHY: When a subagent stops, we update its status or remove it
+        from active sessions depending on the stop reason.
+        """
+        session_id = data.get("session_id")
+        
+        if not session_id:
+            return
+            
+        # Update session status
+        if hasattr(self.server, 'active_sessions'):
+            if session_id in self.server.active_sessions:
+                # Mark as completed rather than removing immediately
+                self.server.active_sessions[session_id]["status"] = "completed"
+                self.server.active_sessions[session_id]["last_activity"] = datetime.now().isoformat()
+                
+                self.logger.debug(
+                    f"Marked session completed: session={session_id[:8]}..."
+                )
+                
+    async def _handle_user_prompt(self, data: Dict[str, Any]):
+        """Handle user prompt events.
+        
+        WHY: User prompts indicate the start of a new interaction,
+        which we track as a PM session if no delegation occurs.
+        """
+        session_id = data.get("session_id")
+        
+        if not session_id:
+            return
+            
+        # Create or update PM session
+        if hasattr(self.server, 'active_sessions'):
+            if session_id not in self.server.active_sessions:
+                self.server.active_sessions[session_id] = {
+                    "session_id": session_id,
+                    "start_time": datetime.now().isoformat(),
+                    "agent": "pm",  # Default to PM
+                    "status": "active",
+                    "prompt": data.get("prompt_text", "")[:100],
+                    "working_directory": data.get("working_directory", ""),
+                    "last_activity": datetime.now().isoformat(),
+                }
+            else:
+                # Update last activity
+                self.server.active_sessions[session_id]["last_activity"] = datetime.now().isoformat()
+                
+    async def _handle_pre_tool(self, data: Dict[str, Any]):
+        """Handle pre-tool events.
+        
+        WHY: Pre-tool events with Task delegation indicate agent changes
+        that we need to track for accurate session information.
+        """
+        if data.get("tool_name") != "Task":
+            return
+            
+        session_id = data.get("session_id")
+        delegation_details = data.get("delegation_details", {})
+        agent_type = delegation_details.get("agent_type", "unknown")
+        
+        if not session_id:
+            return
+            
+        # Update session with new agent
+        if hasattr(self.server, 'active_sessions'):
+            if session_id in self.server.active_sessions:
+                self.server.active_sessions[session_id]["agent"] = agent_type
+                self.server.active_sessions[session_id]["status"] = "delegated"
+                self.server.active_sessions[session_id]["last_activity"] = datetime.now().isoformat()
+                
+                self.logger.debug(
+                    f"Updated session delegation: session={session_id[:8]}..., agent={agent_type}"
+                )

claude_mpm/services/socketio/handlers/memory.py

@@ -10,18 +10,18 @@ from .base import BaseEventHandler
 
 class MemoryEventHandler(BaseEventHandler):
     """Handles memory-related Socket.IO events.
-    
+
     WHY: Agent memory management events will be handled here as the system
     grows. This provides a clean separation for memory-specific functionality.
     """
-    
+
     def register_events(self):
         """Register memory-related event handlers.
-        
+
         Currently memory events are handled through broadcast methods
         rather than Socket.IO event handlers, but this provides a place
         for future interactive memory management features.
         """
         # Future memory management events will be registered here
         # For example: query_memory, clear_memory, export_memory, etc.
-        pass
+        pass

claude_mpm/services/socketio/handlers/project.py

@@ -10,16 +10,16 @@ from .base import BaseEventHandler
 
 class ProjectEventHandler(BaseEventHandler):
     """Handles project-related Socket.IO events.
-    
+
     WHY: Project management events will be handled here as the system
     grows. This provides a clean separation for project-specific functionality.
     """
-    
+
     def register_events(self):
         """Register project-related event handlers.
-        
+
         Currently no project-specific events are defined, but this
         handler is ready for future expansion.
         """
         # Future project events will be registered here
-        pass
+        pass

claude_mpm/services/socketio/handlers/registry.py

@@ -5,66 +5,73 @@ providing a clean interface for the SocketIOServer to register all
 events without knowing the details of each handler.
 """
 
-from typing import List, Type, Optional, TYPE_CHECKING
 from logging import Logger
-from ....core.logger import get_logger
+from typing import TYPE_CHECKING, List, Optional, Type
 
+from ....core.logger import get_logger
 from .base import BaseEventHandler
 
 if TYPE_CHECKING:
     from ..server import SocketIOServer
+
 from .connection import ConnectionEventHandler
-from .project import ProjectEventHandler
-from .memory import MemoryEventHandler
 from .file import FileEventHandler
 from .git import GitEventHandler
+from .hook import HookEventHandler
+from .memory import MemoryEventHandler
+from .project import ProjectEventHandler
 
 
 class EventHandlerRegistry:
     """Manages registration of Socket.IO event handlers.
-    
+
     WHY: The registry pattern allows us to easily add, remove, or modify
     event handlers without changing the SocketIOServer implementation.
     It provides a single point of configuration for all event handlers.
     """
-    
+
     # Default handler classes in registration order
     DEFAULT_HANDLERS: List[Type[BaseEventHandler]] = [
         ConnectionEventHandler,  # Connection management first
-        GitEventHandler,         # Git operations
-        FileEventHandler,        # File operations
-        ProjectEventHandler,     # Project management (future)
-        MemoryEventHandler,      # Memory management (future)
+        HookEventHandler,  # Hook events for session tracking
+        GitEventHandler,  # Git operations
+        FileEventHandler,  # File operations
+        ProjectEventHandler,  # Project management (future)
+        MemoryEventHandler,  # Memory management (future)
     ]
-    
-    def __init__(self, server: 'SocketIOServer') -> None:
+
+    def __init__(self, server: "SocketIOServer") -> None:
         """Initialize the registry.
-        
+
         Args:
             server: The SocketIOServer instance
         """
-        self.server: 'SocketIOServer' = server
+        self.server: "SocketIOServer" = server
         self.logger: Logger = get_logger("EventHandlerRegistry")
         self.handlers: List[BaseEventHandler] = []
         self._initialized: bool = False
-    
-    def initialize(self, handler_classes: Optional[List[Type[BaseEventHandler]]] = None) -> None:
+
+    def initialize(
+        self, handler_classes: Optional[List[Type[BaseEventHandler]]] = None
+    ) -> None:
         """Initialize all event handlers.
-        
+
         WHY: This creates instances of all handler classes and prepares
         them for event registration. Using a list of classes allows
         customization of which handlers to use.
-        
+
         Args:
             handler_classes: Optional list of handler classes to use.
                            Defaults to DEFAULT_HANDLERS if not provided.
         """
         if self._initialized:
-            self.logger.warning("Registry already initialized, skipping re-initialization")
+            self.logger.warning(
+                "Registry already initialized, skipping re-initialization"
+            )
             return
-        
+
         handler_classes = handler_classes or self.DEFAULT_HANDLERS
-        
+
         for handler_class in handler_classes:
             try:
                 handler = handler_class(self.server)
@@ -73,14 +80,15 @@ class EventHandlerRegistry:
             except Exception as e:
                 self.logger.error(f"Failed to initialize {handler_class.__name__}: {e}")
                 import traceback
+
                 self.logger.error(f"Stack trace: {traceback.format_exc()}")
-        
+
         self._initialized = True
         self.logger.info(f"Registry initialized with {len(self.handlers)} handlers")
-    
+
     def register_all_events(self) -> None:
         """Register all events from all handlers.
-        
+
         WHY: This is the main method called by SocketIOServer to register
         all events. It delegates to each handler's register_events method,
         keeping the server code clean and simple.
@@ -88,7 +96,7 @@ class EventHandlerRegistry:
         if not self._initialized:
             self.logger.error("Registry not initialized. Call initialize() first.")
             raise RuntimeError("EventHandlerRegistry not initialized")
-        
+
         registered_count = 0
         for handler in self.handlers:
             try:
@@ -97,27 +105,34 @@ class EventHandlerRegistry:
                 self.logger.info(f"Registered events for {handler.__class__.__name__}")
             except NotImplementedError:
                 # Handler has no events to register (like ProjectEventHandler)
-                self.logger.debug(f"No events to register for {handler.__class__.__name__}")
+                self.logger.debug(
+                    f"No events to register for {handler.__class__.__name__}"
+                )
             except Exception as e:
-                self.logger.error(f"Failed to register events for {handler.__class__.__name__}: {e}")
+                self.logger.error(
+                    f"Failed to register events for {handler.__class__.__name__}: {e}"
+                )
                 import traceback
+
                 self.logger.error(f"Stack trace: {traceback.format_exc()}")
-        
-        self.logger.info(f"Successfully registered events from {registered_count} handlers")
-    
+
+        self.logger.info(
+            f"Successfully registered events from {registered_count} handlers"
+        )
+
     def add_handler(self, handler_class: Type[BaseEventHandler]):
         """Add a custom handler to the registry.
-        
+
         WHY: Allows dynamic addition of custom handlers for specific
         deployments or testing without modifying the default handlers.
-        
+
         Args:
             handler_class: The handler class to add
         """
         if not self._initialized:
             self.logger.error("Registry not initialized. Call initialize() first.")
             raise RuntimeError("EventHandlerRegistry not initialized")
-        
+
         try:
             handler = handler_class(self.server)
             self.handlers.append(handler)
@@ -126,20 +141,20 @@ class EventHandlerRegistry:
         except Exception as e:
             self.logger.error(f"Failed to add handler {handler_class.__name__}: {e}")
             raise
-    
+
     def get_handler(self, handler_class: Type[BaseEventHandler]) -> BaseEventHandler:
         """Get a specific handler instance by class.
-        
+
         WHY: Useful for testing or when specific handler functionality
         needs to be accessed directly.
-        
+
         Args:
             handler_class: The handler class to find
-            
+
         Returns:
             The handler instance or None if not found
         """
         for handler in self.handlers:
             if isinstance(handler, handler_class):
                 return handler
-        return None
+        return None

claude_mpm/services/socketio/server/__init__.py

@@ -0,0 +1,18 @@
+"""
+SocketIO Server package for claude-mpm.
+
+WHY: This package contains the modular SocketIO server components that were
+extracted from the monolithic socketio_server.py file.
+
+DESIGN DECISION: Split the massive SocketIOServer class into focused modules:
+- core.py: Server lifecycle and static file management
+- broadcaster.py: Event broadcasting to clients
+- event_registry.py: Event handler registration (if needed)
+
+This improves maintainability, testability, and code organization.
+"""
+
+from .broadcaster import SocketIOEventBroadcaster
+from .core import SocketIOServerCore
+
+__all__ = ["SocketIOServerCore", "SocketIOEventBroadcaster"]

claude_mpm/services/socketio/server/broadcaster.py

@@ -0,0 +1,252 @@
+"""
+SocketIO Event Broadcaster for claude-mpm.
+
+WHY: This module contains all the broadcasting methods extracted from the
+monolithic socketio_server.py file. It handles sending events to connected
+clients for various Claude MPM activities.
+
+DESIGN DECISION: Separated broadcasting logic from core server management
+to create focused, testable modules with single responsibilities.
+"""
+
+import asyncio
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Set
+
+from ....core.logging_config import get_logger
+
+
+class SocketIOEventBroadcaster:
+    """Handles broadcasting events to connected Socket.IO clients.
+
+    WHY: This class encapsulates all the event broadcasting logic that was
+    scattered throughout the monolithic SocketIOServer class.
+    """
+
+    def __init__(
+        self,
+        sio,
+        connected_clients: Set[str],
+        event_buffer,
+        buffer_lock,
+        stats: Dict[str, Any],
+        logger,
+        server=None,  # Add server reference for event history access
+    ):
+        self.sio = sio
+        self.connected_clients = connected_clients
+        self.event_buffer = event_buffer
+        self.buffer_lock = buffer_lock
+        self.stats = stats
+        self.logger = logger
+        self.loop = None  # Will be set by main server
+        self.server = server  # Reference to main server for event history
+
+    def broadcast_event(self, event_type: str, data: Dict[str, Any]):
+        """Broadcast an event to all connected clients."""
+        if not self.sio:
+            return
+
+        event = {
+            "type": event_type,
+            "timestamp": datetime.now().isoformat(),
+            "data": data,
+        }
+
+        # Buffer the event for reliability AND add to event history for new clients
+        with self.buffer_lock:
+            self.event_buffer.append(event)
+            self.stats["events_buffered"] += 1
+            
+            # Also add to event history if available (for client replay)
+            # Access through server reference to maintain single history source
+            if hasattr(self, 'server') and hasattr(self.server, 'event_history'):
+                self.server.event_history.append(event)
+                self.logger.debug(f"Added {event_type} to history (total: {len(self.server.event_history)})")
+
+        # Broadcast to all connected clients
+        try:
+            # Use run_coroutine_threadsafe to safely call from any thread
+            if hasattr(self, "loop") and self.loop and not self.loop.is_closed():
+                future = asyncio.run_coroutine_threadsafe(
+                    self.sio.emit("claude_event", event), self.loop
+                )
+                # Don't wait for the result to avoid blocking
+                self.stats["events_sent"] += 1
+                self.logger.debug(f"Broadcasted event: {event_type}")
+            else:
+                self.logger.warning(
+                    f"Cannot broadcast {event_type}: server loop not available"
+                )
+
+        except Exception as e:
+            self.logger.error(f"Failed to broadcast event {event_type}: {e}")
+
+    def session_started(self, session_id: str, launch_method: str, working_dir: str):
+        """Notify that a session has started."""
+        self.broadcast_event(
+            "session_started",
+            {
+                "session_id": session_id,
+                "launch_method": launch_method,
+                "working_dir": working_dir,
+                "timestamp": datetime.now().isoformat(),
+            },
+        )
+
+    def session_ended(self):
+        """Notify that a session has ended."""
+        self.broadcast_event("session_ended", {"timestamp": datetime.now().isoformat()})
+
+    def claude_status_changed(
+        self, status: str, pid: Optional[int] = None, message: str = ""
+    ):
+        """Notify Claude status change."""
+        self.broadcast_event(
+            "claude_status", {"status": status, "pid": pid, "message": message}
+        )
+
+    def claude_output(self, content: str, stream: str = "stdout"):
+        """Broadcast Claude output."""
+        self.broadcast_event("claude_output", {"content": content, "stream": stream})
+
+    def agent_delegated(self, agent: str, task: str, status: str = "started"):
+        """Notify agent delegation."""
+        self.broadcast_event(
+            "agent_delegated", {"agent": agent, "task": task, "status": status}
+        )
+
+    def todo_updated(self, todos: List[Dict[str, Any]]):
+        """Notify todo list update."""
+        # Limit the size of todo data to prevent large payloads
+        limited_todos = todos[:50] if len(todos) > 50 else todos
+
+        self.broadcast_event(
+            "todo_updated",
+            {
+                "todos": limited_todos,
+                "total_count": len(todos),
+                "truncated": len(todos) > 50,
+            },
+        )
+
+    def ticket_created(self, ticket_id: str, title: str, priority: str = "medium"):
+        """Notify ticket creation."""
+        self.broadcast_event(
+            "ticket_created",
+            {"ticket_id": ticket_id, "title": title, "priority": priority},
+        )
+
+    def memory_loaded(self, agent_id: str, memory_size: int, sections_count: int):
+        """Notify when agent memory is loaded from file."""
+        self.broadcast_event(
+            "memory_loaded",
+            {
+                "agent_id": agent_id,
+                "memory_size": memory_size,
+                "sections_count": sections_count,
+            },
+        )
+
+    def memory_created(self, agent_id: str, template_type: str):
+        """Notify when new agent memory is created from template."""
+        self.broadcast_event(
+            "memory_created", {"agent_id": agent_id, "template_type": template_type}
+        )
+
+    def memory_updated(
+        self, agent_id: str, learning_type: str, content: str, section: str
+    ):
+        """Notify when learning is added to agent memory."""
+        # Truncate content if too long to prevent large payloads
+        truncated_content = content[:500] + "..." if len(content) > 500 else content
+
+        self.broadcast_event(
+            "memory_updated",
+            {
+                "agent_id": agent_id,
+                "learning_type": learning_type,
+                "content": truncated_content,
+                "section": section,
+                "content_length": len(content),
+                "truncated": len(content) > 500,
+            },
+        )
+
+    def memory_injected(self, agent_id: str, context_size: int):
+        """Notify when agent memory is injected into context."""
+        self.broadcast_event(
+            "memory_injected", {"agent_id": agent_id, "context_size": context_size}
+        )
+
+    def file_changed(
+        self, file_path: str, change_type: str, content: Optional[str] = None
+    ):
+        """Notify file system changes."""
+        event_data = {"file_path": file_path, "change_type": change_type}
+
+        # Include content for small files only
+        if content and len(content) < 1000:
+            event_data["content"] = content
+        elif content:
+            event_data["content_preview"] = content[:200] + "..."
+            event_data["content_length"] = len(content)
+
+        self.broadcast_event("file_changed", event_data)
+
+    def git_operation(self, operation: str, details: Dict[str, Any]):
+        """Notify Git operations."""
+        self.broadcast_event(
+            "git_operation", {"operation": operation, "details": details}
+        )
+
+    def error_occurred(
+        self, error_type: str, message: str, details: Optional[Dict[str, Any]] = None
+    ):
+        """Notify when errors occur."""
+        self.broadcast_event(
+            "error",
+            {"error_type": error_type, "message": message, "details": details or {}},
+        )
+
+    def performance_metric(self, metric_name: str, value: float, unit: str = ""):
+        """Broadcast performance metrics."""
+        self.broadcast_event(
+            "performance", {"metric": metric_name, "value": value, "unit": unit}
+        )
+
+    def system_status(self, status: Dict[str, Any]):
+        """Broadcast system status information."""
+        self.broadcast_event("system_status", status)
+    
+    def broadcast_system_heartbeat(self, heartbeat_data: Dict[str, Any]):
+        """Broadcast system heartbeat event.
+        
+        WHY: System events are separate from hook events to provide
+        server health monitoring independent of Claude activity.
+        """
+        if not self.sio:
+            return
+            
+        # Create system event with consistent format
+        event = {
+            "type": "system",
+            "event": "heartbeat",
+            "timestamp": datetime.now().isoformat(),
+            "data": heartbeat_data,
+        }
+        
+        # Broadcast to all connected clients
+        try:
+            if self.loop and not self.loop.is_closed():
+                future = asyncio.run_coroutine_threadsafe(
+                    self.sio.emit("system_event", event), self.loop
+                )
+                self.logger.debug(
+                    f"Broadcasted system heartbeat - clients: {len(self.connected_clients)}, "
+                    f"uptime: {heartbeat_data.get('uptime_seconds', 0)}s"
+                )
+            else:
+                self.logger.warning("Cannot broadcast heartbeat: server loop not available")
+        except Exception as e:
+            self.logger.error(f"Failed to broadcast system heartbeat: {e}")