claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/socketio/handlers/hook.py

@@ -0,0 +1,211 @@
+"""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, timezone
+from typing import Any, Dict
+
+from ....core.enums import ServiceState
+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
+
+    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 starting with 'hook.'. This separation avoids handler conflicts.
+
+        Args:
+            data: The complete event data including type, timestamp, and data fields
+        """
+        if not isinstance(data, dict):
+            return
+
+        # Extract hook event details
+        # Hook events can come in two formats:
+        # 1. Normalized: { type: "hook", subtype: "user_prompt", ... }
+        # 2. Legacy: { type: "hook.user_prompt", ... }
+        event_type = data.get("type", "")
+        event_subtype = data.get("subtype", "")
+
+        # Determine the actual hook event name
+        hook_event = ""
+        if event_type == "hook" and event_subtype:
+            # Normalized format: use subtype directly
+            hook_event = event_subtype
+        elif isinstance(event_type, str) and event_type.startswith("hook."):
+            # Legacy format: extract from dotted type
+            hook_event = event_type[5:]  # Remove "hook." prefix
+        else:
+            # Fallback: check for 'event' field (another legacy format)
+            hook_event = data.get("event", "")
+
+        hook_data = data.get("data", {})
+
+        # Log hook event processing
+        tool_name = hook_data.get("tool_name", "N/A")
+        self.logger.info(f"Processing hook event: {hook_event} - tool: {tool_name}")
+
+        # 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": data.get("timestamp")
+            or datetime.now(timezone.utc).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 original event to all connected clients
+        # (preserves all original fields)
+        connected_clients = (
+            len(self.server.clients) if hasattr(self.server, "clients") else 0
+        )
+        self.logger.info(
+            f"Broadcasting claude_event to {connected_clients} clients: {hook_event}"
+        )
+        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(timezone.utc).isoformat(),
+                "agent": agent_type,
+                "status": ServiceState.RUNNING,
+                "prompt": data.get("prompt", "")[:100],  # First 100 chars
+                "last_activity": datetime.now(timezone.utc).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(
+                    timezone.utc
+                ).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(timezone.utc).isoformat(),
+                    "agent": "pm",  # Default to PM
+                    "status": ServiceState.RUNNING,
+                    "prompt": data.get("prompt_text", "")[:100],
+                    "working_directory": data.get("working_directory", ""),
+                    "last_activity": datetime.now(timezone.utc).isoformat(),
+                }
+            else:
+                # Update last activity
+                self.server.active_sessions[session_id]["last_activity"] = datetime.now(
+                    timezone.utc
+                ).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(
+                    timezone.utc
+                ).isoformat()
+
+                self.logger.debug(
+                    f"Updated session delegation: session={session_id[:8]}..., agent={agent_type}"
+                )

claude_mpm/services/socketio/handlers/memory.py

@@ -0,0 +1,26 @@
+"""Memory-related event handlers for Socket.IO.
+
+WHY: This module handles agent memory events. Currently the memory
+events are broadcast methods rather than Socket.IO events, but this
+provides a place for future memory management features.
+"""
+
+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.

claude_mpm/services/socketio/handlers/project.py

@@ -0,0 +1,24 @@
+"""Project-related event handlers for Socket.IO.
+
+WHY: This module handles project-specific events that don't fit into
+other categories. Currently empty but provides a place for future
+project management features.
+"""
+
+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

claude_mpm/services/socketio/handlers/registry.py

@@ -0,0 +1,214 @@
+"""Event handler registry for Socket.IO server.
+
+WHY: This registry manages the registration of all event handlers,
+providing a clean interface for the SocketIOServer to register all
+events without knowing the details of each handler.
+"""
+
+from typing import TYPE_CHECKING, List, Optional, Type
+
+from ....core.logger import get_logger
+from .base import BaseEventHandler
+
+if TYPE_CHECKING:
+    from logging import Logger
+
+    from ..server import SocketIOServer
+
+# DISABLED: File Tree interface removed from dashboard
+# from .code_analysis import CodeAnalysisEventHandler
+from .connection import ConnectionEventHandler
+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
+        HookEventHandler,  # Hook events for session tracking
+        GitEventHandler,  # Git operations
+        FileEventHandler,  # File operations
+        # DISABLED: File Tree interface removed from dashboard
+        # CodeAnalysisEventHandler,  # Code analysis for dashboard
+        ProjectEventHandler,  # Project management (future)
+        MemoryEventHandler,  # Memory management (future)
+    ]
+
+    def __init__(self, server: "SocketIOServer") -> None:
+        """Initialize the registry.
+
+        Args:
+            server: The SocketIOServer instance
+        """
+        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:
+        """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"
+            )
+            return
+
+        # Add debug logging for deployment context
+        try:
+            from ....core.unified_paths import PathContext
+
+            deployment_context = PathContext.detect_deployment_context()
+            self.logger.info(
+                f"Initializing event handlers in {deployment_context.value} mode"
+            )
+        except Exception as e:
+            self.logger.debug(f"Could not detect deployment context: {e}")
+
+        handler_classes = handler_classes or self.DEFAULT_HANDLERS
+        self.logger.debug(f"Initializing {len(handler_classes)} handler classes")
+
+        for handler_class in handler_classes:
+            try:
+                self.logger.debug(f"Creating instance of {handler_class.__name__}")
+                handler = handler_class(self.server)
+                self.handlers.append(handler)
+                self.logger.info(f"✅ Initialized handler: {handler_class.__name__}")
+            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.
+        """
+        if not self._initialized:
+            self.logger.error("Registry not initialized. Call initialize() first.")
+            raise RuntimeError("EventHandlerRegistry not initialized")
+
+        self.logger.info(
+            f"🔄 Starting event registration for {len(self.handlers)} handlers"
+        )
+
+        # Verify Socket.IO server is available
+        if (
+            not hasattr(self.server, "core")
+            or not self.server.core
+            or not self.server.core.sio
+        ):
+            self.logger.error(
+                "❌ Socket.IO server instance not available for event registration"
+            )
+            raise RuntimeError("Socket.IO server not available")
+
+        self.logger.debug(f"Socket.IO server available: {type(self.server.core.sio)}")
+
+        registered_count = 0
+        for handler in self.handlers:
+            try:
+                self.logger.debug(
+                    f"Registering events for {handler.__class__.__name__}"
+                )
+
+                # Get the number of registered events before and after
+                sio_events_before = len(getattr(self.server.core.sio, "handlers", {}))
+
+                handler.register_events()
+
+                sio_events_after = len(getattr(self.server.core.sio, "handlers", {}))
+                events_added = sio_events_after - sio_events_before
+
+                registered_count += 1
+                self.logger.info(
+                    f"✅ Registered {events_added} 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__}"
+                )
+            except Exception as 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()}")
+
+        # Final verification
+        total_sio_events = len(getattr(self.server.core.sio, "handlers", {}))
+        self.logger.info(
+            f"🎉 Event registration complete: {registered_count} handlers processed, "
+            f"{total_sio_events} total Socket.IO events registered"
+        )
+
+    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)
+            handler.register_events()
+            self.logger.info(f"Added and registered handler: {handler_class.__name__}")
+        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