claude-mpm 4.13.2__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/services/agents/deployment/pipeline/steps/target_directory_step.py

@@ -3,7 +3,9 @@
 import time
 from pathlib import Path
 
-from .base_step import BaseDeploymentStep, StepResult, StepStatus
+from claude_mpm.core.enums import OperationResult
+
+from .base_step import BaseDeploymentStep, StepResult
 
 
 class TargetDirectorySetupStep(BaseDeploymentStep):
@@ -59,7 +61,7 @@ class TargetDirectorySetupStep(BaseDeploymentStep):
             context.step_timings[self.name] = execution_time
 
             return StepResult(
-                status=StepStatus.SUCCESS,
+                status=OperationResult.SUCCESS,
                 message=f"Target directory set up at {context.actual_target_dir} in {execution_time:.3f}s",
                 execution_time=execution_time,
             )
@@ -73,7 +75,7 @@ class TargetDirectorySetupStep(BaseDeploymentStep):
             context.add_error(error_msg)
 
             return StepResult(
-                status=StepStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=error_msg,
                 error=e,
                 execution_time=execution_time,

claude_mpm/services/agents/deployment/pipeline/steps/validation_step.py

@@ -2,9 +2,10 @@
 
 import time
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.services.agents.deployment.validation import DeploymentValidator
 
-from .base_step import BaseDeploymentStep, StepResult, StepStatus
+from .base_step import BaseDeploymentStep, StepResult
 
 
 class ValidationStep(BaseDeploymentStep):
@@ -49,13 +50,13 @@ class ValidationStep(BaseDeploymentStep):
 
             # Determine step status
             if not validation_result.is_valid:
-                status = StepStatus.FAILURE
+                status = OperationResult.FAILED
                 message = f"Validation failed with {validation_result.error_count} errors in {execution_time:.3f}s"
             elif validation_result.has_warnings:
-                status = StepStatus.WARNING
+                status = OperationResult.WARNING
                 message = f"Validation completed with {validation_result.warning_count} warnings in {execution_time:.3f}s"
             else:
-                status = StepStatus.SUCCESS
+                status = OperationResult.SUCCESS
                 message = f"Validation passed successfully in {execution_time:.3f}s"
 
             self.logger.info(message)
@@ -73,7 +74,7 @@ class ValidationStep(BaseDeploymentStep):
             context.add_error(error_msg)
 
             return StepResult(
-                status=StepStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=error_msg,
                 error=e,
                 execution_time=execution_time,

claude_mpm/services/agents/deployment/refactored_agent_deployment_service.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.interfaces import AgentDeploymentInterface
 from claude_mpm.core.logger import get_logger
 
@@ -116,8 +117,10 @@ class RefactoredAgentDeploymentService(AgentDeploymentInterface):
             )
 
             # Ensure success field is present
-            if "success" not in results:
-                results["success"] = not bool(results.get("errors", []))
+            if OperationResult.SUCCESS.value not in results:
+                results[OperationResult.SUCCESS.value] = not bool(
+                    results.get("errors", [])
+                )
 
             self.logger.info(f"Deployment completed: {results.get('success', False)}")
             return results
@@ -125,7 +128,7 @@ class RefactoredAgentDeploymentService(AgentDeploymentInterface):
         except Exception as e:
             self.logger.error(f"Deployment failed: {e}", exc_info=True)
             return {
-                "success": False,
+                OperationResult.SUCCESS.value: False,
                 "error": str(e),
                 "deployed": [],
                 "updated": [],
@@ -235,7 +238,7 @@ class RefactoredAgentDeploymentService(AgentDeploymentInterface):
             # Build status information
             return {
                 "service_version": "refactored-1.0.0",
-                "status": "ready",
+                "status": OperationResult.SUCCESS,
                 "templates_dir": str(self.templates_dir),
                 "base_agent_path": str(self.base_agent_path),
                 "working_directory": str(self.working_directory),
@@ -255,7 +258,7 @@ class RefactoredAgentDeploymentService(AgentDeploymentInterface):
             self.logger.error(f"Failed to get deployment status: {e}", exc_info=True)
             return {
                 "service_version": "refactored-1.0.0",
-                "status": "error",
+                "status": OperationResult.ERROR,
                 "error": str(e),
             }
 
@@ -301,7 +304,7 @@ class RefactoredAgentDeploymentService(AgentDeploymentInterface):
         except Exception as e:
             self.logger.error(f"Async deployment failed: {e}", exc_info=True)
             return {
-                "success": False,
+                OperationResult.SUCCESS.value: False,
                 "error": str(e),
                 "deployed": [],
                 "updated": [],

claude_mpm/services/agents/deployment/validation/__init__.py

@@ -5,10 +5,12 @@ including template validation, agent file validation, and
 deployment environment validation.
 """
 
+from claude_mpm.core.enums import ValidationSeverity
+
 from .agent_validator import AgentValidator
 from .deployment_validator import DeploymentValidator
 from .template_validator import TemplateValidator
-from .validation_result import ValidationResult, ValidationSeverity
+from .validation_result import ValidationResult
 
 __all__ = [
     "AgentValidator",

claude_mpm/services/agents/deployment/validation/validation_result.py

@@ -1,17 +1,9 @@
 """Validation result classes for deployment validation."""
 
 from dataclasses import dataclass, field
-from enum import Enum
 from typing import Any, Dict, List, Optional
 
-
-class ValidationSeverity(Enum):
-    """Severity levels for validation issues."""
-
-    INFO = "info"
-    WARNING = "warning"
-    ERROR = "error"
-    CRITICAL = "critical"
+from claude_mpm.core.enums import ValidationSeverity
 
 
 @dataclass

claude_mpm/services/agents/local_template_manager.py

@@ -182,7 +182,7 @@ class LocalAgentTemplateManager:
             self._discover_templates_in_dir(self.user_agents_dir, "user")
 
         self._cache_valid = True
-        logger.info(f"Discovered {len(self._template_cache)} local agent templates")
+        logger.debug(f"Discovered {len(self._template_cache)} local agent templates")
 
         return self._template_cache
 

claude_mpm/services/agents/memory/agent_memory_manager.py

@@ -25,6 +25,7 @@ import logging
 from typing import Any, ClassVar, Dict, List, Optional, Tuple
 
 from claude_mpm.core.config import Config
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.interfaces import MemoryServiceInterface
 from claude_mpm.core.unified_paths import get_path_manager
 
@@ -596,9 +597,10 @@ class AgentMemoryManager(MemoryServiceInterface):
         """
         # Deprecated - return informative message
         return {
-            "status": "deprecated",
+            "status": OperationResult.ERROR,  # Deprecated function - calling it is an error
             "message": "Cross-reference analysis has been deprecated in favor of simplified memory management",
             "suggestion": "Use get_memory_status() for memory overview",
+            "deprecated": True,
         }
 
     def get_all_memories_raw(self) -> Dict[str, Any]:
@@ -613,9 +615,10 @@ class AgentMemoryManager(MemoryServiceInterface):
         """
         # Deprecated - return informative message
         return {
-            "status": "deprecated",
+            "status": OperationResult.ERROR,  # Deprecated function - calling it is an error
             "message": "Raw memory access has been deprecated in favor of simplified memory management",
             "suggestion": "Use load_agent_memory() for specific agent memories",
+            "deprecated": True,
         }
 
     def _save_memory_file_wrapper(self, agent_id: str, content: str) -> bool:

claude_mpm/services/agents/registry/modification_tracker.py

@@ -36,6 +36,7 @@ from watchdog.events import FileSystemEvent, FileSystemEventHandler
 from watchdog.observers import Observer
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.core.unified_agent_registry import UnifiedAgentRegistry as AgentRegistry
 from claude_mpm.core.unified_paths import get_path_manager
@@ -551,12 +552,14 @@ class AgentModificationTracker(BaseService):
                     errors.append(f"File does not exist: {modification.file_path}")
 
             # Update validation status
-            modification.validation_status = "failed" if errors else "passed"
+            modification.validation_status = (
+                OperationResult.FAILED if errors else OperationResult.SUCCESS
+            )
             modification.validation_errors = errors
 
         except Exception as e:
             self.logger.error(f"Validation error: {e}")
-            modification.validation_status = "error"
+            modification.validation_status = OperationResult.ERROR
             modification.validation_errors.append(str(e))
 
     async def _invalidate_agent_cache(self, agent_name: str) -> None:

claude_mpm/services/command_handler_service.py

@@ -12,6 +12,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 from typing import Any, Dict, List
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.services.core.interfaces import CommandHandlerInterface
 
 
@@ -169,7 +170,7 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             if command == "test":
                 success = self._handle_test_command(args)
                 return {
-                    "success": success,
+                    OperationResult.SUCCESS.value: success,
                     "command": command,
                     "args": args,
                     "message": (
@@ -179,7 +180,7 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             if command == "agents":
                 success = self._handle_agents_command(args)
                 return {
-                    "success": success,
+                    OperationResult.SUCCESS.value: success,
                     "command": command,
                     "args": args,
                     "message": (
@@ -189,14 +190,19 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
                     ),
                 }
             return {
-                "success": False,
+                OperationResult.SUCCESS.value: False,
                 "command": command,
                 "args": args,
-                "error": f"Unknown command: {command}",
+                OperationResult.ERROR.value: f"Unknown command: {command}",
                 "available_commands": self.get_available_commands(),
             }
         except Exception as e:
-            return {"success": False, "command": command, "args": args, "error": str(e)}
+            return {
+                OperationResult.SUCCESS.value: False,
+                "command": command,
+                "args": args,
+                OperationResult.ERROR.value: str(e),
+            }
 
     def get_command_help(self, command: str) -> str:
         """Get help text for a specific command.

claude_mpm/services/core/interfaces/__init__.py

@@ -43,6 +43,12 @@ from .communication import (  # WebSocket/SocketIO; Project analysis; Ticket man
     TicketManagerInterface,
 )
 
+# Health interfaces (health monitoring)
+from .health import (  # Health checks; Health monitoring
+    IHealthCheck,
+    IHealthCheckManager,
+)
+
 # Infrastructure interfaces (core framework services)
 from .infrastructure import (  # Type variables; Core dependency injection; Configuration management; Caching; Health monitoring; Template management; Service factory; Logging; Service lifecycle; Error handling; Performance monitoring; Event system
     CacheEntry,
@@ -65,11 +71,33 @@ from .infrastructure import (  # Type variables; Core dependency injection; Conf
     TemplateRenderContext,
 )
 
+# Model interfaces (content processing and model providers)
+from .model import (  # Model providers; Routing
+    IModelProvider,
+    IModelRouter,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+)
+
+# Process interfaces (local process management)
+from .process import (  # Process lifecycle; State persistence
+    IDeploymentStateManager,
+    ILocalProcessManager,
+)
+
 # Project interfaces (project analysis and toolchain detection)
 from .project import (  # Toolchain analysis
     IToolchainAnalyzer,
 )
 
+# Restart interfaces (auto-restart management)
+from .restart import (  # Crash detection; Restart policy; Restart orchestration
+    ICrashDetector,
+    IRestartManager,
+    IRestartPolicy,
+)
+
 # Service interfaces (business services)
 from .service import (  # Version service; Command handling; Memory management; Session management; Utilities; Hook service
     CommandHandlerInterface,
@@ -81,6 +109,13 @@ from .service import (  # Version service; Command handling; Memory management;
     VersionServiceInterface,
 )
 
+# Stability interfaces (proactive monitoring and crash prevention)
+from .stability import (  # Memory leak detection; Log monitoring; Resource monitoring
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IResourceMonitor,
+)
+
 
 # Interface registry for dependency injection discovery
 class InterfaceRegistry:
@@ -129,6 +164,23 @@ class InterfaceRegistry:
         "toolchain_analyzer": IToolchainAnalyzer,
         "agent_recommender": IAgentRecommender,
         "auto_config_manager": IAutoConfigManager,
+        # Model interfaces
+        "model_provider": IModelProvider,
+        "model_router": IModelRouter,
+        # Process interfaces
+        "deployment_state_manager": IDeploymentStateManager,
+        "local_process_manager": ILocalProcessManager,
+        # Health interfaces
+        "health_check": IHealthCheck,
+        "health_check_manager": IHealthCheckManager,
+        # Restart interfaces
+        "crash_detector": ICrashDetector,
+        "restart_policy": IRestartPolicy,
+        "restart_manager": IRestartManager,
+        # Stability interfaces
+        "memory_leak_detector": IMemoryLeakDetector,
+        "log_monitor": ILogMonitor,
+        "resource_monitor": IResourceMonitor,
     }
 
     @classmethod
@@ -153,7 +205,7 @@ class InterfaceRegistry:
 
 
 # Re-export everything for backward compatibility
-__all__ = [
+__all__ = [  # noqa: RUF022 - Semantic grouping by domain preferred over alphabetical
     "AgentCapabilitiesInterface",
     "AgentDeploymentInterface",
     "AgentMetadata",
@@ -168,12 +220,29 @@ __all__ = [
     "ICacheService",
     "IConfigurationManager",
     "IConfigurationService",
+    # Process interfaces
+    "IDeploymentStateManager",
     "IErrorHandler",
     "IEventBus",
+    # Health interfaces
+    "IHealthCheck",
+    "IHealthCheckManager",
     "IHealthMonitor",
+    # Infrastructure interfaces
+    "ILocalProcessManager",
+    # Restart interfaces
+    "ICrashDetector",
+    "IRestartManager",
+    "IRestartPolicy",
+    # Stability interfaces
+    "IMemoryLeakDetector",
+    "ILogMonitor",
+    "IResourceMonitor",
+    # Model interfaces
+    "IModelProvider",
+    "IModelRouter",
     "IPerformanceMonitor",
     "IPromptCache",
-    # Infrastructure interfaces
     "IServiceContainer",
     "IServiceFactory",
     "IServiceLifecycle",
@@ -183,6 +252,9 @@ __all__ = [
     "IToolchainAnalyzer",
     # Registry
     "InterfaceRegistry",
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
     "MemoryHookInterface",
     "MemoryServiceInterface",
     "ProjectAnalyzerInterface",

claude_mpm/services/core/interfaces/health.py

@@ -0,0 +1,172 @@
+"""
+Health Check Interfaces for Claude MPM Framework
+=================================================
+
+WHY: This module defines interfaces for health monitoring operations,
+enabling the local-ops-agent to perform comprehensive health checks on
+deployed processes including HTTP endpoints, process status, and resource usage.
+
+DESIGN DECISION: Health check interfaces are separated to enable modular
+health monitoring with different check types (HTTP, process, resource).
+
+ARCHITECTURE:
+- IHealthCheck: Interface for individual health check implementations
+- IHealthCheckManager: Interface for orchestrating multiple health checks
+- Health data models defined in models/health.py
+
+USAGE:
+    http_check = HttpHealthCheck(endpoint="http://localhost:3000/health")
+    process_check = ProcessHealthCheck(process_manager)
+    resource_check = ResourceHealthCheck(process_manager)
+
+    health_manager = HealthCheckManager(
+        process_manager=process_manager,
+        check_interval=30
+    )
+    health_manager.start_monitoring()
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from claude_mpm.services.core.models.health import (
+    DeploymentHealth,
+    HealthCheckResult,
+)
+
+
+class IHealthCheck(ABC):
+    """
+    Interface for individual health check implementations.
+
+    WHY: Abstracts different types of health checks (HTTP, process, resource)
+    to enable flexible health monitoring strategies.
+
+    DESIGN DECISION: Each check type implements this interface to provide
+    a consistent API for executing checks and interpreting results.
+
+    Thread Safety: Implementations must be thread-safe for concurrent execution.
+    """
+
+    @abstractmethod
+    def check(self, deployment_id: str, **kwargs) -> HealthCheckResult:
+        """
+        Execute the health check for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            **kwargs: Check-specific parameters (e.g., endpoint URL, thresholds)
+
+        Returns:
+            HealthCheckResult with check status and details
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def get_check_type(self) -> str:
+        """
+        Get the type identifier for this health check.
+
+        Returns:
+            Check type string (e.g., "http", "process", "resource")
+        """
+
+
+class IHealthCheckManager(ABC):
+    """
+    Interface for coordinating health checks across deployments.
+
+    WHY: Health monitoring requires orchestrating multiple check types,
+    aggregating results, and maintaining historical data. This interface
+    provides a high-level API for comprehensive health monitoring.
+
+    DESIGN DECISION: Provides both synchronous (check_health) and asynchronous
+    (background monitoring) operations to support different use cases.
+
+    Background Monitoring:
+    - Runs health checks at regular intervals
+    - Maintains historical health data
+    - Triggers callbacks on status changes
+    - Thread-safe with proper locking
+    """
+
+    @abstractmethod
+    def check_health(self, deployment_id: str) -> DeploymentHealth:
+        """
+        Execute all health checks for a deployment.
+
+        WHY: Provides a comprehensive health snapshot by running all
+        registered health checks and aggregating results.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            DeploymentHealth with aggregated status and check results
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def start_monitoring(self) -> None:
+        """
+        Start background health monitoring.
+
+        WHY: Enables continuous health tracking without manual polling.
+        Monitoring runs in a separate daemon thread.
+
+        Thread Safety: Creates a daemon thread that performs periodic checks.
+        """
+
+    @abstractmethod
+    def stop_monitoring(self) -> None:
+        """
+        Stop background health monitoring.
+
+        WHY: Gracefully stops the monitoring thread and releases resources.
+        """
+
+    @abstractmethod
+    def is_monitoring(self) -> bool:
+        """
+        Check if background monitoring is active.
+
+        Returns:
+            True if monitoring thread is running
+        """
+
+    @abstractmethod
+    def get_health_history(
+        self, deployment_id: str, limit: int = 10
+    ) -> List[DeploymentHealth]:
+        """
+        Get historical health check results for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            limit: Maximum number of historical entries to return
+
+        Returns:
+            List of DeploymentHealth objects, newest first
+        """
+
+    @abstractmethod
+    def register_status_callback(self, callback) -> None:
+        """
+        Register a callback for health status changes.
+
+        WHY: Enables reactive behavior based on health status changes
+        (e.g., alerts, auto-recovery, logging).
+
+        Args:
+            callback: Function called with (deployment_id, old_status, new_status)
+        """
+
+
+__all__ = [
+    "IHealthCheck",
+    "IHealthCheckManager",
+]