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

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -0,0 +1,229 @@
+"""Connection management service for Claude hook handler.
+
+This service implements the SINGLE-PATH EVENT EMISSION ARCHITECTURE
+to eliminate duplicate events and improve performance.
+
+ARCHITECTURE: Hook → ConnectionManager → Direct Socket.IO → Dashboard
+                                      ↓ (fallback only)
+                                    HTTP POST → Monitor → Dashboard
+
+CRITICAL: This service must maintain the single emission path principle.
+See docs/developer/EVENT_EMISSION_ARCHITECTURE.md for full documentation.
+
+This service manages:
+- SocketIO connection pool initialization
+- Direct event emission with HTTP fallback
+- Connection cleanup
+"""
+
+import os
+import sys
+from datetime import datetime, timezone
+
+# Debug mode is enabled by default for better visibility into hook processing
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+# Import extracted modules with fallback for direct execution
+try:
+    # Try relative imports first (when imported as module)
+    # Use the modern SocketIOConnectionPool instead of the deprecated local one
+    from claude_mpm.core.socketio_pool import get_connection_pool
+except ImportError:
+    # Fall back to absolute imports (when run directly)
+    from pathlib import Path
+
+    # Add parent directory to path
+    sys.path.insert(0, str(Path(__file__).parent))
+
+    # Try to import get_connection_pool from deprecated location
+    try:
+        from connection_pool import SocketIOConnectionPool
+
+        def get_connection_pool():
+            return SocketIOConnectionPool()
+
+    except ImportError:
+        get_connection_pool = None
+
+# Import EventNormalizer for consistent event formatting
+try:
+    from claude_mpm.services.socketio.event_normalizer import EventNormalizer
+except ImportError:
+    # Create a simple fallback EventNormalizer if import fails
+    class EventNormalizer:
+        def normalize(self, event_data, source="hook"):
+            """Simple fallback normalizer that returns event as-is."""
+            return type(
+                "NormalizedEvent",
+                (),
+                {
+                    "to_dict": lambda: {
+                        "event": "mpm_event",
+                        "type": event_data.get("type", "unknown"),
+                        "subtype": event_data.get("subtype", "generic"),
+                        "timestamp": event_data.get(
+                            "timestamp", datetime.now(timezone.utc).isoformat()
+                        ),
+                        "data": event_data.get("data", event_data),
+                    }
+                },
+            )
+
+
+# EventBus removed - using direct Socket.IO calls with HTTP fallback
+# This eliminates duplicate events and improves performance
+
+
+class ConnectionManagerService:
+    """Manages connections for the Claude hook handler."""
+
+    def __init__(self):
+        """Initialize connection management service."""
+        # Event normalizer for consistent event schema
+        self.event_normalizer = EventNormalizer()
+
+        # Initialize SocketIO connection pool for inter-process communication
+        # This sends events directly to the Socket.IO server in the daemon process
+        self.connection_pool = None
+        self._initialize_socketio_pool()
+
+        # EventBus removed - using direct Socket.IO with HTTP fallback only
+
+    def _initialize_socketio_pool(self):
+        """Initialize the SocketIO connection pool."""
+        try:
+            self.connection_pool = get_connection_pool()
+            if DEBUG:
+                print("✅ Modern SocketIO connection pool initialized", file=sys.stderr)
+        except Exception as e:
+            if DEBUG:
+                print(
+                    f"⚠️ Failed to initialize SocketIO connection pool: {e}",
+                    file=sys.stderr,
+                )
+            self.connection_pool = None
+
+    def emit_event(self, namespace: str, event: str, data: dict):
+        """Emit event through direct Socket.IO connection with HTTP fallback.
+
+        🚨 CRITICAL: This method implements the SINGLE-PATH EMISSION ARCHITECTURE.
+        DO NOT add additional emission paths (EventBus, etc.) as this creates duplicates.
+        See docs/developer/EVENT_EMISSION_ARCHITECTURE.md for details.
+
+        High-performance single-path approach:
+        - Primary: Direct Socket.IO connection for ultra-low latency
+        - Fallback: HTTP POST for reliability when direct connection fails
+        - Eliminates duplicate events from multiple emission paths
+        """
+        # Extract tool_call_id from data if present for correlation
+        tool_call_id = data.get("tool_call_id")
+
+        # Create event data for normalization
+        # Extract session_id (try both camelCase and snake_case)
+        session_id = data.get("session_id") or data.get("sessionId")
+
+        # Extract working directory for project identification
+        # Try multiple field names for maximum compatibility
+        cwd = (
+            data.get("cwd")
+            or data.get("working_directory")
+            or data.get("workingDirectory")
+        )
+
+        # For hook_execution events, extract the actual hook type from data
+        # Otherwise use "hook" as the type
+        if event == "hook_execution":
+            hook_type = data.get("hook_type", "unknown")
+            event_type = hook_type
+        else:
+            event_type = "hook"
+
+        raw_event = {
+            "type": event_type,  # Use actual hook type for hook_execution, "hook" otherwise
+            "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop", "execution"
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "data": data,
+            "source": "mpm_hook",  # Identify the source as mpm_hook
+            "session_id": session_id,  # Include session if available (supports both naming conventions)
+            "cwd": cwd,  # Add working directory at top level for easy frontend access
+            "correlation_id": tool_call_id,  # Set from tool_call_id for event correlation
+        }
+
+        # Normalize the event using EventNormalizer for consistent schema
+        normalized_event = self.event_normalizer.normalize(raw_event, source="hook")
+        claude_event_data = normalized_event.to_dict()
+
+        # Log important events for debugging
+        if DEBUG and event in ["subagent_stop", "pre_tool"]:
+            if event == "subagent_stop":
+                agent_type = data.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing SubagentStop for agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+            elif event == "pre_tool" and data.get("tool_name") == "Task":
+                delegation = data.get("delegation_details", {})
+                agent_type = delegation.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing Task delegation to agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+
+        # Emit through direct Socket.IO connection pool (primary path)
+        # This provides ultra-low latency direct async communication
+        if self.connection_pool:
+            try:
+                # Emit to Socket.IO server directly
+                self.connection_pool.emit("mpm_event", claude_event_data)
+                if DEBUG:
+                    print(f"✅ Emitted via connection pool: {event}", file=sys.stderr)
+                return  # Success - no need for fallback
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to emit via connection pool: {e}", file=sys.stderr)
+
+        # HTTP fallback for cross-process communication (when direct calls fail)
+        # This replaces EventBus for reliability without the complexity
+        self._try_http_fallback(claude_event_data)
+
+    def _try_http_fallback(self, claude_event_data: dict):
+        """HTTP fallback when direct Socket.IO connection fails."""
+        try:
+            import requests
+
+            # Send to monitor server HTTP API
+            response = requests.post(
+                "http://localhost:8765/api/events",
+                json=claude_event_data,
+                timeout=2.0,
+                headers={"Content-Type": "application/json"},
+            )
+
+            if response.status_code in [200, 204]:
+                if DEBUG:
+                    print("✅ HTTP fallback successful", file=sys.stderr)
+            elif DEBUG:
+                print(
+                    f"⚠️ HTTP fallback failed: {response.status_code}",
+                    file=sys.stderr,
+                )
+
+        except Exception as e:
+            if DEBUG:
+                print(f"⚠️ HTTP fallback error: {e}", file=sys.stderr)
+
+        # Warn if no emission method is available
+        if not self.connection_pool and DEBUG:
+            print(
+                f"⚠️ No event emission method available for: {claude_event_data.get('event', 'unknown')}",
+                file=sys.stderr,
+            )
+
+    def cleanup(self):
+        """Cleanup connections on service destruction."""
+        # Clean up connection pool if it exists
+        if self.connection_pool:
+            try:
+                self.connection_pool.cleanup()
+            except Exception:
+                pass  # Ignore cleanup errors during destruction

claude_mpm/hooks/claude_hooks/services/connection_manager_http.py

@@ -0,0 +1,254 @@
+"""HTTP-based connection management service for Claude hook handler.
+
+This service manages:
+- HTTP POST event emission for ephemeral hook processes
+- Direct event emission without EventBus complexity
+
+DESIGN DECISION: Use stateless HTTP POST instead of persistent SocketIO
+connections because hook handlers are ephemeral processes (< 1 second lifetime).
+This eliminates disconnection issues and matches the process lifecycle.
+"""
+
+import asyncio
+import os
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+
+# Debug mode is enabled by default for better visibility into hook processing
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+# Import requests for HTTP POST communication
+try:
+    import requests
+
+    REQUESTS_AVAILABLE = True
+except ImportError:
+    REQUESTS_AVAILABLE = False
+    requests = None
+
+# Import high-performance event emitter - lazy loaded in _async_emit()
+# to reduce hook handler initialization time by ~85% (792ms -> minimal)
+
+# Import EventNormalizer for consistent event formatting
+try:
+    from claude_mpm.services.socketio.event_normalizer import EventNormalizer
+except ImportError:
+    # Create a simple fallback EventNormalizer if import fails
+    class EventNormalizer:
+        def normalize(self, event_data, source="hook"):
+            """Simple fallback normalizer that returns event as-is."""
+            return type(
+                "NormalizedEvent",
+                (),
+                {
+                    "to_dict": lambda: {
+                        "event": "claude_event",
+                        "type": event_data.get("type", "unknown"),
+                        "subtype": event_data.get("subtype", "generic"),
+                        "timestamp": event_data.get(
+                            "timestamp", datetime.now(timezone.utc).isoformat()
+                        ),
+                        "data": event_data.get("data", event_data),
+                    }
+                },
+            )
+
+
+# EventBus removed - using direct HTTP POST only
+# This eliminates duplicate events and simplifies the architecture
+
+
+class ConnectionManagerService:
+    """Manages connections for the Claude hook handler using HTTP POST."""
+
+    def __init__(self):
+        """Initialize connection management service."""
+        # Event normalizer for consistent event schema
+        self.event_normalizer = EventNormalizer()
+
+        # Server configuration for HTTP POST
+        self.server_host = os.environ.get("CLAUDE_MPM_SERVER_HOST", "localhost")
+        self.server_port = int(os.environ.get("CLAUDE_MPM_SERVER_PORT", "8765"))
+        self.http_endpoint = f"http://{self.server_host}:{self.server_port}/api/events"
+
+        # EventBus removed - using direct HTTP POST only
+
+        # For backward compatibility with tests
+        self.connection_pool = None  # No longer used
+
+        # Track async emit tasks to prevent garbage collection
+        self._emit_tasks: set = set()
+
+        # Thread pool for non-blocking HTTP requests
+        # WHY: Prevents HTTP POST from blocking hook processing (2s timeout → 0ms blocking)
+        # max_workers=2: Sufficient for low-frequency HTTP fallback events
+        self._http_executor = ThreadPoolExecutor(
+            max_workers=2, thread_name_prefix="http-emit"
+        )
+
+        if DEBUG:
+            print(
+                f"✅ HTTP connection manager initialized - endpoint: {self.http_endpoint}",
+                file=sys.stderr,
+            )
+
+    def emit_event(self, namespace: str, event: str, data: dict):
+        """Emit event using high-performance async emitter with HTTP fallback.
+
+        WHY Hybrid approach:
+        - Direct async calls for ultra-low latency in-process events
+        - HTTP POST fallback for cross-process communication
+        - Connection pooling for memory protection
+        - Automatic routing based on availability
+        """
+        # Create event data for normalization
+        raw_event = {
+            "type": "hook",
+            "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop"
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "data": data,
+            "source": "claude_hooks",  # Identify the source
+            "session_id": data.get("sessionId"),  # Include session if available
+        }
+
+        # Normalize the event using EventNormalizer for consistent schema
+        normalized_event = self.event_normalizer.normalize(raw_event, source="hook")
+        claude_event_data = normalized_event.to_dict()
+
+        # Log important events for debugging
+        if DEBUG and event in ["subagent_stop", "pre_tool"]:
+            if event == "subagent_stop":
+                agent_type = data.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing SubagentStop for agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+            elif event == "pre_tool" and data.get("tool_name") == "Task":
+                delegation = data.get("delegation_details", {})
+                agent_type = delegation.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing Task delegation to agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+
+        # Try high-performance async emitter first (direct calls)
+        success = self._try_async_emit(namespace, event, claude_event_data)
+        if success:
+            return
+
+        # Fallback to HTTP POST for cross-process communication
+        self._try_http_emit(namespace, event, claude_event_data)
+
+    def _try_async_emit(self, namespace: str, event: str, data: dict) -> bool:
+        """Try to emit event using high-performance async emitter."""
+        try:
+            # Run async emission in the current event loop or create one
+            loop = None
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                # No running loop, create a new one
+                pass
+
+            if loop:
+                # We're in an async context, create a task with tracking
+                task = loop.create_task(self._async_emit(namespace, event, data))
+                self._emit_tasks.add(task)
+                task.add_done_callback(self._emit_tasks.discard)
+                # Don't wait for completion to maintain low latency
+                if DEBUG:
+                    print(f"✅ Async emit scheduled: {event}", file=sys.stderr)
+                return True
+            # No event loop, run synchronously
+            success = asyncio.run(self._async_emit(namespace, event, data))
+            if DEBUG and success:
+                print(f"✅ Async emit successful: {event}", file=sys.stderr)
+            return success
+
+        except Exception as e:
+            if DEBUG:
+                print(f"⚠️ Async emit failed: {e}", file=sys.stderr)
+            return False
+
+    async def _async_emit(self, namespace: str, event: str, data: dict) -> bool:
+        """Async helper for event emission."""
+        try:
+            # Lazy load event emitter to reduce initialization overhead
+            from claude_mpm.services.monitor.event_emitter import get_event_emitter
+
+            emitter = await get_event_emitter()
+            return await emitter.emit_event(namespace, "claude_event", data)
+        except ImportError:
+            if DEBUG:
+                print("⚠️ Event emitter not available", file=sys.stderr)
+            return False
+        except Exception as e:
+            if DEBUG:
+                print(f"⚠️ Async emitter error: {e}", file=sys.stderr)
+            return False
+
+    def _try_http_emit(self, namespace: str, event: str, data: dict):
+        """Try to emit event using HTTP POST fallback (non-blocking).
+
+        WHY non-blocking: HTTP POST can take up to 2 seconds (timeout),
+        blocking hook processing. Thread pool makes it fire-and-forget.
+        """
+        if not REQUESTS_AVAILABLE:
+            if DEBUG:
+                print(
+                    "⚠️ requests module not available - cannot emit via HTTP",
+                    file=sys.stderr,
+                )
+            return
+
+        # Submit to thread pool - don't wait for result (fire-and-forget)
+        self._http_executor.submit(self._http_emit_blocking, namespace, event, data)
+
+    def _http_emit_blocking(self, namespace: str, event: str, data: dict):
+        """HTTP emission in background thread (blocking operation isolated)."""
+        try:
+            # Create payload for HTTP API
+            payload = {
+                "namespace": namespace,
+                "event": "claude_event",  # Standard event name for dashboard
+                "data": data,
+            }
+
+            # Send HTTP POST with reasonable timeout
+            response = requests.post(
+                self.http_endpoint,
+                json=payload,
+                timeout=2.0,  # 2 second timeout
+                headers={"Content-Type": "application/json"},
+            )
+
+            if response.status_code in [200, 204]:
+                if DEBUG:
+                    print(f"✅ HTTP POST successful: {event}", file=sys.stderr)
+            elif DEBUG:
+                print(
+                    f"⚠️ HTTP POST failed with status {response.status_code}: {event}",
+                    file=sys.stderr,
+                )
+
+        except requests.exceptions.Timeout:
+            if DEBUG:
+                print(f"⚠️ HTTP POST timeout for: {event}", file=sys.stderr)
+        except requests.exceptions.ConnectionError:
+            if DEBUG:
+                print(
+                    f"⚠️ HTTP POST connection failed for: {event} (server not running?)",
+                    file=sys.stderr,
+                )
+        except Exception as e:
+            if DEBUG:
+                print(f"⚠️ HTTP POST error for {event}: {e}", file=sys.stderr)
+
+    def cleanup(self):
+        """Cleanup connections on service destruction."""
+        # Shutdown HTTP executor gracefully
+        if hasattr(self, "_http_executor"):
+            self._http_executor.shutdown(wait=False)
+            if DEBUG:
+                print("✅ HTTP executor shutdown", file=sys.stderr)

claude_mpm/hooks/claude_hooks/services/duplicate_detector.py

@@ -0,0 +1,106 @@
+"""Duplicate event detection service for Claude hook handler.
+
+This service manages:
+- Event key generation
+- Duplicate event detection within time windows
+- Recent event tracking
+"""
+
+import threading
+import time
+from collections import deque
+
+
+class DuplicateEventDetector:
+    """Detects and filters duplicate events."""
+
+    def __init__(
+        self, max_recent_events: int = 10, duplicate_window_seconds: float = 0.1
+    ):
+        """Initialize duplicate event detector.
+
+        Args:
+            max_recent_events: Maximum number of recent events to track
+            duplicate_window_seconds: Time window in seconds for duplicate detection
+        """
+        # Track recent events to detect duplicates
+        self._recent_events = deque(maxlen=max_recent_events)
+        self._events_lock = threading.Lock()
+        self.duplicate_window_seconds = duplicate_window_seconds
+
+    def is_duplicate(self, event: dict) -> bool:
+        """Check if an event is a duplicate of a recent event.
+
+        Args:
+            event: The event dictionary to check
+
+        Returns:
+            True if the event is a duplicate, False otherwise
+        """
+        event_key = self.generate_event_key(event)
+        current_time = time.time()
+
+        with self._events_lock:
+            # Check if we've seen this event recently
+            for recent_key, recent_time in self._recent_events:
+                if (
+                    recent_key == event_key
+                    and (current_time - recent_time) < self.duplicate_window_seconds
+                ):
+                    return True
+
+            # Not a duplicate, record it
+            self._recent_events.append((event_key, current_time))
+            return False
+
+    def generate_event_key(self, event: dict) -> str:
+        """Generate a unique key for an event to detect duplicates.
+
+        WHY: Claude Code may call the hook multiple times for the same event
+        because the hook is registered for multiple event types. We need to
+        detect and skip duplicate processing while still returning continue.
+
+        Args:
+            event: The event dictionary
+
+        Returns:
+            A unique string key for the event
+        """
+        # Create a key from event type, session_id, and key data
+        hook_type = event.get("hook_event_name", "unknown")
+        session_id = event.get("session_id", "")
+
+        # Add type-specific data to make the key unique
+        if hook_type == "PreToolUse":
+            tool_name = event.get("tool_name", "")
+            # For some tools, include parameters to distinguish calls
+            if tool_name == "Task":
+                tool_input = event.get("tool_input", {})
+                agent = tool_input.get("subagent_type", "")
+                prompt_preview = (
+                    tool_input.get("prompt", "") or tool_input.get("description", "")
+                )[:50]
+                return f"{hook_type}:{session_id}:{tool_name}:{agent}:{prompt_preview}"
+            return f"{hook_type}:{session_id}:{tool_name}"
+
+        if hook_type == "UserPromptSubmit":
+            prompt_preview = event.get("prompt", "")[:50]
+            return f"{hook_type}:{session_id}:{prompt_preview}"
+
+        # For other events, just use type and session
+        return f"{hook_type}:{session_id}"
+
+    def clear_old_events(self):
+        """Clear events older than the duplicate window."""
+        current_time = time.time()
+        cutoff_time = current_time - self.duplicate_window_seconds
+
+        with self._events_lock:
+            # Create a new deque with only recent events
+            recent_only = deque(
+                (key, timestamp)
+                for key, timestamp in self._recent_events
+                if timestamp > cutoff_time
+            )
+            recent_only.maxlen = self._recent_events.maxlen
+            self._recent_events = recent_only