claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/core/base_service.py

@@ -26,11 +26,12 @@ import traceback
 from abc import ABC, abstractmethod
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from .config import Config
+from .enums import HealthStatus
 from .mixins import LoggerMixin
 
 
@@ -38,7 +39,7 @@ from .mixins import LoggerMixin
 class ServiceHealth:
     """Service health status information."""
 
-    status: str  # healthy, degraded, unhealthy, unknown
+    status: HealthStatus  # Type-safe health status using enum
     message: str
     timestamp: str
     metrics: Dict[str, Any] = field(default_factory=dict)
@@ -142,9 +143,9 @@ class BaseService(LoggerMixin, ABC):
 
         # Health and metrics
         self._health = ServiceHealth(
-            status="unknown",
+            status=HealthStatus.UNKNOWN,
             message="Service not started",
-            timestamp=datetime.now().isoformat(),
+            timestamp=datetime.now(timezone.utc).isoformat(),
         )
         self._metrics = ServiceMetrics()
         self._last_health_check: Optional[float] = None
@@ -199,7 +200,7 @@ class BaseService(LoggerMixin, ABC):
     def uptime(self) -> Optional[float]:
         """Get service uptime in seconds."""
         if self._start_time and self._running:
-            return (datetime.now() - self._start_time).total_seconds()
+            return (datetime.now(timezone.utc) - self._start_time).total_seconds()
         return None
 
     @property
@@ -235,9 +236,9 @@ class BaseService(LoggerMixin, ABC):
         except Exception as e:
             self.logger.error(f"Failed to start service {self.name}: {e}")
             self._health = ServiceHealth(
-                status="unhealthy",
+                status=HealthStatus.UNHEALTHY,
                 message=f"Startup failed: {e!s}",
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 checks={"startup": False},
             )
 
@@ -268,13 +269,13 @@ class BaseService(LoggerMixin, ABC):
 
         # Mark as running
         self._running = True
-        self._start_time = datetime.now()
+        self._start_time = datetime.now(timezone.utc)
 
         # Update health status
         self._health = ServiceHealth(
-            status="healthy",
+            status=HealthStatus.HEALTHY,
             message="Service started successfully",
-            timestamp=datetime.now().isoformat(),
+            timestamp=datetime.now(timezone.utc).isoformat(),
             checks={"startup": True},
             metrics=self._get_health_metrics() if self._enable_enhanced else {},
         )
@@ -336,9 +337,9 @@ class BaseService(LoggerMixin, ABC):
 
         # Update health status
         self._health = ServiceHealth(
-            status="unknown",
+            status=HealthStatus.UNKNOWN,
             message="Service stopped",
-            timestamp=datetime.now().isoformat(),
+            timestamp=datetime.now(timezone.utc).isoformat(),
             checks={"running": False},
         )
 
@@ -372,23 +373,23 @@ class BaseService(LoggerMixin, ABC):
 
             # Determine overall status
             if not checks["running"]:
-                status = "unhealthy"
+                status = HealthStatus.UNHEALTHY
                 message = "Service is not running"
             elif all(checks.values()):
-                status = "healthy"
+                status = HealthStatus.HEALTHY
                 message = "All health checks passed"
             elif any(checks.values()):
-                status = "degraded"
+                status = HealthStatus.DEGRADED
                 message = "Some health checks failed"
             else:
-                status = "unhealthy"
+                status = HealthStatus.UNHEALTHY
                 message = "Multiple health checks failed"
 
             # Update health status
             self._health = ServiceHealth(
                 status=status,
                 message=message,
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 checks=checks,
                 metrics={
                     "uptime": self.uptime,
@@ -402,9 +403,9 @@ class BaseService(LoggerMixin, ABC):
         except Exception as e:
             self.logger.error(f"Health check failed for {self.name}: {e}")
             self._health = ServiceHealth(
-                status="unhealthy",
+                status=HealthStatus.UNHEALTHY,
                 message=f"Health check error: {e!s}",
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 checks={"health_check_error": True},
             )
             return self._health
@@ -428,7 +429,16 @@ class BaseService(LoggerMixin, ABC):
             self.logger.info(
                 f"Received signal {signum}, initiating graceful shutdown..."
             )
-            asyncio.create_task(self.stop())
+            # Get the event loop and create a tracked shutdown task
+            try:
+                loop = asyncio.get_event_loop()
+                task = loop.create_task(self.stop())
+                # Store reference to prevent GC during shutdown
+                if not hasattr(self, "_shutdown_task"):
+                    self._shutdown_task = task
+            except RuntimeError:
+                # No event loop, call stop synchronously
+                self.logger.warning("No event loop available for graceful shutdown")
 
         signal.signal(signal.SIGINT, signal_handler)
         signal.signal(signal.SIGTERM, signal_handler)
@@ -584,9 +594,9 @@ class BaseService(LoggerMixin, ABC):
                     )
                 else:
                     return ServiceHealth(
-                        status="degraded",
+                        status=HealthStatus.DEGRADED,
                         message="Service circuit breaker is open",
-                        timestamp=datetime.now().isoformat(),
+                        timestamp=datetime.now(timezone.utc).isoformat(),
                         checks={"circuit_breaker": False},
                         metrics=self._get_health_metrics(),
                     )
@@ -595,7 +605,7 @@ class BaseService(LoggerMixin, ABC):
             health = await self.health_check()
 
             # Update circuit breaker
-            if health.status in ["healthy", "degraded"]:
+            if health.status in (HealthStatus.HEALTHY, HealthStatus.DEGRADED):
                 self._record_circuit_success()
             else:
                 self._record_circuit_failure()

claude_mpm/core/cache.py

@@ -19,7 +19,7 @@ import pickle
 import threading
 from collections import OrderedDict
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Optional, TypeVar, Union
 
 from ..core.logger import get_logger
@@ -43,12 +43,12 @@ class CacheEntry:
         """Check if entry has expired based on TTL."""
         if self.ttl is None:
             return False
-        age = (datetime.now() - self.created_at).total_seconds()
+        age = (datetime.now(timezone.utc) - self.created_at).total_seconds()
         return age > self.ttl
 
     def touch(self):
         """Update last access time and increment counter."""
-        self.last_accessed = datetime.now()
+        self.last_accessed = datetime.now(timezone.utc)
         self.access_count += 1
 
 
@@ -129,13 +129,13 @@ class FileSystemCache:
             # Rough estimate using JSON serialization
             try:
                 return len(json.dumps(value))
-            except:
+            except Exception:
                 return 1000  # Default estimate
         else:
             # Use pickle for size estimation
             try:
                 return len(pickle.dumps(value))
-            except:
+            except Exception:
                 return 100  # Default small size
 
     def _evict_lru(self):
@@ -288,10 +288,10 @@ class FileSystemCache:
             """Read file from disk."""
             try:
                 if "b" in mode:
-                    with open(file_path, mode) as f:
+                    with Path(file_path).open(mode) as f:
                         return f.read()
                 else:
-                    with open(file_path, mode, encoding=encoding) as f:
+                    with Path(file_path).open(mode, encoding=encoding) as f:
                         return f.read()
             except Exception as e:
                 self._logger.error(f"Failed to read file {file_path}: {e}")
@@ -391,7 +391,7 @@ class FileSystemCache:
 
         try:
             self.persist_path.parent.mkdir(parents=True, exist_ok=True)
-            with open(self.persist_path, "wb") as f:
+            with self.persist_path.open("wb") as f:
                 pickle.dump(self._cache, f)
             self._logger.debug(f"Cache persisted to {self.persist_path}")
         except Exception as e:
@@ -403,7 +403,7 @@ class FileSystemCache:
             return
 
         try:
-            with open(self.persist_path, "rb") as f:
+            with self.persist_path.open("rb") as f:
                 loaded_cache = pickle.load(f)
 
             # Rebuild cache with validation

claude_mpm/core/claude_runner.py

@@ -42,8 +42,19 @@ class ClaudeRunner:
         launch_method: str = "exec",  # "exec" or "subprocess"
         enable_websocket: bool = False,
         websocket_port: int = 8765,
+        use_native_agents: bool = False,  # Use --agents flag instead of file deployment
     ):
-        """Initialize the Claude runner."""
+        """Initialize the Claude runner.
+
+        Args:
+            enable_tickets: Enable ticket extraction (deprecated)
+            log_level: Logging level
+            claude_args: Additional arguments for Claude CLI
+            launch_method: "exec" or "subprocess" launch mode
+            enable_websocket: Enable WebSocket server
+            websocket_port: WebSocket server port
+            use_native_agents: Use --agents CLI flag instead of .claude/agents/ deployment
+        """
         self.logger = get_logger(__name__)
 
         # Initialize configuration service
@@ -75,6 +86,7 @@ class ClaudeRunner:
             launch_method=launch_method,
             enable_websocket=enable_websocket,
             websocket_port=websocket_port,
+            use_native_agents=use_native_agents,
         )
 
         # Set configuration attributes
@@ -84,6 +96,7 @@ class ClaudeRunner:
         self.launch_method = config_data["launch_method"]
         self.enable_websocket = config_data["enable_websocket"]
         self.websocket_port = config_data["websocket_port"]
+        self.use_native_agents = config_data.get("use_native_agents", False)
         self.config = config_data["config"]
 
         # Initialize project logger using the service
@@ -462,13 +475,11 @@ class ClaudeRunner:
                         if (
                             "author: claude-mpm-project" in existing_content
                             or "source: project" in existing_content
-                        ):
-                            # Compare modification times
-                            if target_file.stat().st_mtime >= json_file.stat().st_mtime:
-                                needs_update = False
-                                self.logger.debug(
-                                    f"Project agent {agent_name} is up to date"
-                                )
+                        ) and target_file.stat().st_mtime >= json_file.stat().st_mtime:
+                            needs_update = False
+                            self.logger.debug(
+                                f"Project agent {agent_name} is up to date"
+                            )
 
                     if needs_update:
                         # Build the agent markdown using the pre-initialized service and base agent data

claude_mpm/core/config.py

@@ -14,11 +14,13 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 
 import yaml
 
+from claude_mpm.core.logging_utils import get_logger
+
 from ..utils.config_manager import ConfigurationManager
 from .exceptions import ConfigurationError, FileOperationError
 from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class Config:
@@ -54,7 +56,7 @@ class Config:
                 # Double-check locking pattern for thread safety
                 if cls._instance is None:
                     cls._instance = super().__new__(cls)
-                    logger.info("Creating new Config singleton instance")
+                    logger.debug("Creating new Config singleton instance")
                 else:
                     logger.debug(
                         "Reusing existing Config singleton instance (concurrent init)"
@@ -100,7 +102,7 @@ class Config:
                 return
 
             Config._initialized = True
-            logger.info("Initializing Config singleton for the first time")
+            logger.debug("Initializing Config singleton for the first time")
 
             # Initialize instance variables inside the lock to ensure thread safety
             self._config: Dict[str, Any] = {}
@@ -199,7 +201,7 @@ class Config:
                         # Set flag IMMEDIATELY before logging to prevent any possibility of duplicate
                         # messages. No lock needed here since we're already inside __init__ lock
                         Config._success_logged = True
-                        logger.info(
+                        logger.debug(
                             f"✓ Successfully loaded configuration from {file_path}"
                         )
                     else:
@@ -251,7 +253,7 @@ class Config:
                     "operation": "read",
                     "error_type": type(e).__name__,
                 },
-            )
+            ) from e
         except Exception as e:
             # Catch any remaining unexpected errors and wrap them as configuration errors
             raise ConfigurationError(
@@ -261,7 +263,7 @@ class Config:
                     "error_type": type(e).__name__,
                     "original_error": str(e),
                 },
-            )
+            ) from e
 
     def _load_env_vars(self) -> None:
         """Load configuration from environment variables."""
@@ -527,11 +529,67 @@ class Config:
                     },
                 },
             },
+            # Monitor server configuration (decoupled from dashboard)
+            "monitor_server": {
+                "host": "localhost",
+                "port": 8765,  # Default monitor port (shared with dashboard)
+                "enable_health_monitoring": True,
+                "auto_start": False,  # Don't auto-start with dashboard by default
+                "event_buffer_size": 2000,  # Larger buffer for monitor server
+                "client_timeout": 60,  # Timeout for inactive clients
+            },
+            # Dashboard server configuration (connects to monitor)
+            "dashboard_server": {
+                "host": "localhost",
+                "port": 8765,  # Dashboard UI port
+                "monitor_host": "localhost",  # Monitor server host to connect to
+                "monitor_port": 8765,  # Monitor server port to connect to
+                "auto_connect_monitor": True,  # Automatically connect to monitor
+                "monitor_reconnect": True,  # Auto-reconnect to monitor if disconnected
+                "fallback_standalone": True,  # Run in standalone mode if monitor unavailable
+            },
             # Agent deployment configuration
             "agent_deployment": {
                 "excluded_agents": [],  # List of agent IDs to exclude from deployment
                 "exclude_dependencies": False,  # Whether to exclude agent dependencies too
                 "case_sensitive": False,  # Whether agent name matching is case-sensitive
+                "filter_non_mpm_agents": True,  # Filter out non-MPM agents by default
+                "mpm_author_patterns": [
+                    "claude mpm",
+                    "claude-mpm",
+                    "anthropic",
+                ],  # Patterns for MPM agents
+            },
+            # Instruction reinforcement system configuration
+            "instruction_reinforcement": {
+                "enabled": True,
+                "test_mode": True,
+                "injection_interval": 5,
+                "test_messages": [
+                    "[TEST-REMINDER] This is an injected instruction reminder",
+                    "[PM-INSTRUCTION] Remember to delegate all work to agents",
+                    "[PM-INSTRUCTION] Do not use Edit, Write, or Bash tools directly",
+                    "[PM-INSTRUCTION] Your role is orchestration and coordination",
+                ],
+                "production_messages": [
+                    "[PM-REMINDER] Delegate implementation tasks to specialized agents",
+                    "[PM-REMINDER] Use Task tool for all work delegation",
+                    "[PM-REMINDER] Focus on orchestration, not implementation",
+                    "[PM-REMINDER] Your role is coordination and management",
+                ],
+            },
+            # Session management configuration
+            "session": {
+                "auto_save": True,  # Enable automatic session saving
+                "save_interval": 300,  # Auto-save interval in seconds (5 minutes)
+            },
+            # Update checking configuration
+            "updates": {
+                "check_enabled": True,  # Enable automatic update checks
+                "check_frequency": "daily",  # Options: "always", "daily", "weekly", "never"
+                "check_claude_code": True,  # Check Claude Code version compatibility
+                "auto_upgrade": False,  # Automatically upgrade without prompting (use with caution)
+                "cache_ttl": 86400,  # Cache update check results (24 hours)
             },
         }
 
@@ -543,6 +601,9 @@ class Config:
         # Validate health and recovery configuration
         self._validate_health_recovery_config()
 
+        # Validate session configuration
+        self._validate_session_config()
+
     def get(self, key: str, default: Any = None) -> Any:
         """Get configuration value."""
         # Support nested keys with dot notation
@@ -606,7 +667,7 @@ class Config:
                     "format": format,
                     "error_type": type(e).__name__,
                 },
-            )
+            ) from e
         except Exception as e:
             # Re-raise ConfigurationError as-is, wrap others
             if isinstance(e, ConfigurationError):
@@ -618,7 +679,7 @@ class Config:
                     "format": format,
                     "error_type": type(e).__name__,
                 },
-            )
+            ) from e
 
     def validate(self, schema: Dict[str, Any]) -> bool:
         """
@@ -719,6 +780,40 @@ class Config:
         except Exception as e:
             logger.error(f"Error validating health/recovery configuration: {e}")
 
+    def _validate_session_config(self) -> None:
+        """Validate session management configuration."""
+        try:
+            session_config = self.get("session", {})
+
+            # Validate save_interval range (60-1800 seconds)
+            save_interval = session_config.get("save_interval", 300)
+            if not isinstance(save_interval, int):
+                logger.warning(
+                    f"Session save_interval must be integer, got {type(save_interval).__name__}, using default 300"
+                )
+                self.set("session.save_interval", 300)
+            elif save_interval < 60:
+                logger.warning(
+                    f"Session save_interval must be at least 60 seconds, got {save_interval}, using 60"
+                )
+                self.set("session.save_interval", 60)
+            elif save_interval > 1800:
+                logger.warning(
+                    f"Session save_interval must be at most 1800 seconds (30 min), got {save_interval}, using 1800"
+                )
+                self.set("session.save_interval", 1800)
+
+            # Validate auto_save is boolean
+            auto_save = session_config.get("auto_save", True)
+            if not isinstance(auto_save, bool):
+                logger.warning(
+                    f"Session auto_save must be boolean, got {type(auto_save).__name__}, using True"
+                )
+                self.set("session.auto_save", True)
+
+        except Exception as e:
+            logger.error(f"Error validating session configuration: {e}")
+
     def get_health_monitoring_config(self) -> Dict[str, Any]:
         """Get health monitoring configuration with defaults."""
         base_config = {

claude_mpm/core/config_aliases.py

@@ -14,13 +14,14 @@ Aliases are stored in ~/.claude-mpm/config_aliases.json
 """
 
 import json
-import logging
 from typing import Dict, List, Optional, Tuple
 
+from claude_mpm.core.logging_utils import get_logger
+
 from ..utils.config_manager import ConfigurationManager
 from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class ConfigAliasError(Exception):
@@ -87,7 +88,7 @@ class ConfigAliasManager:
             self.config_mgr.save_json(aliases, self.aliases_file, sort_keys=True)
         except Exception as e:
             logger.error(f"Failed to save aliases: {e}")
-            raise ConfigAliasError(f"Failed to save aliases: {e}")
+            raise ConfigAliasError(f"Failed to save aliases: {e}") from e
 
     def create_alias(self, alias_name: str, directory_path: str) -> None:
         """
@@ -210,7 +211,7 @@ class ConfigAliasManager:
                 except Exception as e:
                     raise InvalidDirectoryError(
                         f"Cannot create directory '{directory_path}': {e}"
-                    )
+                    ) from e
 
             # Verify we can write to the directory
             test_file = directory_path / ".claude_pm_test"
@@ -220,14 +221,14 @@ class ConfigAliasManager:
             except Exception as e:
                 raise InvalidDirectoryError(
                     f"Directory '{directory_path}' is not writable: {e}"
-                )
+                ) from e
 
             return directory_path
 
         except InvalidDirectoryError:
             raise
         except Exception as e:
-            raise InvalidDirectoryError(f"Invalid directory path '{path}': {e}")
+            raise InvalidDirectoryError(f"Invalid directory path '{path}': {e}") from e
 
     def get_alias(self, alias_name: str) -> Optional[str]:
         """

claude_mpm/core/constants.py

@@ -4,6 +4,7 @@ This module consolidates all magic numbers and configuration constants
 that were previously scattered throughout the codebase.
 """
 
+from pathlib import Path
 from typing import Tuple
 
 
@@ -294,3 +295,67 @@ SOCKETIO_PORT_RANGE = NetworkConfig.SOCKETIO_PORT_RANGE
 QUERY_TIMEOUT = TimeoutConfig.QUERY_TIMEOUT
 MAX_RETRIES = RetryConfig.MAX_RETRIES
 DEFAULT_TIMEOUT = TimeoutConfig.DEFAULT_TIMEOUT
+
+
+# ==============================================================================
+# NEW ORGANIZED CONSTANTS (Phase 1 Refactoring)
+# ==============================================================================
+
+
+class NetworkPorts:
+    """Network port configuration."""
+
+    # Use existing values from NetworkConfig
+    DEFAULT_SOCKETIO = NetworkConfig.DEFAULT_SOCKETIO_PORT
+    DEFAULT_DASHBOARD = NetworkConfig.DEFAULT_DASHBOARD_PORT
+    PORT_RANGE_START = NetworkConfig.SOCKETIO_PORT_RANGE[0]
+    PORT_RANGE_END = NetworkConfig.SOCKETIO_PORT_RANGE[1]
+
+    @classmethod
+    def get_port_range(cls) -> range:
+        """Get the valid port range."""
+        return range(cls.PORT_RANGE_START, cls.PORT_RANGE_END + 1)
+
+
+class ProjectPaths:
+    """Project-specific paths and directories."""
+
+    # Claude directories
+    CLAUDE_DIR = ".claude"
+    CLAUDE_AGENTS_DIR = ".claude/agents"
+    CLAUDE_CONFIG_FILE = ".claude/config.yaml"
+
+    # MPM directories
+    MPM_DIR = ".claude-mpm"
+    MPM_SESSION_DIR = ".claude-mpm/session"
+    MPM_PROMPTS_DIR = ".claude-mpm/prompts"
+    MPM_LOGS_DIR = ".claude-mpm/logs"
+    MPM_CONFIG_DIR = ".claude-mpm/config"
+    MPM_MEMORY_DIR = ".claude-mpm/memory"
+    MPM_CACHE_DIR = ".claude-mpm/cache"
+
+    # Config files
+    MPM_CONFIG_FILE = "config.yaml"
+    AGENT_CONFIG_FILE = "agent_config.yaml"
+    EXPERIMENTAL_CONFIG = "experimental.json"
+    SOCKETIO_CONFIG = "socketio_config.yaml"
+
+    # Special files
+    EXPERIMENTAL_ACCEPTED = ".experimental_accepted"
+    VERSION_FILE = "VERSION"
+    BUILD_NUMBER_FILE = "BUILD_NUMBER"
+
+    @classmethod
+    def get_mpm_home(cls) -> Path:
+        """Get the MPM home directory."""
+        return Path.home() / cls.MPM_DIR
+
+    @classmethod
+    def get_project_mpm_dir(cls) -> Path:
+        """Get the project-specific MPM directory."""
+        return Path.cwd() / cls.MPM_DIR
+
+    @classmethod
+    def get_claude_dir(cls) -> Path:
+        """Get the Claude directory."""
+        return Path.cwd() / cls.CLAUDE_DIR

claude_mpm/core/container.py

@@ -538,10 +538,16 @@ class DIContainer(IServiceContainer):
 
             elif registration.lifetime == ServiceLifetime.SCOPED:
                 # Check current scope
-                if self._current_scope:
-                    instance = self._current_scope.get_scoped_instance(service_type)
-                    if instance is not None:
-                        return instance
+                if (
+                    self._current_scope
+                    and (
+                        instance := self._current_scope.get_scoped_instance(
+                            service_type
+                        )
+                    )
+                    is not None
+                ):
+                    return instance
 
             # Mark as resolving
             self._resolving.add(service_type)
@@ -636,7 +642,7 @@ class DIContainer(IServiceContainer):
                                 if reg_type.__name__ == param_type:
                                     param_type = reg_type
                                     break
-                    except:
+                    except Exception:
                         # If we can't resolve, skip this parameter
                         if param.default != param.empty:
                             kwargs[param_name] = param.default