claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/hooks/claude_hooks/memory_integration.py

@@ -7,7 +7,7 @@ including pre and post delegation hooks.
 
 import os
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 
 # Debug mode
@@ -122,7 +122,7 @@ class MemoryHookManager:
                     "session_id": session_id,
                 },
                 metadata={"source": "claude_hook_handler", "tool_name": "Task"},
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 session_id=session_id,
             )
 
@@ -200,7 +200,7 @@ class MemoryHookManager:
                     "tool_name": "Task",
                     "duration_ms": event.get("duration_ms", 0),
                 },
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 session_id=session_id,
             )
 

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -9,29 +9,29 @@ import json
 import os
 import re
 import sys
-from datetime import datetime
-from typing import Optional
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
 
 # Debug mode
 DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
 
 # Response tracking integration
-RESPONSE_TRACKING_AVAILABLE = False
-try:
-    from claude_mpm.services.response_tracker import ResponseTracker
-
-    RESPONSE_TRACKING_AVAILABLE = True
-except Exception as e:
-    if DEBUG:
-        print(f"Response tracking not available: {e}", file=sys.stderr)
-    RESPONSE_TRACKING_AVAILABLE = False
+# NOTE: ResponseTracker import moved to _initialize_response_tracking() for lazy loading
+# This prevents unnecessary import of base_agent_loader and other heavy dependencies
+# when hooks don't need response tracking
+RESPONSE_TRACKING_AVAILABLE = (
+    True  # Assume available, will check on actual initialization
+)
 
 
 class ResponseTrackingManager:
     """Manager for response tracking functionality."""
 
     def __init__(self):
-        self.response_tracker: Optional[ResponseTracker] = None
+        self.response_tracker: Optional[Any] = (
+            None  # Type hint changed to Any for lazy import
+        )
         self.response_tracking_enabled = False
         self.track_all_interactions = (
             False  # Track all Claude interactions, not just delegations
@@ -49,8 +49,14 @@ class ResponseTrackingManager:
 
         DESIGN DECISION: Check configuration to allow enabling/disabling
         response tracking without code changes.
+
+        NOTE: ResponseTracker is imported lazily here to avoid loading
+        base_agent_loader and other heavy dependencies unless actually needed.
         """
         try:
+            # Lazy import of ResponseTracker to avoid unnecessary dependency loading
+            from claude_mpm.services.response_tracker import ResponseTracker
+
             # Create configuration with optional config file using ConfigLoader
             config_file = os.environ.get("CLAUDE_PM_CONFIG_FILE")
             from claude_mpm.core.shared.config_loader import ConfigLoader, ConfigPattern
@@ -59,8 +65,8 @@ class ResponseTrackingManager:
             if config_file:
                 # Use specific config file with ConfigLoader
                 pattern = ConfigPattern(
-                    filenames=[os.path.basename(config_file)],
-                    search_paths=[os.path.dirname(config_file)],
+                    filenames=[Path(config_file).name],
+                    search_paths=[Path(config_file).parent],
                     env_prefix="CLAUDE_MPM_",
                 )
                 config = config_loader.load_config(
@@ -192,7 +198,7 @@ class ResponseTrackingManager:
                 "has_error": bool(event.get("error")),
                 "duration_ms": event.get("duration_ms"),
                 "working_directory": event.get("cwd", ""),
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
                 "tool_name": "Task",
                 "original_request_timestamp": request_info.get("timestamp"),
             }
@@ -262,7 +268,10 @@ class ResponseTrackingManager:
     def track_stop_response(
         self, event: dict, session_id: str, metadata: dict, pending_prompts: dict
     ):
-        """Track response for stop events."""
+        """Track response for stop events.
+
+        Captures Claude API stop_reason and usage data for context management.
+        """
         if not (self.response_tracking_enabled and self.response_tracker):
             return
 
@@ -288,6 +297,37 @@ class ResponseTrackingManager:
                 # Add prompt timestamp to metadata
                 metadata["prompt_timestamp"] = prompt_data.get("timestamp")
 
+                # Capture Claude API stop_reason if available
+                if "stop_reason" in event:
+                    metadata["stop_reason"] = event["stop_reason"]
+                    if DEBUG:
+                        print(
+                            f"  - Captured stop_reason: {event['stop_reason']}",
+                            file=sys.stderr,
+                        )
+
+                # Capture Claude API usage data if available
+                if "usage" in event:
+                    usage_data = event["usage"]
+                    metadata["usage"] = {
+                        "input_tokens": usage_data.get("input_tokens", 0),
+                        "output_tokens": usage_data.get("output_tokens", 0),
+                        "cache_creation_input_tokens": usage_data.get(
+                            "cache_creation_input_tokens", 0
+                        ),
+                        "cache_read_input_tokens": usage_data.get(
+                            "cache_read_input_tokens", 0
+                        ),
+                    }
+                    if DEBUG:
+                        total_tokens = usage_data.get(
+                            "input_tokens", 0
+                        ) + usage_data.get("output_tokens", 0)
+                        print(
+                            f"  - Captured usage: {total_tokens} total tokens",
+                            file=sys.stderr,
+                        )
+
                 # Track the main Claude response
                 file_path = self.response_tracker.track_response(
                     agent_name="claude_main",
@@ -344,7 +384,7 @@ class ResponseTrackingManager:
 
             # Track the response
             metadata = {
-                "timestamp": datetime.now().isoformat(),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
                 "prompt_timestamp": prompt_data.get("timestamp"),
                 "working_directory": prompt_data.get("working_directory", ""),
                 "event_type": "assistant_response",

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -1,15 +1,24 @@
 """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
-- EventBus initialization
-- Event emission through both channels
+- Direct event emission with HTTP fallback
 - Connection cleanup
 """
 
 import os
 import sys
-from datetime import datetime
+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"
@@ -53,7 +62,7 @@ except ImportError:
                         "type": event_data.get("type", "unknown"),
                         "subtype": event_data.get("subtype", "generic"),
                         "timestamp": event_data.get(
-                            "timestamp", datetime.now().isoformat()
+                            "timestamp", datetime.now(timezone.utc).isoformat()
                         ),
                         "data": event_data.get("data", event_data),
                     }
@@ -61,14 +70,8 @@ except ImportError:
             )
 
 
-# Import EventBus for decoupled event distribution
-try:
-    from claude_mpm.services.event_bus import EventBus
-
-    EVENTBUS_AVAILABLE = True
-except ImportError:
-    EVENTBUS_AVAILABLE = False
-    EventBus = None
+# EventBus removed - using direct Socket.IO calls with HTTP fallback
+# This eliminates duplicate events and improves performance
 
 
 class ConnectionManagerService:
@@ -84,9 +87,7 @@ class ConnectionManagerService:
         self.connection_pool = None
         self._initialize_socketio_pool()
 
-        # Initialize EventBus for in-process event distribution (optional)
-        self.event_bus = None
-        self._initialize_eventbus()
+        # EventBus removed - using direct Socket.IO with HTTP fallback only
 
     def _initialize_socketio_pool(self):
         """Initialize the SocketIO connection pool."""
@@ -102,31 +103,23 @@ class ConnectionManagerService:
                 )
             self.connection_pool = None
 
-    def _initialize_eventbus(self):
-        """Initialize the EventBus for in-process distribution."""
-        if EVENTBUS_AVAILABLE:
-            try:
-                self.event_bus = EventBus.get_instance()
-                if DEBUG:
-                    print("✅ EventBus initialized for hook handler", file=sys.stderr)
-            except Exception as e:
-                if DEBUG:
-                    print(f"⚠️ Failed to initialize EventBus: {e}", file=sys.stderr)
-                self.event_bus = None
-
     def emit_event(self, namespace: str, event: str, data: dict):
-        """Emit event through both connection pool and EventBus.
+        """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.
 
-        WHY dual approach:
-        - Connection pool: Direct Socket.IO connection for inter-process communication
-        - EventBus: For in-process subscribers (if any)
-        - Ensures events reach the dashboard regardless of process boundaries
+        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
         """
         # Create event data for normalization
         raw_event = {
             "type": "hook",
             "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop"
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "data": data,
             "source": "claude_hooks",  # Identify the source
             "session_id": data.get("sessionId"),  # Include session if available
@@ -152,33 +145,55 @@ class ConnectionManagerService:
                     file=sys.stderr,
                 )
 
-        # First, try to emit through direct Socket.IO connection pool
-        # This is the primary path for inter-process communication
+        # 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("claude_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)
 
-        # Also publish to EventBus for any in-process subscribers
-        if self.event_bus and EVENTBUS_AVAILABLE:
-            try:
-                # Publish to EventBus with topic format: hook.{event}
-                topic = f"hook.{event}"
-                self.event_bus.publish(topic, claude_event_data)
-                if DEBUG:
-                    print(f"✅ Published to EventBus: {topic}", file=sys.stderr)
-            except Exception as e:
+        # 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(f"⚠️ Failed to publish to EventBus: {e}", file=sys.stderr)
+                    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 neither method is available
-        if not self.connection_pool and not self.event_bus and DEBUG:
-            print(f"⚠️ No event emission method available for: {event}", 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."""
@@ -186,5 +201,5 @@ class ConnectionManagerService:
         if self.connection_pool:
             try:
                 self.connection_pool.cleanup()
-            except:
+            except Exception:
                 pass  # Ignore cleanup errors during destruction

claude_mpm/hooks/claude_hooks/services/connection_manager_http.py

@@ -2,17 +2,18 @@
 
 This service manages:
 - HTTP POST event emission for ephemeral hook processes
-- EventBus initialization (optional)
-- Event emission through both channels
+- 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 datetime import datetime
+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"
@@ -26,6 +27,9 @@ 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
@@ -43,7 +47,7 @@ except ImportError:
                         "type": event_data.get("type", "unknown"),
                         "subtype": event_data.get("subtype", "generic"),
                         "timestamp": event_data.get(
-                            "timestamp", datetime.now().isoformat()
+                            "timestamp", datetime.now(timezone.utc).isoformat()
                         ),
                         "data": event_data.get("data", event_data),
                     }
@@ -51,14 +55,8 @@ except ImportError:
             )
 
 
-# Import EventBus for decoupled event distribution
-try:
-    from claude_mpm.services.event_bus import EventBus
-
-    EVENTBUS_AVAILABLE = True
-except ImportError:
-    EVENTBUS_AVAILABLE = False
-    EventBus = None
+# EventBus removed - using direct HTTP POST only
+# This eliminates duplicate events and simplifies the architecture
 
 
 class ConnectionManagerService:
@@ -74,45 +72,41 @@ class ConnectionManagerService:
         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"
 
-        # Initialize EventBus for in-process event distribution (optional)
-        self.event_bus = None
-        self._initialize_eventbus()
+        # 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 _initialize_eventbus(self):
-        """Initialize the EventBus for in-process distribution."""
-        if EVENTBUS_AVAILABLE:
-            try:
-                self.event_bus = EventBus.get_instance()
-                if DEBUG:
-                    print("✅ EventBus initialized for hook handler", file=sys.stderr)
-            except Exception as e:
-                if DEBUG:
-                    print(f"⚠️ Failed to initialize EventBus: {e}", file=sys.stderr)
-                self.event_bus = None
-
     def emit_event(self, namespace: str, event: str, data: dict):
-        """Emit event using HTTP POST and optionally EventBus.
+        """Emit event using high-performance async emitter with HTTP fallback.
 
-        WHY HTTP POST approach:
-        - Stateless: Perfect for ephemeral hook processes
-        - Fire-and-forget: No connection management needed
-        - Fast: Minimal overhead, no handshake
-        - Reliable: Server handles buffering and retries
+        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().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "data": data,
             "source": "claude_hooks",  # Identify the source
             "session_id": data.get("sessionId"),  # Include session if available
@@ -138,53 +132,123 @@ class ConnectionManagerService:
                     file=sys.stderr,
                 )
 
-        # Primary method: HTTP POST to server
-        # This is fire-and-forget with a short timeout
-        if REQUESTS_AVAILABLE:
+        # 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:
-                # Send HTTP POST with short timeout (fire-and-forget pattern)
-                response = requests.post(
-                    self.http_endpoint,
-                    json=claude_event_data,
-                    timeout=0.5,  # 500ms timeout - don't wait long
-                    headers={"Content-Type": "application/json"},
-                )
-                if DEBUG and response.status_code == 204:
-                    print(f"✅ Emitted via HTTP POST: {event}", file=sys.stderr)
-                elif DEBUG and response.status_code != 204:
-                    print(
-                        f"⚠️ HTTP POST returned status {response.status_code} for: {event}",
-                        file=sys.stderr,
-                    )
-            except requests.exceptions.Timeout:
-                # Timeout is expected for fire-and-forget pattern
-                if DEBUG:
-                    print(f"✅ HTTP POST sent (timeout OK): {event}", file=sys.stderr)
-            except requests.exceptions.ConnectionError:
-                # Server might not be running - this is OK
-                if DEBUG:
-                    print(f"⚠️ Server not available for: {event}", file=sys.stderr)
-            except Exception as e:
+                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"⚠️ Failed to emit via HTTP POST: {e}", file=sys.stderr)
-        elif DEBUG:
-            print(
-                "⚠️ requests module not available - cannot emit via HTTP",
-                file=sys.stderr,
+                    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"},
             )
 
-        # Also publish to EventBus for any in-process subscribers
-        if self.event_bus and EVENTBUS_AVAILABLE:
-            try:
-                # Publish to EventBus with topic format: hook.{event}
-                topic = f"hook.{event}"
-                self.event_bus.publish(topic, claude_event_data)
-                if DEBUG:
-                    print(f"✅ Published to EventBus: {topic}", file=sys.stderr)
-            except Exception as e:
+            if response.status_code in [200, 204]:
                 if DEBUG:
-                    print(f"⚠️ Failed to publish to EventBus: {e}", file=sys.stderr)
+                    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."""
-        # Nothing to cleanup for HTTP POST approach
+        # Shutdown HTTP executor gracefully
+        if hasattr(self, "_http_executor"):
+            self._http_executor.shutdown(wait=False)
+            if DEBUG:
+                print("✅ HTTP executor shutdown", file=sys.stderr)