claude-mpm 4.13.2__py3-none-any.whl → 4.18.2__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/stability.py

@@ -0,0 +1,260 @@
+"""
+Stability Monitoring Interfaces for Claude MPM Framework
+==========================================================
+
+WHY: This module defines interfaces for proactive stability monitoring including
+memory leak detection, log monitoring, and resource exhaustion prevention.
+
+DESIGN DECISION: Separated from health checks to enable preventive monitoring
+that triggers actions BEFORE crashes occur. Provides early warning systems.
+
+ARCHITECTURE:
+- IMemoryLeakDetector: Interface for memory leak detection using trend analysis
+- ILogMonitor: Interface for real-time log file monitoring and pattern matching
+- IResourceMonitor: Interface for comprehensive resource usage tracking
+
+USAGE:
+    memory_detector = MemoryLeakDetector(leak_threshold_mb_per_minute=10.0)
+    log_monitor = LogMonitor(log_file="/var/log/app.log")
+    resource_monitor = ResourceMonitor(fd_threshold_percent=0.8)
+
+    # Integrate with health monitoring
+    health_manager.add_stability_monitors(
+        memory_detector=memory_detector,
+        log_monitor=log_monitor,
+        resource_monitor=resource_monitor,
+    )
+"""
+
+from abc import ABC, abstractmethod
+from typing import Callable, List
+
+from claude_mpm.services.core.models.stability import (
+    LogPatternMatch,
+    MemoryTrend,
+    ResourceUsage,
+)
+
+
+class IMemoryLeakDetector(ABC):
+    """
+    Interface for memory leak detection using trend analysis.
+
+    WHY: Memory leaks are a common cause of process crashes. Early detection
+    enables preemptive restarts BEFORE the OOM killer terminates the process.
+
+    DESIGN DECISION: Uses slope-based trend analysis over a rolling window
+    to detect sustained memory growth patterns, filtering out normal variations.
+
+    Algorithm:
+    1. Maintain rolling window of memory measurements (timestamp, memory_mb)
+    2. Calculate linear regression slope (MB per minute)
+    3. Detect leak if slope exceeds threshold (default: 10 MB/minute)
+    4. Trigger alert when leak detected and memory > 80% limit
+
+    Thread Safety: Implementations must be thread-safe for concurrent access.
+    """
+
+    @abstractmethod
+    def record_memory_usage(self, deployment_id: str, memory_mb: float) -> None:
+        """
+        Record a memory usage measurement.
+
+        WHY: Builds historical data for trend analysis. Should be called
+        periodically (e.g., every 30s) to collect sufficient data points.
+
+        Args:
+            deployment_id: Deployment identifier
+            memory_mb: Current memory usage in megabytes
+        """
+
+    @abstractmethod
+    def analyze_trend(self, deployment_id: str) -> MemoryTrend:
+        """
+        Analyze memory usage trend for leak detection.
+
+        WHY: Computes slope of memory usage over time to detect sustained
+        growth patterns characteristic of memory leaks.
+
+        Args:
+            deployment_id: Deployment identifier
+
+        Returns:
+            MemoryTrend with slope analysis and leak detection result
+
+        Algorithm:
+            slope_mb_per_minute = (recent_memory - old_memory) / time_delta_minutes
+            is_leaking = slope_mb_per_minute > threshold
+        """
+
+    @abstractmethod
+    def is_leaking(self, deployment_id: str) -> bool:
+        """
+        Check if deployment has a detected memory leak.
+
+        Returns:
+            True if leak detected (sustained memory growth)
+        """
+
+    @abstractmethod
+    def register_leak_callback(
+        self, callback: Callable[[str, MemoryTrend], None]
+    ) -> None:
+        """
+        Register callback for leak detection events.
+
+        Args:
+            callback: Function called with (deployment_id, trend) when leak detected
+        """
+
+
+class ILogMonitor(ABC):
+    """
+    Interface for real-time log file monitoring and pattern matching.
+
+    WHY: Application logs contain early warning signals (exceptions, OOM errors,
+    segfaults) that predict imminent crashes. Real-time monitoring enables
+    proactive intervention.
+
+    DESIGN DECISION: Uses watchdog library for efficient file system monitoring.
+    Avoids polling by receiving file modification events from the OS.
+
+    Pattern Matching:
+    - Regex-based patterns for flexibility
+    - Configurable patterns per deployment
+    - Built-in patterns for common errors:
+      * OutOfMemoryError
+      * Segmentation fault
+      * Exception: / Traceback
+      * Database connection errors
+      * Network timeouts
+
+    Thread Safety: Uses watchdog's thread-safe event handling.
+    """
+
+    @abstractmethod
+    def start_monitoring(self, log_file: str, deployment_id: str) -> None:
+        """
+        Start monitoring a log file for error patterns.
+
+        WHY: Begins watching the log file for new entries. Uses OS-level
+        file system events for efficiency.
+
+        Args:
+            log_file: Path to log file to monitor
+            deployment_id: Deployment identifier for callbacks
+        """
+
+    @abstractmethod
+    def stop_monitoring(self, deployment_id: str) -> None:
+        """
+        Stop monitoring a deployment's log file.
+
+        Args:
+            deployment_id: Deployment identifier
+        """
+
+    @abstractmethod
+    def add_pattern(self, pattern: str, severity: str = "ERROR") -> None:
+        """
+        Add an error pattern to monitor.
+
+        Args:
+            pattern: Regex pattern to match
+            severity: Error severity (ERROR, CRITICAL, WARNING)
+        """
+
+    @abstractmethod
+    def get_recent_matches(
+        self, deployment_id: str, limit: int = 10
+    ) -> List[LogPatternMatch]:
+        """
+        Get recent pattern matches for a deployment.
+
+        Args:
+            deployment_id: Deployment identifier
+            limit: Maximum number of matches to return
+
+        Returns:
+            List of LogPatternMatch objects, newest first
+        """
+
+    @abstractmethod
+    def register_match_callback(
+        self, callback: Callable[[str, LogPatternMatch], None]
+    ) -> None:
+        """
+        Register callback for pattern matches.
+
+        Args:
+            callback: Function called with (deployment_id, match) when pattern detected
+        """
+
+
+class IResourceMonitor(ABC):
+    """
+    Interface for comprehensive resource usage monitoring.
+
+    WHY: Resource exhaustion (file descriptors, threads, connections, disk space)
+    causes crashes and degradation. Monitoring enables preemptive action at 80%
+    thresholds before hitting hard limits.
+
+    DESIGN DECISION: Extends basic resource health checks with:
+    - Higher granularity (more frequent checks)
+    - Percentage-based thresholds (80% of ulimit)
+    - Trend analysis for growth rate
+    - Integration with restart manager for preemptive restarts
+
+    Resource Types:
+    1. File Descriptors: Critical for I/O operations (Unix: ulimit -n)
+    2. Threads: Memory and scheduling overhead
+    3. Network Connections: Socket exhaustion
+    4. Disk Space: Working directory availability
+
+    Thread Safety: Implementations must be thread-safe.
+    """
+
+    @abstractmethod
+    def check_resources(self, deployment_id: str) -> ResourceUsage:
+        """
+        Check resource usage for a deployment.
+
+        WHY: Provides comprehensive snapshot of resource consumption across
+        all monitored resource types.
+
+        Args:
+            deployment_id: Deployment identifier
+
+        Returns:
+            ResourceUsage with current metrics and critical status
+
+        Raises:
+            ValueError: If deployment not found
+        """
+
+    @abstractmethod
+    def is_critical(self, deployment_id: str) -> bool:
+        """
+        Check if any resource is at critical threshold (>80%).
+
+        Returns:
+            True if any resource exceeds 80% of limit
+        """
+
+    @abstractmethod
+    def register_critical_callback(
+        self, callback: Callable[[str, ResourceUsage], None]
+    ) -> None:
+        """
+        Register callback for critical resource usage.
+
+        Args:
+            callback: Function called with (deployment_id, usage) when critical
+        """
+
+
+__all__ = [
+    "ILogMonitor",
+    "IMemoryLeakDetector",
+    "IResourceMonitor",
+]

claude_mpm/services/core/models/__init__.py

@@ -20,6 +20,24 @@ from .agent_config import (
     ConfigurationResult,
     ValidationResult,
 )
+from .process import (
+    PROTECTED_PORT_RANGES,
+    DeploymentState,
+    ProcessInfo,
+    StartConfig,
+    is_port_protected,
+)
+from .restart import (
+    CircuitBreakerState,
+    RestartAttempt,
+    RestartConfig,
+    RestartHistory,
+)
+from .stability import (
+    LogPatternMatch,
+    MemoryTrend,
+    ResourceUsage,
+)
 from .toolchain import (
     ConfidenceLevel,
     DeploymentTarget,
@@ -43,4 +61,19 @@ __all__ = [  # noqa: RUF022 - Grouped by category with comments for clarity
     "ConfigurationResult",
     "ValidationResult",
     "ConfigurationPreview",
+    # Process management models
+    "DeploymentState",
+    "ProcessInfo",
+    "StartConfig",
+    "PROTECTED_PORT_RANGES",
+    "is_port_protected",
+    # Restart management models
+    "CircuitBreakerState",
+    "RestartAttempt",
+    "RestartHistory",
+    "RestartConfig",
+    # Stability monitoring models
+    "MemoryTrend",
+    "LogPatternMatch",
+    "ResourceUsage",
 ]

claude_mpm/services/core/models/agent_config.py

@@ -17,6 +17,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Dict, List, Optional
 
+from ....core.enums import OperationResult, ValidationSeverity
+
 
 class AgentSpecialization(str, Enum):
     """Agent specialization categories.
@@ -154,20 +156,6 @@ class AgentRecommendation:
         }
 
 
-class ConfigurationStatus(str, Enum):
-    """Status of configuration operation.
-
-    WHY: Configuration can succeed, fail, or partially succeed. This enum
-    provides a standardized way to communicate operation outcomes.
-    """
-
-    SUCCESS = "success"
-    PARTIAL_SUCCESS = "partial_success"
-    FAILURE = "failure"
-    VALIDATION_ERROR = "validation_error"
-    USER_CANCELLED = "user_cancelled"
-
-
 @dataclass
 class ConfigurationResult:
     """Result of automated configuration operation.
@@ -179,9 +167,17 @@ class ConfigurationResult:
     DESIGN DECISION: Separates successful and failed deployments to enable
     proper error handling. Includes validation results and user-facing
     messages for transparency.
+
+    NOTE: Uses core OperationResult enum (consolidated from ConfigurationStatus
+    in Phase 3A Batch 25). Mappings:
+    - SUCCESS → OperationResult.SUCCESS
+    - PARTIAL_SUCCESS → OperationResult.WARNING (partial success with issues)
+    - FAILURE → OperationResult.FAILED
+    - VALIDATION_ERROR → OperationResult.ERROR
+    - USER_CANCELLED → OperationResult.CANCELLED
     """
 
-    status: ConfigurationStatus
+    status: OperationResult
     deployed_agents: List[str] = field(default_factory=list)
     failed_agents: List[str] = field(default_factory=list)
     validation_warnings: List[str] = field(default_factory=list)
@@ -193,7 +189,7 @@ class ConfigurationResult:
     @property
     def is_successful(self) -> bool:
         """Check if configuration was completely successful."""
-        return self.status == ConfigurationStatus.SUCCESS
+        return self.status == OperationResult.SUCCESS
 
     @property
     def has_failures(self) -> bool:
@@ -223,18 +219,6 @@ class ConfigurationResult:
         }
 
 
-class ValidationSeverity(str, Enum):
-    """Severity level for validation issues.
-
-    WHY: Not all validation issues are equally critical. This enum enables
-    categorization of issues by severity to support appropriate handling.
-    """
-
-    ERROR = "error"  # Blocks deployment
-    WARNING = "warning"  # Should be reviewed but doesn't block
-    INFO = "info"  # Informational only
-
-
 @dataclass
 class ValidationIssue:
     """Represents a validation issue.