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

claude_mpm/services/core/interfaces/restart.py

@@ -0,0 +1,307 @@
+"""
+Restart Management Interfaces for Claude MPM Framework
+========================================================
+
+WHY: This module defines interfaces for auto-restart functionality with crash
+detection, intelligent restart policies, and circuit breaker patterns.
+
+DESIGN DECISION: Restart interfaces are separated to enable modular restart
+management with different crash detection strategies and restart policies.
+
+ARCHITECTURE:
+- ICrashDetector: Interface for detecting process crashes and failures
+- IRestartPolicy: Interface for restart decision logic with backoff
+- IRestartManager: Interface for orchestrating the full restart workflow
+
+USAGE:
+    crash_detector = CrashDetector(health_manager)
+    restart_policy = RestartPolicy(config)
+    restart_manager = RestartManager(
+        process_manager=process_manager,
+        health_manager=health_manager,
+        config=config
+    )
+    restart_manager.enable_auto_restart(deployment_id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from claude_mpm.services.core.models.restart import RestartHistory
+
+
+class ICrashDetector(ABC):
+    """
+    Interface for detecting process crashes and failures.
+
+    WHY: Crash detection requires monitoring health status changes, process
+    exits, and zombie states. This interface abstracts different detection
+    strategies to enable flexible crash monitoring.
+
+    DESIGN DECISION: Integrates with IHealthCheckManager via callbacks to
+    receive real-time status updates. Tracks crash history per deployment
+    to enable pattern detection.
+
+    Thread Safety: Implementations must be thread-safe for concurrent monitoring.
+    """
+
+    @abstractmethod
+    def register_crash_callback(self, callback: Callable[[str, str], None]) -> None:
+        """
+        Register a callback to be invoked when a crash is detected.
+
+        Args:
+            callback: Function called with (deployment_id, reason)
+        """
+
+    @abstractmethod
+    def start_monitoring(self, deployment_id: str) -> None:
+        """
+        Start monitoring a deployment for crashes.
+
+        WHY: Enables targeted monitoring for specific deployments.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def stop_monitoring(self, deployment_id: str) -> None:
+        """
+        Stop monitoring a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def is_monitoring(self, deployment_id: str) -> bool:
+        """
+        Check if a deployment is being monitored.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if deployment is being monitored
+        """
+
+    @abstractmethod
+    def get_crash_count(self, deployment_id: str) -> int:
+        """
+        Get the number of crashes detected for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Number of crashes detected
+        """
+
+
+class IRestartPolicy(ABC):
+    """
+    Interface for restart decision logic with exponential backoff.
+
+    WHY: Restart policies prevent restart loops through exponential backoff,
+    max attempts, and circuit breaker patterns. This interface abstracts
+    the decision-making logic to enable different strategies.
+
+    DESIGN DECISION: Implements exponential backoff with configurable
+    parameters and circuit breaker state transitions (CLOSED → OPEN → HALF_OPEN).
+
+    Circuit Breaker States:
+    - CLOSED: Normal operation, restarts allowed
+    - OPEN: Circuit breaker tripped, restarts blocked
+    - HALF_OPEN: Testing if service recovered
+    """
+
+    @abstractmethod
+    def should_restart(self, deployment_id: str) -> bool:
+        """
+        Determine if a deployment should be restarted.
+
+        WHY: Central decision point that considers attempt count, circuit
+        breaker state, and backoff timing.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if restart should proceed
+        """
+
+    @abstractmethod
+    def calculate_backoff(self, deployment_id: str) -> float:
+        """
+        Calculate backoff time in seconds for next restart.
+
+        WHY: Implements exponential backoff to prevent restart storms.
+        Formula: min(initial * (multiplier ** (attempt - 1)), max_backoff)
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Backoff time in seconds (0 if first attempt)
+        """
+
+    @abstractmethod
+    def record_restart_attempt(
+        self, deployment_id: str, success: bool, failure_reason: Optional[str] = None
+    ) -> None:
+        """
+        Record a restart attempt and update circuit breaker state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            success: Whether restart succeeded
+            failure_reason: Optional reason for failure
+        """
+
+    @abstractmethod
+    def reset_restart_history(self, deployment_id: str) -> None:
+        """
+        Reset restart history for a deployment.
+
+        WHY: Clears restart attempts after successful recovery or manual
+        intervention.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def get_circuit_breaker_state(self, deployment_id: str) -> str:
+        """
+        Get current circuit breaker state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Circuit breaker state (CLOSED, OPEN, HALF_OPEN)
+        """
+
+    @abstractmethod
+    def get_restart_attempt_count(self, deployment_id: str) -> int:
+        """
+        Get number of restart attempts for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Number of restart attempts
+        """
+
+
+class IRestartManager(ABC):
+    """
+    Interface for orchestrating the complete restart workflow.
+
+    WHY: Restart management requires coordinating crash detection, policy
+    evaluation, process restart, and health verification. This interface
+    provides a high-level API for automatic and manual restarts.
+
+    DESIGN DECISION: Provides both automatic (background) and manual
+    (on-demand) restart operations. Integrates with all components:
+    CrashDetector, RestartPolicy, ProcessManager, and HealthCheckManager.
+
+    Restart Workflow:
+    1. Detect crash (via CrashDetector callback)
+    2. Check restart policy (max attempts, circuit breaker)
+    3. Wait for backoff period
+    4. Execute restart (preserve original StartConfig)
+    5. Verify health after restart
+    6. Record attempt and update circuit breaker
+    """
+
+    @abstractmethod
+    def enable_auto_restart(self, deployment_id: str) -> None:
+        """
+        Enable automatic restarts for a deployment.
+
+        WHY: Enables hands-free recovery from crashes. Starts monitoring
+        via CrashDetector and registers restart callbacks.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def disable_auto_restart(self, deployment_id: str) -> None:
+        """
+        Disable automatic restarts for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def is_auto_restart_enabled(self, deployment_id: str) -> bool:
+        """
+        Check if auto-restart is enabled for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if auto-restart is enabled
+        """
+
+    @abstractmethod
+    def restart_deployment(self, deployment_id: str, manual: bool = False) -> bool:
+        """
+        Restart a deployment (manual or automatic trigger).
+
+        WHY: Provides unified restart operation that respects policy
+        constraints and performs health verification.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            manual: If True, bypass some policy checks (e.g., circuit breaker)
+
+        Returns:
+            True if restart succeeded
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def get_restart_history(self, deployment_id: str) -> Optional["RestartHistory"]:
+        """
+        Get restart history for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            RestartHistory if found, None otherwise
+        """
+
+    @abstractmethod
+    def clear_restart_history(self, deployment_id: str) -> None:
+        """
+        Clear restart history and reset circuit breaker.
+
+        WHY: Allows manual intervention to clear failed restart state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+
+__all__ = [
+    "ICrashDetector",
+    "IRestartManager",
+    "IRestartPolicy",
+]

claude_mpm/services/core/interfaces/service.py

@@ -0,0 +1,405 @@
+"""
+Service Management Interfaces for Claude MPM Framework
+=====================================================
+
+WHY: This module contains interfaces for various service operations including
+memory management, hooks, WebSocket/SocketIO communication, project analysis,
+and ticket management. These are grouped as "services" because they provide
+specific business functionality.
+
+DESIGN DECISION: Service interfaces are separated from infrastructure and agent
+interfaces because they represent higher-level business services that build
+upon the infrastructure layer.
+
+EXTRACTED FROM: services/core/interfaces.py (lines 876-1397)
+- Memory service and hooks
+- WebSocket/SocketIO communication
+- Project analysis and ticket management
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# Version service interface
+class VersionServiceInterface(ABC):
+    """Interface for version detection and formatting.
+
+    WHY: Version detection involves multiple fallback methods and different
+    formatting requirements. This interface abstracts version logic to enable
+    different version detection strategies and improve testability.
+
+    DESIGN DECISION: Provides both raw version and formatted version methods
+    to support different display contexts and enable caching of version data.
+    """
+
+    @abstractmethod
+    def get_version(self) -> str:
+        """Get the current version string.
+
+        Returns:
+            Version string in semantic version format
+        """
+
+    @abstractmethod
+    def get_version_info(self) -> Dict[str, Any]:
+        """Get detailed version information.
+
+        Returns:
+            Dictionary with version details and metadata
+        """
+
+    @abstractmethod
+    def format_version_display(self, include_build: bool = False) -> str:
+        """Format version for display purposes.
+
+        Args:
+            include_build: Whether to include build information
+
+        Returns:
+            Formatted version string for display
+        """
+
+    @abstractmethod
+    def check_for_updates(self) -> Dict[str, Any]:
+        """Check for available updates.
+
+        Returns:
+            Dictionary with update information
+        """
+
+
+# Command handler interface
+class CommandHandlerInterface(ABC):
+    """Interface for handling MPM commands.
+
+    WHY: MPM command handling involves parsing, routing, and execution logic
+    that should be separated from the main runner. This interface abstracts
+    command handling to enable different command processing strategies.
+
+    DESIGN DECISION: Commands return structured results to enable consistent
+    error handling and response formatting across different command types.
+    """
+
+    @abstractmethod
+    def handle_command(self, command: str, args: List[str]) -> Dict[str, Any]:
+        """Handle an MPM command.
+
+        Args:
+            command: Command name to execute
+            args: Command arguments
+
+        Returns:
+            Dictionary with command execution results
+        """
+
+    @abstractmethod
+    def get_available_commands(self) -> List[str]:
+        """Get list of available commands.
+
+        Returns:
+            List of available command names
+        """
+
+    @abstractmethod
+    def get_command_help(self, command: str) -> str:
+        """Get help text for a specific command.
+
+        Args:
+            command: Command name
+
+        Returns:
+            Help text for the command
+        """
+
+
+# Memory hook interface
+class MemoryHookInterface(ABC):
+    """Interface for memory hook management.
+
+    WHY: Memory management involves registering hooks at various points in the
+    Claude interaction lifecycle. This interface abstracts memory hook logic
+    to enable different memory management strategies.
+
+    DESIGN DECISION: Provides both hook registration and status methods for
+    comprehensive memory management integration.
+    """
+
+    @abstractmethod
+    def register_memory_hooks(self):
+        """Register memory-related hooks with the hook service."""
+
+    @abstractmethod
+    def unregister_memory_hooks(self):
+        """Unregister memory-related hooks from the hook service."""
+
+    @abstractmethod
+    def get_hook_status(self) -> Dict[str, Any]:
+        """Get status of registered memory hooks.
+
+        Returns:
+            Dictionary with hook status information
+        """
+
+
+# Session management interface
+class SessionManagementInterface(ABC):
+    """Interface for session management and orchestration.
+
+    WHY: Session management involves complex orchestration of multiple services
+    and lifecycle management. This interface abstracts session logic to enable
+    different session management strategies.
+
+    DESIGN DECISION: Provides both synchronous and asynchronous session methods
+    to support different execution contexts and enable proper cleanup.
+    """
+
+    @abstractmethod
+    def start_session(self, session_config: Dict[str, Any]) -> str:
+        """Start a new session.
+
+        Args:
+            session_config: Configuration for the session
+
+        Returns:
+            Session ID
+        """
+
+    @abstractmethod
+    def end_session(self, session_id: str) -> bool:
+        """End an active session.
+
+        Args:
+            session_id: ID of session to end
+
+        Returns:
+            True if session ended successfully
+        """
+
+    @abstractmethod
+    def get_session_status(self, session_id: str) -> Dict[str, Any]:
+        """Get status of a session.
+
+        Args:
+            session_id: ID of session
+
+        Returns:
+            Dictionary with session status information
+        """
+
+    @abstractmethod
+    def list_active_sessions(self) -> List[str]:
+        """List all active session IDs.
+
+        Returns:
+            List of active session IDs
+        """
+
+    @abstractmethod
+    async def cleanup_sessions(self) -> int:
+        """Clean up inactive or expired sessions.
+
+        Returns:
+            Number of sessions cleaned up
+        """
+
+
+# Utility service interface
+class UtilityServiceInterface(ABC):
+    """Interface for utility functions and helper methods.
+
+    WHY: Utility functions are often scattered throughout the codebase and
+    can benefit from centralization. This interface provides a clean way
+    to access common utility functions.
+
+    DESIGN DECISION: Groups related utility functions into logical categories
+    to maintain organization while providing a single access point.
+    """
+
+    @abstractmethod
+    def format_file_size(self, size_bytes: int) -> str:
+        """Format file size in human-readable format.
+
+        Args:
+            size_bytes: Size in bytes
+
+        Returns:
+            Formatted size string (e.g., "1.5 MB")
+        """
+
+    @abstractmethod
+    def format_duration(self, seconds: float) -> str:
+        """Format duration in human-readable format.
+
+        Args:
+            seconds: Duration in seconds
+
+        Returns:
+            Formatted duration string (e.g., "2m 30s")
+        """
+
+    @abstractmethod
+    def sanitize_filename(self, filename: str) -> str:
+        """Sanitize filename for safe filesystem usage.
+
+        Args:
+            filename: Original filename
+
+        Returns:
+            Sanitized filename
+        """
+
+    @abstractmethod
+    def generate_unique_id(self, prefix: str = "") -> str:
+        """Generate a unique identifier.
+
+        Args:
+            prefix: Optional prefix for the ID
+
+        Returns:
+            Unique identifier string
+        """
+
+    @abstractmethod
+    def validate_path(self, path: Path) -> Tuple[bool, Optional[str]]:
+        """Validate a filesystem path.
+
+        Args:
+            path: Path to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+
+
+# Memory service interface
+class MemoryServiceInterface(ABC):
+    """Interface for memory management operations.
+
+    WHY: Memory management is crucial for agent learning and context retention.
+    This interface abstracts memory storage, retrieval, and optimization to
+    enable different backends (file-based, database, distributed cache).
+
+    DESIGN DECISION: Memory operations return success/failure status to enable
+    proper error handling and fallback strategies when memory is unavailable.
+    """
+
+    @abstractmethod
+    def load_memory(self, agent_id: str) -> Optional[str]:
+        """Load memory for a specific agent.
+
+        Args:
+            agent_id: Identifier of the agent
+
+        Returns:
+            Memory content as string or None if not found
+        """
+
+    @abstractmethod
+    def save_memory(self, agent_id: str, content: str) -> bool:
+        """Save memory for a specific agent.
+
+        Args:
+            agent_id: Identifier of the agent
+            content: Memory content to save
+
+        Returns:
+            True if save successful
+        """
+
+    @abstractmethod
+    def validate_memory_size(self, content: str) -> Tuple[bool, Optional[str]]:
+        """Validate memory content size and structure.
+
+        Args:
+            content: Memory content to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+
+    @abstractmethod
+    def optimize_memory(self, agent_id: str) -> bool:
+        """Optimize memory by removing duplicates and consolidating entries.
+
+        Args:
+            agent_id: Identifier of the agent
+
+        Returns:
+            True if optimization successful
+        """
+
+    @abstractmethod
+    def get_memory_stats(self, agent_id: str) -> Dict[str, Any]:
+        """Get memory statistics for an agent.
+
+        Args:
+            agent_id: Identifier of the agent
+
+        Returns:
+            Dictionary with memory statistics
+        """
+
+
+# Hook service interface
+class HookServiceInterface(ABC):
+    """Interface for hook execution operations.
+
+    WHY: Hooks provide extensibility points for the framework, allowing plugins
+    and extensions to modify behavior. This interface ensures consistent hook
+    registration, priority handling, and execution across different hook systems.
+
+    DESIGN DECISION: Hooks support priority ordering and conditional execution
+    to enable complex plugin interactions and performance optimization.
+    """
+
+    @abstractmethod
+    def register_hook(
+        self, hook_name: str, callback: callable, priority: int = 0
+    ) -> str:
+        """Register a hook callback.
+
+        Args:
+            hook_name: Name of the hook point
+            callback: Function to call when hook is triggered
+            priority: Execution priority (higher = earlier)
+
+        Returns:
+            Hook registration ID
+        """
+
+    @abstractmethod
+    def unregister_hook(self, registration_id: str) -> bool:
+        """Unregister a hook callback.
+
+        Args:
+            registration_id: ID returned from register_hook
+
+        Returns:
+            True if unregistration successful
+        """
+
+    @abstractmethod
+    def execute_hook(self, hook_name: str, *args, **kwargs) -> List[Any]:
+        """Execute all callbacks for a hook.
+
+        Args:
+            hook_name: Name of the hook point
+            *args: Positional arguments for callbacks
+            **kwargs: Keyword arguments for callbacks
+
+        Returns:
+            List of callback return values
+        """
+
+    @abstractmethod
+    def get_hook_info(self, hook_name: str) -> Dict[str, Any]:
+        """Get information about registered hooks.
+
+        Args:
+            hook_name: Name of the hook point
+
+        Returns:
+            Dictionary with hook information
+        """