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

claude_mpm/services/agents/deployment/single_agent_deployer.py

@@ -0,0 +1,315 @@
+"""Single agent deployer for deploying individual agents."""
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from claude_mpm.core.exceptions import AgentDeploymentError
+
+
+class SingleAgentDeployer:
+    """Service for deploying individual agents.
+
+    This service handles the deployment of single agent templates,
+    including version checking, building, and writing agent files.
+    """
+
+    def __init__(
+        self,
+        template_builder,
+        version_manager,
+        results_manager,
+        logger: Optional[logging.Logger] = None,
+    ):
+        """Initialize the single agent deployer.
+
+        Args:
+            template_builder: Template builder service
+            version_manager: Version manager service
+            results_manager: Results manager service
+            logger: Optional logger instance
+        """
+        self.template_builder = template_builder
+        self.version_manager = version_manager
+        self.results_manager = results_manager
+        self.logger = logger or logging.getLogger(__name__)
+
+    def deploy_single_agent(
+        self,
+        template_file: Path,
+        agents_dir: Path,
+        base_agent_data: dict,
+        base_agent_version: tuple,
+        force_rebuild: bool,
+        deployment_mode: str,
+        results: Dict[str, Any],
+        source_info: str = "unknown",
+    ) -> None:
+        """Deploy a single agent template.
+
+        WHY: Extracting single agent deployment logic reduces complexity
+        and makes the main deployment loop more readable.
+
+        Args:
+            template_file: Agent template file
+            agents_dir: Target agents directory
+            base_agent_data: Base agent data
+            base_agent_version: Base agent version
+            force_rebuild: Whether to force rebuild
+            deployment_mode: Deployment mode (update/project)
+            results: Results dictionary to update
+            source_info: Source of the agent (system/project/user)
+        """
+        try:
+            # METRICS: Track individual agent deployment time
+            agent_start_time = time.time()
+
+            agent_name = template_file.stem
+            target_file = agents_dir / f"{agent_name}.md"
+
+            # Check if agent needs update
+            needs_update, is_migration, reason = self._check_update_status(
+                target_file,
+                template_file,
+                base_agent_version,
+                force_rebuild,
+                deployment_mode,
+            )
+
+            # Skip if exists and doesn't need update (only in update mode)
+            if (
+                target_file.exists()
+                and not needs_update
+                and deployment_mode != "project"
+            ):
+                results["skipped"].append(agent_name)
+                self.logger.debug(f"Skipped up-to-date agent: {agent_name}")
+                return
+
+            # Build the agent file as markdown with YAML frontmatter
+            agent_content = self.template_builder.build_agent_markdown(
+                agent_name, template_file, base_agent_data, source_info
+            )
+
+            # Write the agent file
+            is_update = target_file.exists()
+            target_file.write_text(agent_content)
+
+            # Record metrics and update results
+            self.results_manager.record_agent_deployment(
+                agent_name,
+                template_file,
+                target_file,
+                is_update,
+                is_migration,
+                reason,
+                agent_start_time,
+                results,
+                self.logger,
+            )
+
+        except AgentDeploymentError as e:
+            # Re-raise our custom exceptions
+            self.logger.error(str(e))
+            results["errors"].append(str(e))
+        except Exception as e:
+            # Wrap generic exceptions with context
+            error_msg = f"Failed to build {template_file.name}: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+
+    def _check_update_status(
+        self,
+        target_file: Path,
+        template_file: Path,
+        base_agent_version: tuple,
+        force_rebuild: bool,
+        deployment_mode: str,
+    ) -> Tuple[bool, bool, str]:
+        """Check if agent needs update and determine status.
+
+        WHY: Centralized update checking logic ensures consistent
+        version comparison and migration detection.
+
+        Args:
+            target_file: Target agent file
+            template_file: Template file
+            base_agent_version: Base agent version
+            force_rebuild: Whether to force rebuild
+            deployment_mode: Deployment mode
+
+        Returns:
+            Tuple of (needs_update, is_migration, reason)
+        """
+        needs_update = force_rebuild
+        is_migration = False
+        reason = ""
+
+        # In project deployment mode, always deploy regardless of version
+        if deployment_mode == "project":
+            if target_file.exists():
+                needs_update = True
+                self.logger.debug(
+                    f"Project deployment mode: will deploy {template_file.stem}"
+                )
+            else:
+                needs_update = True
+        elif not needs_update and target_file.exists():
+            # In update mode, check version compatibility
+            needs_update, reason = self.version_manager.check_agent_needs_update(
+                target_file, template_file, base_agent_version
+            )
+            if needs_update:
+                # Check if this is a migration from old format
+                if "migration needed" in reason:
+                    is_migration = True
+                    self.logger.info(f"Migrating agent {template_file.stem}: {reason}")
+                else:
+                    self.logger.info(
+                        f"Agent {template_file.stem} needs update: {reason}"
+                    )
+
+        return needs_update, is_migration, reason
+
+    def deploy_agent(
+        self,
+        agent_name: str,
+        templates_dir: Path,
+        target_dir: Path,
+        base_agent_path: Path,
+        force_rebuild: bool = False,
+        working_directory: Optional[Path] = None,
+    ) -> bool:
+        """Deploy a single agent to the specified directory.
+
+        Args:
+            agent_name: Name of the agent to deploy
+            templates_dir: Directory containing templates
+            target_dir: Target directory for deployment (Path object)
+            base_agent_path: Path to base agent configuration
+            force_rebuild: Whether to force rebuild even if version is current
+            working_directory: Working directory for determining agent source
+
+        Returns:
+            True if deployment was successful, False otherwise
+
+        WHY: Single agent deployment because:
+        - Users may want to deploy specific agents only
+        - Reduces deployment time for targeted updates
+        - Enables selective agent management in projects
+        """
+        try:
+            # Find the template file (templates migrated to .md in v4.26.0+)
+            template_file = templates_dir / f"{agent_name}.md"
+            if not template_file.exists():
+                self.logger.error(f"Agent template not found: {agent_name}")
+                return False
+
+            # Ensure target directory exists
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            # Build and deploy the agent
+            target_file = target_dir / f"{agent_name}.md"
+
+            # Check if update is needed
+            if not force_rebuild and target_file.exists():
+                # Load base agent data for version checking
+                base_agent_data = {}
+                base_agent_version = (0, 0, 0)
+                if base_agent_path.exists():
+                    try:
+                        import json
+
+                        base_agent_data = json.loads(base_agent_path.read_text())
+                        base_agent_version = self.version_manager.parse_version(
+                            base_agent_data.get("base_version")
+                            or base_agent_data.get("version", 0)
+                        )
+                    except Exception as e:
+                        self.logger.warning(
+                            f"Could not load base agent for version check: {e}"
+                        )
+
+                needs_update, reason = self.version_manager.check_agent_needs_update(
+                    target_file, template_file, base_agent_version
+                )
+                if not needs_update:
+                    self.logger.info(f"Agent {agent_name} is up to date")
+                    return True
+                self.logger.info(f"Updating agent {agent_name}: {reason}")
+
+            # Load base agent data for building
+            base_agent_data = {}
+            if base_agent_path.exists():
+                try:
+                    import json
+
+                    base_agent_data = json.loads(base_agent_path.read_text())
+                except Exception as e:
+                    self.logger.warning(f"Could not load base agent: {e}")
+
+            # Build the agent markdown
+            # For single agent deployment, determine source from template location
+            source_info = self._determine_agent_source(
+                template_file, working_directory or Path.cwd()
+            )
+            agent_content = self.template_builder.build_agent_markdown(
+                agent_name, template_file, base_agent_data, source_info
+            )
+            if not agent_content:
+                self.logger.error(f"Failed to build agent content for {agent_name}")
+                return False
+
+            # Write to target file
+            target_file.write_text(agent_content)
+            self.logger.info(
+                f"Successfully deployed agent: {agent_name} to {target_file}"
+            )
+
+            return True
+
+        except AgentDeploymentError:
+            # Re-raise our custom exceptions
+            raise
+        except Exception as e:
+            # Wrap generic exceptions with context
+            raise AgentDeploymentError(
+                f"Failed to deploy agent {agent_name}",
+                context={"agent_name": agent_name, "error": str(e)},
+            ) from e
+
+    def _determine_agent_source(
+        self, template_path: Path, working_directory: Path
+    ) -> str:
+        """Determine the source of an agent from its template path.
+
+        WHY: When deploying single agents, we need to track their source
+        for proper version management and debugging.
+
+        Args:
+            template_path: Path to the agent template
+            working_directory: Current working directory
+
+        Returns:
+            Source string (system/project/user/unknown)
+        """
+        template_str = str(template_path.resolve())
+
+        # Check if it's a system template
+        if (
+            "/claude_mpm/agents/templates/" in template_str
+            or "/src/claude_mpm/agents/templates/" in template_str
+        ):
+            return "system"
+
+        # Check if it's a project agent
+        if "/.claude-mpm/agents/" in template_str:
+            # Check if it's in the current working directory
+            if str(working_directory) in template_str:
+                return "project"
+            # Check if it's in user home
+            if str(Path.home()) in template_str:
+                return "user"
+
+        return "unknown"

claude_mpm/services/agents/deployment/startup_reconciliation.py

@@ -0,0 +1,138 @@
+"""
+Startup Reconciliation Hook
+
+This module provides a hook for performing agent/skill reconciliation
+during application startup, ensuring deployed state matches configuration.
+
+Usage:
+    from claude_mpm.services.agents.deployment.startup_reconciliation import (
+        perform_startup_reconciliation
+    )
+
+    # In your startup code
+    perform_startup_reconciliation()
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_utils import get_logger
+from claude_mpm.core.unified_config import UnifiedConfig
+
+from .deployment_reconciler import DeploymentReconciler, DeploymentResult
+
+logger = get_logger(__name__)
+
+
+def perform_startup_reconciliation(
+    project_path: Optional[Path] = None,
+    config: Optional[UnifiedConfig] = None,
+    silent: bool = False,
+) -> tuple[DeploymentResult, DeploymentResult]:
+    """
+    Perform agent and skill reconciliation during startup.
+
+    This ensures the deployed state (.claude/agents, .claude/skills) matches
+    the configuration (agents.enabled, skills.enabled lists).
+
+    Args:
+        project_path: Project directory (default: current directory)
+        config: Configuration instance (auto-loads if None)
+        silent: Suppress info logging (only errors)
+
+    Returns:
+        Tuple of (agent_result, skill_result)
+    """
+    project_path = project_path or Path.cwd()
+
+    # Load config if not provided
+    if config is None:
+        config = UnifiedConfig()
+
+    # Initialize reconciler
+    reconciler = DeploymentReconciler(config)
+
+    if not silent:
+        logger.info("Performing startup reconciliation...")
+
+    # Reconcile agents
+    agent_result = reconciler.reconcile_agents(project_path)
+
+    if agent_result.deployed and not silent:
+        logger.info(f"Deployed agents: {', '.join(agent_result.deployed)}")
+    if agent_result.removed and not silent:
+        logger.info(f"Removed agents: {', '.join(agent_result.removed)}")
+    if agent_result.errors:
+        for error in agent_result.errors:
+            logger.error(f"Agent reconciliation error: {error}")
+
+    # Reconcile skills
+    skill_result = reconciler.reconcile_skills(project_path)
+
+    if skill_result.deployed and not silent:
+        logger.info(f"Deployed skills: {', '.join(skill_result.deployed)}")
+    if skill_result.removed and not silent:
+        logger.info(f"Removed skills: {', '.join(skill_result.removed)}")
+    if skill_result.errors:
+        for error in skill_result.errors:
+            logger.error(f"Skill reconciliation error: {error}")
+
+    if not silent:
+        total_errors = len(agent_result.errors) + len(skill_result.errors)
+        if total_errors == 0:
+            logger.info("Startup reconciliation complete")
+        else:
+            logger.warning(
+                f"Startup reconciliation complete with {total_errors} errors"
+            )
+
+    return agent_result, skill_result
+
+
+def check_reconciliation_needed(
+    project_path: Optional[Path] = None, config: Optional[UnifiedConfig] = None
+) -> bool:
+    """
+    Check if reconciliation is needed (without performing it).
+
+    Args:
+        project_path: Project directory
+        config: Configuration instance
+
+    Returns:
+        True if reconciliation would make changes
+    """
+    project_path = project_path or Path.cwd()
+
+    if config is None:
+        config = UnifiedConfig()
+
+    reconciler = DeploymentReconciler(config)
+    view = reconciler.get_reconciliation_view(project_path)
+
+    agent_state = view["agents"]
+    skill_state = view["skills"]
+
+    # Check if any changes needed
+    return (
+        len(agent_state.to_deploy) > 0
+        or len(agent_state.to_remove) > 0
+        or len(skill_state.to_deploy) > 0
+        or len(skill_state.to_remove) > 0
+    )
+
+
+# Example integration in startup code:
+#
+# from claude_mpm.services.agents.deployment.startup_reconciliation import (
+#     perform_startup_reconciliation,
+#     check_reconciliation_needed
+# )
+#
+# def startup():
+#     # Check if reconciliation needed
+#     if check_reconciliation_needed():
+#         logger.info("Reconciliation needed, performing...")
+#         perform_startup_reconciliation()
+#     else:
+#         logger.debug("No reconciliation needed")

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

@@ -0,0 +1,25 @@
+"""Deployment strategy pattern for agent deployment.
+
+This module provides different deployment strategies for various scenarios:
+- SystemAgentDeploymentStrategy: For system-wide agent deployment
+- ProjectAgentDeploymentStrategy: For project-specific agent deployment
+- UserAgentDeploymentStrategy: For user-specific agent deployment
+
+The strategy pattern allows for clean separation of deployment logic
+and makes it easy to add new deployment types in the future.
+"""
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+from .project_strategy import ProjectAgentDeploymentStrategy
+from .strategy_selector import DeploymentStrategySelector
+from .system_strategy import SystemAgentDeploymentStrategy
+from .user_strategy import UserAgentDeploymentStrategy
+
+__all__ = [
+    "BaseDeploymentStrategy",
+    "DeploymentContext",
+    "DeploymentStrategySelector",
+    "ProjectAgentDeploymentStrategy",
+    "SystemAgentDeploymentStrategy",
+    "UserAgentDeploymentStrategy",
+]

claude_mpm/services/agents/deployment/strategies/base_strategy.py

@@ -0,0 +1,113 @@
+"""Base deployment strategy interface and context."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from claude_mpm.core.config import Config
+
+
+@dataclass
+class DeploymentContext:
+    """Context object containing all deployment parameters."""
+
+    target_dir: Optional[Path] = None
+    force_rebuild: bool = False
+    deployment_mode: str = "update"
+    config: Optional[Config] = None
+    use_async: bool = False
+    working_directory: Optional[Path] = None
+    templates_dir: Optional[Path] = None
+    base_agent_path: Optional[Path] = None
+
+
+class BaseDeploymentStrategy(ABC):
+    """Base class for all deployment strategies.
+
+    This abstract base class defines the interface that all deployment
+    strategies must implement. Each strategy handles a specific type
+    of deployment (system, project, user) with its own logic.
+    """
+
+    def __init__(self, name: str):
+        """Initialize the deployment strategy.
+
+        Args:
+            name: Human-readable name for this strategy
+        """
+        self.name = name
+
+    @abstractmethod
+    def can_handle(self, context: DeploymentContext) -> bool:
+        """Check if this strategy can handle the given deployment context.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            True if this strategy should handle the deployment
+        """
+
+    @abstractmethod
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine the target directory for deployment.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            Path where agents should be deployed
+        """
+
+    @abstractmethod
+    def get_templates_directory(self, context: DeploymentContext) -> Path:
+        """Get the templates directory for this deployment type.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            Path to the templates directory
+        """
+
+    @abstractmethod
+    def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
+        """Get list of agents to exclude for this deployment type.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            List of agent names to exclude from deployment
+        """
+
+    @abstractmethod
+    def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
+        """Check if system instructions should be deployed.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            True if system instructions should be deployed
+        """
+
+    @abstractmethod
+    def get_deployment_priority(self) -> int:
+        """Get the priority of this deployment strategy.
+
+        Lower numbers have higher priority. Used when multiple
+        strategies can handle the same context.
+
+        Returns:
+            Priority number (lower = higher priority)
+        """
+
+    def __str__(self) -> str:
+        """String representation of the strategy."""
+        return f"{self.__class__.__name__}({self.name})"
+
+    def __repr__(self) -> str:
+        """Detailed string representation of the strategy."""
+        return f"{self.__class__.__name__}(name='{self.name}', priority={self.get_deployment_priority()})"