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

claude_mpm/hooks/claude_hooks/services/container.py

@@ -0,0 +1,310 @@
+"""Dependency Injection container for hook handler services.
+
+This module provides a DI container that manages service instantiation,
+lazy initialization, and service overriding for testing.
+
+WHY DI Container:
+- Centralized service management
+- Lazy initialization reduces startup overhead
+- Easy testing through service overriding
+- Clear dependency graph
+- Thread-safe singleton pattern
+"""
+
+import threading
+from typing import Any, Optional, TypeVar
+
+# Import service protocols for type hints
+from .protocols import (
+    IAutoPauseHandler,
+    IConnectionManager,
+    IDuplicateDetector,
+    IEventHandlers,
+    IMemoryHookManager,
+    IResponseTrackingManager,
+    IStateManager,
+    ISubagentProcessor,
+)
+
+T = TypeVar("T")
+
+
+class HookServiceContainer:
+    """Dependency injection container for hook handler services.
+
+    Features:
+    - Lazy initialization of services
+    - Thread-safe singleton pattern
+    - Service overriding for testing
+    - Automatic dependency resolution
+
+    Usage:
+        # Normal usage (services created lazily)
+        container = HookServiceContainer()
+        state_manager = container.get_state_manager()
+
+        # Testing usage (override services)
+        container = HookServiceContainer()
+        container.override_state_manager(mock_state_manager)
+        state_manager = container.get_state_manager()  # Returns mock
+
+        # Reset overrides
+        container.reset_overrides()
+    """
+
+    # Thread-safe singleton
+    _instance: Optional["HookServiceContainer"] = None
+    _lock = threading.Lock()
+
+    def __new__(cls) -> "HookServiceContainer":
+        """Thread-safe singleton pattern."""
+        if cls._instance is None:
+            with cls._lock:
+                # Double-check locking pattern
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize container if not already initialized."""
+        if getattr(self, "_initialized", False):
+            return
+
+        # Service instances (lazily initialized)
+        self._state_manager: Optional[IStateManager] = None
+        self._connection_manager: Optional[IConnectionManager] = None
+        self._duplicate_detector: Optional[IDuplicateDetector] = None
+        self._response_tracking_manager: Optional[IResponseTrackingManager] = None
+        self._memory_hook_manager: Optional[IMemoryHookManager] = None
+        self._subagent_processor: Optional[ISubagentProcessor] = None
+        self._auto_pause_handler: Optional[IAutoPauseHandler] = None
+        self._event_handlers: Optional[IEventHandlers] = None
+
+        # Override factories for testing
+        self._overrides: dict[str, Any] = {}
+
+        # Lock for lazy initialization
+        self._init_lock = threading.Lock()
+
+        self._initialized = True
+
+    # =========================================================================
+    # Lazy Service Getters
+    # =========================================================================
+
+    def get_state_manager(self) -> IStateManager:
+        """Get or create StateManagerService instance."""
+        if "state_manager" in self._overrides:
+            return self._overrides["state_manager"]
+
+        if self._state_manager is None:
+            with self._init_lock:
+                if self._state_manager is None:
+                    from .state_manager import StateManagerService
+
+                    self._state_manager = StateManagerService()
+        return self._state_manager
+
+    def get_connection_manager(self) -> IConnectionManager:
+        """Get or create ConnectionManagerService instance."""
+        if "connection_manager" in self._overrides:
+            return self._overrides["connection_manager"]
+
+        if self._connection_manager is None:
+            with self._init_lock:
+                if self._connection_manager is None:
+                    from .connection_manager_http import ConnectionManagerService
+
+                    self._connection_manager = ConnectionManagerService()
+        return self._connection_manager
+
+    def get_duplicate_detector(self) -> IDuplicateDetector:
+        """Get or create DuplicateEventDetector instance."""
+        if "duplicate_detector" in self._overrides:
+            return self._overrides["duplicate_detector"]
+
+        if self._duplicate_detector is None:
+            with self._init_lock:
+                if self._duplicate_detector is None:
+                    from .duplicate_detector import DuplicateEventDetector
+
+                    self._duplicate_detector = DuplicateEventDetector()
+        return self._duplicate_detector
+
+    def get_response_tracking_manager(self) -> IResponseTrackingManager:
+        """Get or create ResponseTrackingManager instance."""
+        if "response_tracking_manager" in self._overrides:
+            return self._overrides["response_tracking_manager"]
+
+        if self._response_tracking_manager is None:
+            with self._init_lock:
+                if self._response_tracking_manager is None:
+                    from ..response_tracking import ResponseTrackingManager
+
+                    self._response_tracking_manager = ResponseTrackingManager()
+        return self._response_tracking_manager
+
+    def get_memory_hook_manager(self) -> IMemoryHookManager:
+        """Get or create MemoryHookManager instance."""
+        if "memory_hook_manager" in self._overrides:
+            return self._overrides["memory_hook_manager"]
+
+        if self._memory_hook_manager is None:
+            with self._init_lock:
+                if self._memory_hook_manager is None:
+                    from ..memory_integration import MemoryHookManager
+
+                    self._memory_hook_manager = MemoryHookManager()
+        return self._memory_hook_manager
+
+    def get_auto_pause_handler(self) -> Optional[IAutoPauseHandler]:
+        """Get or create AutoPauseHandler instance.
+
+        Returns None if initialization fails (auto-pause is optional).
+        """
+        if "auto_pause_handler" in self._overrides:
+            return self._overrides["auto_pause_handler"]
+
+        if self._auto_pause_handler is None:
+            with self._init_lock:
+                if self._auto_pause_handler is None:
+                    try:
+                        from ..auto_pause_handler import AutoPauseHandler
+
+                        self._auto_pause_handler = AutoPauseHandler()
+                    except Exception:
+                        # Auto-pause is optional
+                        self._auto_pause_handler = None
+        return self._auto_pause_handler
+
+    def get_subagent_processor(
+        self,
+        state_manager: Optional[IStateManager] = None,
+        response_tracking_manager: Optional[IResponseTrackingManager] = None,
+        connection_manager: Optional[IConnectionManager] = None,
+    ) -> ISubagentProcessor:
+        """Get or create SubagentResponseProcessor instance.
+
+        Args:
+            state_manager: Optional override for state manager
+            response_tracking_manager: Optional override for response tracking
+            connection_manager: Optional override for connection manager
+        """
+        if "subagent_processor" in self._overrides:
+            return self._overrides["subagent_processor"]
+
+        if self._subagent_processor is None:
+            with self._init_lock:
+                if self._subagent_processor is None:
+                    from .subagent_processor import SubagentResponseProcessor
+
+                    # Use provided dependencies or get from container
+                    sm = state_manager or self.get_state_manager()
+                    rtm = (
+                        response_tracking_manager
+                        or self.get_response_tracking_manager()
+                    )
+                    cm = connection_manager or self.get_connection_manager()
+
+                    self._subagent_processor = SubagentResponseProcessor(sm, rtm, cm)
+        return self._subagent_processor
+
+    def get_event_handlers(self, hook_handler: Any = None) -> IEventHandlers:
+        """Get or create EventHandlers instance.
+
+        Args:
+            hook_handler: The ClaudeHookHandler instance for backward compatibility.
+                         In the future, this will be replaced with proper DI.
+        """
+        if "event_handlers" in self._overrides:
+            return self._overrides["event_handlers"]
+
+        if self._event_handlers is None:
+            with self._init_lock:
+                if self._event_handlers is None:
+                    from ..event_handlers import EventHandlers
+
+                    if hook_handler is None:
+                        raise ValueError(
+                            "hook_handler is required to create EventHandlers"
+                        )
+                    self._event_handlers = EventHandlers(hook_handler)
+        return self._event_handlers
+
+    # =========================================================================
+    # Service Override Methods (for testing)
+    # =========================================================================
+
+    def override_state_manager(self, service: IStateManager) -> None:
+        """Override state manager with a mock or custom implementation."""
+        self._overrides["state_manager"] = service
+
+    def override_connection_manager(self, service: IConnectionManager) -> None:
+        """Override connection manager with a mock or custom implementation."""
+        self._overrides["connection_manager"] = service
+
+    def override_duplicate_detector(self, service: IDuplicateDetector) -> None:
+        """Override duplicate detector with a mock or custom implementation."""
+        self._overrides["duplicate_detector"] = service
+
+    def override_response_tracking_manager(
+        self, service: IResponseTrackingManager
+    ) -> None:
+        """Override response tracking manager with a mock or custom implementation."""
+        self._overrides["response_tracking_manager"] = service
+
+    def override_memory_hook_manager(self, service: IMemoryHookManager) -> None:
+        """Override memory hook manager with a mock or custom implementation."""
+        self._overrides["memory_hook_manager"] = service
+
+    def override_subagent_processor(self, service: ISubagentProcessor) -> None:
+        """Override subagent processor with a mock or custom implementation."""
+        self._overrides["subagent_processor"] = service
+
+    def override_auto_pause_handler(self, service: Optional[IAutoPauseHandler]) -> None:
+        """Override auto-pause handler with a mock or custom implementation."""
+        self._overrides["auto_pause_handler"] = service
+
+    def override_event_handlers(self, service: IEventHandlers) -> None:
+        """Override event handlers with a mock or custom implementation."""
+        self._overrides["event_handlers"] = service
+
+    def reset_overrides(self) -> None:
+        """Reset all service overrides."""
+        self._overrides.clear()
+
+    def reset_all(self) -> None:
+        """Reset all services and overrides.
+
+        Useful for testing to ensure clean state between tests.
+        """
+        self._state_manager = None
+        self._connection_manager = None
+        self._duplicate_detector = None
+        self._response_tracking_manager = None
+        self._memory_hook_manager = None
+        self._subagent_processor = None
+        self._auto_pause_handler = None
+        self._event_handlers = None
+        self._overrides.clear()
+
+    @classmethod
+    def reset_singleton(cls) -> None:
+        """Reset the singleton instance.
+
+        USE WITH CAUTION: This is primarily for testing.
+        """
+        with cls._lock:
+            if cls._instance is not None:
+                cls._instance.reset_all()
+            cls._instance = None
+
+
+def get_container() -> HookServiceContainer:
+    """Get the global HookServiceContainer singleton.
+
+    Returns:
+        The singleton HookServiceContainer instance.
+    """
+    return HookServiceContainer()

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."""
+        ...