claude-mpm 5.4.22__py3-none-any.whl → 5.6.34__py3-none-any.whl

claude_mpm/hooks/claude_hooks/services/protocols.py

@@ -0,0 +1,328 @@
+"""Protocol definitions for hook handler services.
+
+This module defines Protocol classes for all hook handler services,
+enabling type-safe dependency injection and easy testing through
+protocol-based duck typing.
+
+WHY Protocol-based DI:
+- Enables loose coupling between components
+- Allows easy mocking in tests without monkey-patching
+- Provides clear interface contracts
+- Supports static type checking with mypy
+"""
+
+from typing import Any, Callable, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IStateManager(Protocol):
+    """Protocol for state management service.
+
+    Manages:
+    - Agent delegation tracking
+    - Git branch caching
+    - Session state management
+    - Cleanup of old entries
+    """
+
+    active_delegations: dict
+    delegation_history: Any  # deque
+    delegation_requests: dict
+    pending_prompts: dict
+    events_processed: int
+
+    def track_delegation(
+        self, session_id: str, agent_type: str, request_data: Optional[dict] = None
+    ) -> None:
+        """Track a new agent delegation with optional request data."""
+        ...
+
+    def get_delegation_agent_type(self, session_id: str) -> str:
+        """Get the agent type for a session's active delegation."""
+        ...
+
+    def cleanup_old_entries(self) -> None:
+        """Clean up old entries to prevent memory growth."""
+        ...
+
+    def get_git_branch(self, working_dir: Optional[str] = None) -> str:
+        """Get git branch for the given directory with caching."""
+        ...
+
+    def find_matching_request(self, session_id: str) -> Optional[dict]:
+        """Find matching request data for a session, with fuzzy matching fallback."""
+        ...
+
+    def remove_request(self, session_id: str) -> None:
+        """Remove request data for a session."""
+        ...
+
+    def increment_events_processed(self) -> bool:
+        """Increment events processed counter and return True if cleanup is needed."""
+        ...
+
+
+@runtime_checkable
+class IConnectionManager(Protocol):
+    """Protocol for connection management service.
+
+    Handles:
+    - HTTP-based event emission to dashboard
+    - Event queuing and batching
+    - Connection state management
+    """
+
+    def emit_event(self, namespace: str, event: str, data: dict) -> None:
+        """Emit an event through HTTP to the dashboard."""
+        ...
+
+    def cleanup(self) -> None:
+        """Clean up any resources."""
+        ...
+
+
+@runtime_checkable
+class IDuplicateDetector(Protocol):
+    """Protocol for duplicate event detection service.
+
+    Detects:
+    - Duplicate events within a time window
+    - Rapid-fire events that should be deduplicated
+    """
+
+    def is_duplicate(self, event: dict) -> bool:
+        """Check if an event is a duplicate of a recent event."""
+        ...
+
+    def generate_event_key(self, event: dict) -> str:
+        """Generate a unique key for an event for deduplication."""
+        ...
+
+
+@runtime_checkable
+class IResponseTrackingManager(Protocol):
+    """Protocol for response tracking management.
+
+    Manages:
+    - Response tracking enablement
+    - Comprehensive response logging
+    - Agent response correlation
+    """
+
+    response_tracking_enabled: bool
+    response_tracker: Optional[Any]
+    track_all_interactions: bool
+    auto_pause_handler: Optional[Any]
+
+    def track_agent_response(
+        self,
+        session_id: str,
+        agent_type: str,
+        event: dict,
+        delegation_requests: dict,
+    ) -> None:
+        """Track an agent response for logging."""
+        ...
+
+    def track_stop_response(
+        self,
+        event: dict,
+        session_id: str,
+        metadata: dict,
+        pending_prompts: dict,
+    ) -> None:
+        """Track a stop event response."""
+        ...
+
+    def track_assistant_response(
+        self,
+        event: dict,
+        pending_prompts: dict,
+    ) -> None:
+        """Track an assistant response."""
+        ...
+
+
+@runtime_checkable
+class IMemoryHookManager(Protocol):
+    """Protocol for memory hook management.
+
+    Manages:
+    - Pre/post delegation memory hooks
+    - Memory field processing
+    """
+
+    def trigger_pre_delegation_hook(
+        self, agent_type: str, tool_input: dict, session_id: str
+    ) -> None:
+        """Trigger memory hooks before delegation."""
+        ...
+
+    def trigger_post_delegation_hook(
+        self, agent_type: str, event: dict, session_id: str
+    ) -> None:
+        """Trigger memory hooks after delegation."""
+        ...
+
+
+@runtime_checkable
+class ISubagentProcessor(Protocol):
+    """Protocol for subagent response processing.
+
+    Handles:
+    - SubagentStop event processing
+    - Structured response extraction
+    - Response tracking and correlation
+    """
+
+    def process_subagent_stop(self, event: dict) -> None:
+        """Handle subagent stop events."""
+        ...
+
+
+@runtime_checkable
+class IAutoPauseHandler(Protocol):
+    """Protocol for auto-pause functionality.
+
+    Manages:
+    - Session pause tracking
+    - Usage threshold monitoring
+    - Session state capture
+    """
+
+    def is_pause_active(self) -> bool:
+        """Check if auto-pause is currently active."""
+        ...
+
+    def on_user_message(self, message: str) -> None:
+        """Record a user message for auto-pause tracking."""
+        ...
+
+    def on_tool_call(self, tool_name: str, tool_input: dict) -> None:
+        """Record a tool call for auto-pause tracking."""
+        ...
+
+    def on_assistant_response(self, response: str) -> None:
+        """Record an assistant response for auto-pause tracking."""
+        ...
+
+    def on_usage_update(self, usage: dict) -> Optional[str]:
+        """Update usage metrics and return threshold crossed if any."""
+        ...
+
+    def emit_threshold_warning(self, threshold: str) -> str:
+        """Emit a warning for a crossed threshold."""
+        ...
+
+    def on_session_end(self) -> Optional[Any]:
+        """Finalize the current auto-pause session."""
+        ...
+
+
+@runtime_checkable
+class IEventHandlers(Protocol):
+    """Protocol for event handler collection.
+
+    Provides handlers for:
+    - UserPromptSubmit
+    - PreToolUse
+    - PostToolUse
+    - Notification
+    - Stop
+    - SubagentStop
+    - SubagentStart
+    - SessionStart
+    - AssistantResponse
+    """
+
+    def handle_user_prompt_fast(self, event: dict) -> None:
+        """Handle user prompt with comprehensive data capture."""
+        ...
+
+    def handle_pre_tool_fast(self, event: dict) -> Optional[dict]:
+        """Handle pre-tool use with comprehensive data capture."""
+        ...
+
+    def handle_post_tool_fast(self, event: dict) -> None:
+        """Handle post-tool use with comprehensive data capture."""
+        ...
+
+    def handle_notification_fast(self, event: dict) -> None:
+        """Handle notification events from Claude."""
+        ...
+
+    def handle_stop_fast(self, event: dict) -> None:
+        """Handle stop events when Claude processing stops."""
+        ...
+
+    def handle_subagent_stop_fast(self, event: dict) -> None:
+        """Handle subagent stop events."""
+        ...
+
+    def handle_subagent_start_fast(self, event: dict) -> None:
+        """Handle SubagentStart events."""
+        ...
+
+    def handle_session_start_fast(self, event: dict) -> None:
+        """Handle session start events."""
+        ...
+
+    def handle_assistant_response(self, event: dict) -> None:
+        """Handle assistant response events."""
+        ...
+
+
+# Type alias for log function
+LogFunction = Callable[[str], None]
+
+
+@runtime_checkable
+class ILogManager(Protocol):
+    """Protocol for log manager service (optional dependency).
+
+    Used for logging agent prompts and responses.
+    """
+
+    async def log_prompt(
+        self, source: str, content: str, metadata: dict
+    ) -> Optional[Any]:
+        """Log a prompt to the log manager."""
+        ...
+
+
+@runtime_checkable
+class IDelegationDetector(Protocol):
+    """Protocol for delegation pattern detector (optional dependency).
+
+    Used for detecting delegation anti-patterns in responses.
+    """
+
+    def detect_user_delegation(self, text: str) -> list[dict]:
+        """Detect delegation patterns in text."""
+        ...
+
+
+@runtime_checkable
+class IEventLog(Protocol):
+    """Protocol for event log service (optional dependency).
+
+    Used for logging PM violations and other events.
+    """
+
+    def append_event(
+        self,
+        event_type: str,
+        payload: dict,
+        status: str = "pending",
+    ) -> None:
+        """Append an event to the log."""
+        ...
+
+
+@runtime_checkable
+class IConfig(Protocol):
+    """Protocol for configuration service (optional dependency)."""
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value."""
+        ...

claude_mpm/hooks/claude_hooks/services/state_manager.py

@@ -8,13 +8,22 @@ This service manages:
 """
 
 import os
-import subprocess
+import subprocess  # nosec B404
 import time
 from collections import deque
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+# Try to import _log from hook_handler, fall back to no-op
+try:
+    from claude_mpm.hooks.claude_hooks.hook_handler import _log
+except ImportError:
+
+    def _log(msg: str) -> None:
+        pass  # Silent fallback
+
+
 # Import constants for configuration
 try:
     from claude_mpm.core.constants import TimeoutConfig
@@ -24,8 +33,8 @@ except ImportError:
         QUICK_TIMEOUT = 2.0
 
 
-# Debug mode is enabled by default for better visibility into hook processing
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+# Debug mode - disabled by default to prevent logging overhead in production
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 
 class StateManagerService:
@@ -63,17 +72,11 @@ class StateManagerService:
     ):
         """Track a new agent delegation with optional request data for response correlation."""
         if DEBUG:
-            import sys
-
-            print(
-                f"  - session_id: {session_id[:16] if session_id else 'None'}...",
-                file=sys.stderr,
-            )
-            print(f"  - agent_type: {agent_type}", file=sys.stderr)
-            print(f"  - request_data provided: {bool(request_data)}", file=sys.stderr)
-            print(
-                f"  - delegation_requests size before: {len(self.delegation_requests)}",
-                file=sys.stderr,
+            _log(f"  - session_id: {session_id[:16] if session_id else 'None'}...")
+            _log(f"  - agent_type: {agent_type}")
+            _log(f"  - request_data provided: {bool(request_data)}")
+            _log(
+                f"  - delegation_requests size before: {len(self.delegation_requests)}"
             )
 
         if session_id and agent_type and agent_type != "unknown":
@@ -89,15 +92,9 @@ class StateManagerService:
                     "timestamp": datetime.now(timezone.utc).isoformat(),
                 }
                 if DEBUG:
-                    import sys
-
-                    print(
-                        f"  - ✅ Stored in delegation_requests[{session_id[:16]}...]",
-                        file=sys.stderr,
-                    )
-                    print(
-                        f"  - delegation_requests size after: {len(self.delegation_requests)}",
-                        file=sys.stderr,
+                    _log(f"  - ✅ Stored in delegation_requests[{session_id[:16]}...]")
+                    _log(
+                        f"  - delegation_requests size after: {len(self.delegation_requests)}"
                     )
 
             # Clean up old delegations (older than 5 minutes)
@@ -197,7 +194,7 @@ class StateManagerService:
             os.chdir(working_dir)
 
             # Run git command to get current branch
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607
                 ["git", "branch", "--show-current"],
                 capture_output=True,
                 text=True,
@@ -233,17 +230,12 @@ class StateManagerService:
     def find_matching_request(self, session_id: str) -> Optional[dict]:
         """Find matching request data for a session, with fuzzy matching fallback."""
         # First try exact match
-        request_info = self.delegation_requests.get(session_id)
+        request_info = self.delegation_requests.get(session_id)  # nosec B113
 
         # If exact match fails, try partial matching
         if not request_info and session_id:
             if DEBUG:
-                import sys
-
-                print(
-                    f"  - Trying fuzzy match for session {session_id[:16]}...",
-                    file=sys.stderr,
-                )
+                _log(f"  - Trying fuzzy match for session {session_id[:16]}...")
             # Try to find a session that matches the first 8-16 characters
             for stored_sid in list(self.delegation_requests.keys()):
                 if (
@@ -256,13 +248,8 @@ class StateManagerService:
                     )
                 ):
                     if DEBUG:
-                        import sys
-
-                        print(
-                            f"  - ✅ Fuzzy match found: {stored_sid[:16]}...",
-                            file=sys.stderr,
-                        )
-                    request_info = self.delegation_requests.get(stored_sid)
+                        _log(f"  - ✅ Fuzzy match found: {stored_sid[:16]}...")
+                    request_info = self.delegation_requests.get(stored_sid)  # nosec B113
                     # Update the key to use the current session_id for consistency
                     if request_info:
                         self.delegation_requests[session_id] = request_info