claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__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/interfaces.py

@@ -20,7 +20,62 @@ focused modules for better maintainability and testing.
 """
 
 # Re-export everything from the new modular structure for backward compatibility
-from .interfaces import *
+from .interfaces import (  # noqa: F401
+    AgentCapabilitiesInterface,
+    AgentDeploymentInterface,
+    AgentMetadata,
+    CacheEntry,
+    CommandHandlerInterface,
+    HealthStatus,
+    HookServiceInterface,
+    IAgentRecommender,
+    IAgentRegistry,
+    IAutoConfigManager,
+    ICacheService,
+    IConfigurationManager,
+    IConfigurationService,
+    ICrashDetector,
+    IDeploymentStateManager,
+    IErrorHandler,
+    IEventBus,
+    IHealthCheck,
+    IHealthCheckManager,
+    IHealthMonitor,
+    ILocalProcessManager,
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IModelProvider,
+    IModelRouter,
+    InterfaceRegistry,
+    IPerformanceMonitor,
+    IPromptCache,
+    IResourceMonitor,
+    IRestartManager,
+    IRestartPolicy,
+    IServiceContainer,
+    IServiceFactory,
+    IServiceLifecycle,
+    IStructuredLogger,
+    ITemplateManager,
+    IToolchainAnalyzer,
+    MemoryHookInterface,
+    MemoryServiceInterface,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+    ProjectAnalyzerInterface,
+    RunnerConfigurationInterface,
+    ServiceType,
+    SessionManagementInterface,
+    SocketIOServiceInterface,
+    SubprocessLauncherInterface,
+    SystemInstructionsInterface,
+    T,
+    TemplateRenderContext,
+    TicketManagerInterface,
+    UtilityServiceInterface,
+    VersionServiceInterface,
+)
 
 # All interface definitions have been moved to the interfaces/ package
 # This file now serves as a compatibility layer that delegates to the modular structure