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

claude_mpm/services/agents/deployment/deployment_config_loader.py

@@ -0,0 +1,178 @@
+"""Deployment configuration loading for agent deployment service.
+
+This module handles loading and processing of deployment configuration.
+Extracted from AgentDeploymentService to reduce complexity and improve maintainability.
+"""
+
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+from claude_mpm.core.config import Config
+
+
+class DeploymentConfigLoader:
+    """Handles loading and processing of deployment configuration."""
+
+    def __init__(self, logger: logging.Logger):
+        """Initialize the config loader with a logger."""
+        self.logger = logger
+
+    def load_deployment_config(self, config: Optional[Config]) -> Tuple[Config, list]:
+        """
+        Load and process deployment configuration.
+
+        Centralized configuration loading reduces duplication
+        and ensures consistent handling of exclusion settings.
+
+        Args:
+            config: Optional configuration object
+
+        Returns:
+            Tuple of (config, excluded_agents)
+        """
+        # Load configuration if not provided
+        if config is None:
+            config = Config()
+
+        # Get new configuration format first, fall back to legacy
+        disabled_agents = config.get("agent_deployment.disabled_agents", [])
+
+        # Fall back to legacy excluded_agents if disabled_agents is empty
+        if not disabled_agents:
+            disabled_agents = config.get("agent_deployment.excluded_agents", [])
+
+        case_sensitive = config.get("agent_deployment.case_sensitive", False)
+        exclude_dependencies = config.get(
+            "agent_deployment.exclude_dependencies", False
+        )
+
+        # Normalize excluded agents list for comparison
+        if not case_sensitive:
+            disabled_agents = [agent.lower() for agent in disabled_agents]
+
+        # Log exclusion configuration if agents are being excluded
+        if disabled_agents:
+            self.logger.info(f"Excluding agents from deployment: {disabled_agents}")
+            self.logger.debug(f"Case sensitive matching: {case_sensitive}")
+            self.logger.debug(f"Exclude dependencies: {exclude_dependencies}")
+
+        return config, disabled_agents
+
+    def get_deployment_settings(
+        self, config: Optional[Config] = None
+    ) -> Dict[str, Any]:
+        """
+        Get comprehensive deployment settings from configuration.
+
+        Args:
+            config: Optional configuration object
+
+        Returns:
+            Dictionary of deployment settings
+        """
+        if config is None:
+            config = Config()
+
+        return {
+            "enabled_agents": config.get("agent_deployment.enabled_agents", []),
+            "disabled_agents": config.get("agent_deployment.disabled_agents", [])
+            or config.get("agent_deployment.excluded_agents", []),
+            "deploy_system_agents": config.get(
+                "agent_deployment.deploy_system_agents", True
+            ),
+            "deploy_local_agents": config.get(
+                "agent_deployment.deploy_local_agents", True
+            ),
+            "deploy_user_agents": config.get(
+                "agent_deployment.deploy_user_agents", True
+            ),
+            "prefer_local_over_system": config.get(
+                "agent_deployment.prefer_local_over_system", True
+            ),
+            "version_comparison": config.get(
+                "agent_deployment.version_comparison", True
+            ),
+            "case_sensitive": config.get("agent_deployment.case_sensitive", False),
+            "exclude_dependencies": config.get(
+                "agent_deployment.exclude_dependencies", False
+            ),
+        }
+
+    def should_deploy_agent(
+        self, agent_id: str, agent_source: str, config: Optional[Config] = None
+    ) -> bool:
+        """
+        Check if an agent should be deployed based on configuration.
+
+        Args:
+            agent_id: The agent identifier
+            agent_source: The source of the agent ('system', 'local', 'user')
+            config: Optional configuration object
+
+        Returns:
+            True if the agent should be deployed, False otherwise
+        """
+        if config is None:
+            config = Config()
+
+        settings = self.get_deployment_settings(config)
+
+        # Check startup configuration for system agents
+        if agent_source == "system":
+            # Check startup configuration first
+            startup_enabled = config.get("startup.enabled_agents", [])
+            if startup_enabled:
+                # Normalize for comparison
+                check_id = agent_id if settings["case_sensitive"] else agent_id.lower()
+                startup_list = (
+                    startup_enabled
+                    if settings["case_sensitive"]
+                    else [a.lower() for a in startup_enabled]
+                )
+                if check_id not in startup_list:
+                    self.logger.debug(
+                        f"Skipping system agent {agent_id} - not in startup enabled list"
+                    )
+                    return False
+
+        # Check if the source type is enabled
+        if agent_source == "system" and not settings["deploy_system_agents"]:
+            self.logger.debug(
+                f"Skipping system agent {agent_id} - system agents disabled"
+            )
+            return False
+        if agent_source == "local" and not settings["deploy_local_agents"]:
+            self.logger.debug(
+                f"Skipping local agent {agent_id} - local agents disabled"
+            )
+            return False
+        if agent_source == "user" and not settings["deploy_user_agents"]:
+            self.logger.debug(f"Skipping user agent {agent_id} - user agents disabled")
+            return False
+
+        # Normalize agent_id for comparison if not case sensitive
+        check_id = agent_id if settings["case_sensitive"] else agent_id.lower()
+
+        # Check enabled list (if specified, only these agents are deployed)
+        enabled = settings["enabled_agents"]
+        if enabled:
+            enabled_list = (
+                enabled if settings["case_sensitive"] else [a.lower() for a in enabled]
+            )
+            if check_id not in enabled_list:
+                self.logger.debug(f"Skipping agent {agent_id} - not in enabled list")
+                return False
+
+        # Check disabled list
+        disabled = settings["disabled_agents"]
+        if disabled:
+            disabled_list = (
+                disabled
+                if settings["case_sensitive"]
+                else [a.lower() for a in disabled]
+            )
+            if check_id in disabled_list:
+                self.logger.debug(f"Skipping agent {agent_id} - in disabled list")
+                return False
+
+        return True

claude_mpm/services/agents/deployment/deployment_results_manager.py

@@ -0,0 +1,185 @@
+"""Deployment results manager for tracking deployment outcomes."""
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class DeploymentResultsManager:
+    """Service for managing deployment results and metrics.
+
+    This service handles initialization and updates of deployment
+    results dictionaries, ensuring consistent structure across
+    all deployment operations.
+    """
+
+    def __init__(self, logger: Optional[logging.Logger] = None):
+        """Initialize the deployment results manager.
+
+        Args:
+            logger: Optional logger instance
+        """
+        self.logger = logger or logging.getLogger(__name__)
+
+        # Initialize deployment metrics tracking
+        self._deployment_metrics = {
+            "total_deployments": 0,
+            "successful_deployments": 0,
+            "failed_deployments": 0,
+            "migrations_performed": 0,
+            "version_migration_count": 0,
+            "agent_type_counts": {},
+            "deployment_errors": {},
+        }
+
+    def initialize_deployment_results(
+        self, agents_dir: Path, deployment_start_time: float
+    ) -> Dict[str, Any]:
+        """Initialize the deployment results dictionary.
+
+        WHY: Consistent result structure ensures all deployment
+        operations return the same format for easier processing.
+
+        Args:
+            agents_dir: Target agents directory
+            deployment_start_time: Start time for metrics
+
+        Returns:
+            Initialized results dictionary
+        """
+        return {
+            "target_dir": str(agents_dir),
+            "deployed": [],
+            "errors": [],
+            "skipped": [],
+            "updated": [],
+            "migrated": [],  # Track agents migrated from old format
+            "converted": [],  # Track YAML to MD conversions
+            "repaired": [],  # Track agents with repaired frontmatter
+            "total": 0,
+            # METRICS: Add detailed timing and performance data to results
+            "metrics": {
+                "start_time": deployment_start_time,
+                "end_time": None,
+                "duration_ms": None,
+                "agent_timings": {},  # Track individual agent deployment times
+                "validation_times": {},  # Track template validation times
+                "resource_usage": {},  # Could track memory/CPU if needed
+            },
+        }
+
+    def record_agent_deployment(
+        self,
+        agent_name: str,
+        template_file: Path,
+        target_file: Path,
+        is_update: bool,
+        is_migration: bool,
+        reason: str,
+        agent_start_time: float,
+        results: Dict[str, Any],
+        logger: Optional[logging.Logger] = None,
+    ) -> None:
+        """Record deployment metrics and update results.
+
+        WHY: Centralized metrics recording ensures consistent tracking
+        of deployment performance and statistics.
+
+        Args:
+            agent_name: Name of the agent
+            template_file: Template file
+            target_file: Target file
+            is_update: Whether this is an update
+            is_migration: Whether this is a migration
+            reason: Update/migration reason
+            agent_start_time: Start time for this agent
+            results: Results dictionary to update
+            logger: Optional logger for output
+        """
+        logger = logger or self.logger
+
+        # METRICS: Record deployment time for this agent
+        agent_deployment_time = (time.time() - agent_start_time) * 1000  # Convert to ms
+        results["metrics"]["agent_timings"][agent_name] = agent_deployment_time
+
+        # METRICS: Update agent type deployment counts
+        self._deployment_metrics["agent_type_counts"][agent_name] = (
+            self._deployment_metrics["agent_type_counts"].get(agent_name, 0) + 1
+        )
+
+        deployment_info = {
+            "name": agent_name,
+            "template": str(template_file),
+            "target": str(target_file),
+            "deployment_time_ms": agent_deployment_time,
+        }
+
+        if is_migration:
+            deployment_info["reason"] = reason
+            results["migrated"].append(deployment_info)
+            logger.info(
+                f"Successfully migrated agent: {agent_name} to semantic versioning"
+            )
+
+            # METRICS: Track migration statistics
+            self._deployment_metrics["migrations_performed"] += 1
+            self._deployment_metrics["version_migration_count"] += 1
+
+        elif is_update:
+            results["updated"].append(deployment_info)
+            logger.debug(f"Updated agent: {agent_name}")
+        else:
+            results["deployed"].append(deployment_info)
+            logger.debug(f"Built and deployed agent: {agent_name}")
+
+    def finalize_results(
+        self, results: Dict[str, Any], deployment_start_time: float
+    ) -> None:
+        """Finalize deployment results with end metrics.
+
+        Args:
+            results: Results dictionary to finalize
+            deployment_start_time: Original start time
+        """
+        deployment_end_time = time.time()
+        deployment_duration = (deployment_end_time - deployment_start_time) * 1000  # ms
+
+        results["metrics"]["end_time"] = deployment_end_time
+        results["metrics"]["duration_ms"] = deployment_duration
+
+    def update_deployment_metrics(
+        self, success: bool, error_type: Optional[str] = None
+    ) -> None:
+        """Update internal deployment metrics.
+
+        Args:
+            success: Whether deployment succeeded
+            error_type: Type of error if failed
+        """
+        self._deployment_metrics["total_deployments"] += 1
+
+        if success:
+            self._deployment_metrics["successful_deployments"] += 1
+        else:
+            self._deployment_metrics["failed_deployments"] += 1
+            if error_type:
+                self._deployment_metrics["deployment_errors"][error_type] = (
+                    self._deployment_metrics["deployment_errors"].get(error_type, 0) + 1
+                )
+
+    def get_deployment_metrics(self) -> Dict[str, Any]:
+        """Get current deployment metrics."""
+        return self._deployment_metrics.copy()
+
+    def reset_metrics(self) -> None:
+        """Reset deployment metrics."""
+        self._deployment_metrics = {
+            "total_deployments": 0,
+            "successful_deployments": 0,
+            "failed_deployments": 0,
+            "migrations_performed": 0,
+            "version_migration_count": 0,
+            "agent_type_counts": {},
+            "deployment_errors": {},
+        }

claude_mpm/services/agents/deployment/deployment_type_detector.py

@@ -0,0 +1,120 @@
+"""Deployment type detection for agent deployment service.
+
+This module provides utilities to detect the type of agent deployment
+(system, project-specific, or user custom) based on template directory paths.
+Extracted from AgentDeploymentService to reduce complexity.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.config.paths import paths
+
+
+class DeploymentTypeDetector:
+    """Detects the type of agent deployment based on template directory."""
+
+    @staticmethod
+    def is_system_agent_deployment(templates_dir: Optional[Path]) -> bool:
+        """
+        Check if this is a deployment of system agents.
+
+        System agents are those provided by the claude-mpm package itself,
+        located in the package's agents/templates directory.
+
+        Args:
+            templates_dir: Directory containing agent templates
+
+        Returns:
+            True if deploying system agents, False otherwise
+        """
+        # Check if templates_dir points to the system templates
+        if templates_dir and templates_dir.exists():
+            # System agents are in the package's agents/templates directory
+            try:
+                # Check if templates_dir is within the claude_mpm package structure
+                templates_str = str(templates_dir.resolve())
+                return (
+                    "site-packages/claude_mpm" in templates_str
+                    or "src/claude_mpm/agents/templates" in templates_str
+                    or (paths.agents_dir / "templates").resolve()
+                    == templates_dir.resolve()
+                )
+            except Exception:
+                pass
+        return False
+
+    @staticmethod
+    def is_project_specific_deployment(
+        templates_dir: Optional[Path], working_directory: Path
+    ) -> bool:
+        """
+        Check if deploying project-specific agents.
+
+        Project-specific agents are those found in the project's
+        .claude-mpm/agents/ directory.
+
+        Args:
+            templates_dir: Directory containing agent templates
+            working_directory: Current working directory
+
+        Returns:
+            True if deploying project-specific agents, False otherwise
+        """
+        # Check if we're in a project directory with .claude-mpm/agents
+        project_agents_dir = working_directory / ".claude-mpm" / "agents"
+        if project_agents_dir.exists() and templates_dir and templates_dir.exists():
+            try:
+                return project_agents_dir.resolve() == templates_dir.resolve()
+            except Exception:
+                pass
+        return False
+
+    @staticmethod
+    def is_user_custom_deployment(templates_dir: Optional[Path]) -> bool:
+        """
+        Check if deploying user custom agents.
+
+        User custom agents are those in ~/.claude-mpm/agents/
+
+        Args:
+            templates_dir: Directory containing agent templates
+
+        Returns:
+            True if deploying user custom agents, False otherwise
+        """
+        user_agents_dir = Path.home() / ".claude-mpm" / "agents"
+        if user_agents_dir.exists() and templates_dir and templates_dir.exists():
+            try:
+                return user_agents_dir.resolve() == templates_dir.resolve()
+            except Exception:
+                pass
+        return False
+
+    @staticmethod
+    def determine_source_tier(templates_dir: Optional[Path]) -> str:
+        """
+        Determine the source tier for logging.
+
+        Understanding which tier (SYSTEM/USER/PROJECT) agents
+        are being deployed from helps with debugging and auditing.
+
+        Args:
+            templates_dir: Directory containing agent templates
+
+        Returns:
+            Source tier string: "SYSTEM", "USER", or "PROJECT"
+        """
+        if templates_dir:
+            templates_str = str(templates_dir)
+            if (
+                ".claude-mpm/agents" in templates_str
+                and "/templates" not in templates_str
+            ):
+                return "PROJECT"
+            if (
+                "/.claude-mpm/agents" in templates_str
+                and "/templates" not in templates_str
+            ):
+                return "USER"
+        return "SYSTEM"

claude_mpm/services/agents/deployment/deployment_wrapper.py

@@ -0,0 +1,129 @@
+"""Temporary wrapper to provide backward compatibility for CLI commands."""
+
+import contextlib
+from pathlib import Path
+from typing import Any, Dict
+
+from claude_mpm.services.agents.deployment import AgentDeploymentService
+
+
+class DeploymentServiceWrapper:
+    """Wrapper to provide backward-compatible methods for the CLI."""
+
+    def __init__(self, deployment_service: AgentDeploymentService):
+        """Initialize wrapper with actual deployment service."""
+        self.service = deployment_service
+        # Pass through all attributes
+        for attr in dir(deployment_service):
+            if not attr.startswith("_") and not hasattr(self, attr):
+                setattr(self, attr, getattr(deployment_service, attr))
+
+    def deploy_system_agents(self, force: bool = False) -> Dict[str, Any]:
+        """Deploy system agents only.
+
+        Args:
+            force: Force rebuild even if agents are up to date
+
+        Returns:
+            Deployment results
+        """
+        # Deploy agents with default target (system agents location)
+        result = self.service.deploy_agents(
+            force_rebuild=force, deployment_mode="update"
+        )
+
+        # Transform result to expected format
+        return {
+            "deployed_count": len(result.get("deployed", []))
+            + len(result.get("updated", [])),
+            "deployed": result.get("deployed", []),
+            "updated": result.get("updated", []),
+            "errors": result.get("errors", []),
+            "target_dir": result.get("target_dir", ""),
+        }
+
+    def deploy_project_agents(self, force: bool = False) -> Dict[str, Any]:
+        """Deploy project agents only.
+
+        Args:
+            force: Force rebuild even if agents are up to date
+
+        Returns:
+            Deployment results
+        """
+        # Check if project agents directory exists
+        project_dir = Path.cwd() / ".claude-mpm" / "agents"
+        if not project_dir.exists():
+            return {
+                "deployed_count": 0,
+                "deployed": [],
+                "updated": [],
+                "errors": [],
+                "target_dir": "",
+            }
+
+        # For now, return empty result as project agents are handled differently
+        return {
+            "deployed_count": 0,
+            "deployed": [],
+            "updated": [],
+            "errors": [],
+            "target_dir": str(project_dir),
+        }
+
+    def get_agent_details(self, agent_name: str) -> Dict[str, Any]:
+        """Get detailed information for a specific agent.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Agent details dictionary or empty dict if not found
+        """
+        try:
+            # Try to get from list of available agents
+            available_agents = self.service.list_available_agents()
+            for agent in available_agents:
+                if agent.get("name") == agent_name:
+                    # Get template path for the agent
+                    templates_dir = self.service.templates_dir
+                    agent_path = templates_dir / f"{agent_name}.md"
+
+                    # Read agent content if file exists
+                    if agent_path.exists():
+                        with agent_path.open() as f:
+                            content = f.read()
+
+                        # Parse metadata from content
+                        import yaml
+
+                        metadata = {}
+                        if content.startswith("---"):
+                            # Extract frontmatter
+                            parts = content.split("---", 2)
+                            if len(parts) >= 2:
+                                with contextlib.suppress(yaml.YAMLError):
+                                    metadata = yaml.safe_load(parts[1])
+
+                        return {
+                            "name": agent_name,
+                            "path": str(agent_path),
+                            "type": agent.get("type", "agent"),
+                            "version": metadata.get("version", "1.0.0"),
+                            "description": metadata.get("description", ""),
+                            "specializations": metadata.get("specializations", []),
+                            "metadata": metadata,
+                            "content": content,
+                            "exists": True,
+                        }
+
+            # Agent not found in available agents
+            return {
+                "name": agent_name,
+                "exists": False,
+                "error": f"Agent '{agent_name}' not found",
+            }
+
+        except Exception as e:
+            # Return error information
+            return {"name": agent_name, "exists": False, "error": str(e)}

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

@@ -0,0 +1,18 @@
+"""Deployment facade for handling async/sync deployment modes.
+
+This module provides a clean facade pattern for handling different
+deployment execution modes (async vs sync) without cluttering the
+main deployment logic with conditional complexity.
+"""
+
+from .async_deployment_executor import AsyncDeploymentExecutor
+from .deployment_executor import DeploymentExecutor
+from .deployment_facade import DeploymentFacade
+from .sync_deployment_executor import SyncDeploymentExecutor
+
+__all__ = [
+    "AsyncDeploymentExecutor",
+    "DeploymentExecutor",
+    "DeploymentFacade",
+    "SyncDeploymentExecutor",
+]