claude-mpm 4.1.1__py3-none-any.whl → 4.1.3__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
+            template_file = templates_dir / f"{agent_name}.json"
+            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/strategies/__init__.py

@@ -18,8 +18,8 @@ from .user_strategy import UserAgentDeploymentStrategy
 __all__ = [
     "BaseDeploymentStrategy",
     "DeploymentContext",
-    "SystemAgentDeploymentStrategy",
+    "DeploymentStrategySelector",
     "ProjectAgentDeploymentStrategy",
+    "SystemAgentDeploymentStrategy",
     "UserAgentDeploymentStrategy",
-    "DeploymentStrategySelector",
 ]

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

@@ -3,7 +3,7 @@
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import List, Optional
 
 from claude_mpm.core.config import Config
 
@@ -48,7 +48,6 @@ class BaseDeploymentStrategy(ABC):
         Returns:
             True if this strategy should handle the deployment
         """
-        pass
 
     @abstractmethod
     def determine_target_directory(self, context: DeploymentContext) -> Path:
@@ -60,7 +59,6 @@ class BaseDeploymentStrategy(ABC):
         Returns:
             Path where agents should be deployed
         """
-        pass
 
     @abstractmethod
     def get_templates_directory(self, context: DeploymentContext) -> Path:
@@ -72,7 +70,6 @@ class BaseDeploymentStrategy(ABC):
         Returns:
             Path to the templates directory
         """
-        pass
 
     @abstractmethod
     def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
@@ -84,7 +81,6 @@ class BaseDeploymentStrategy(ABC):
         Returns:
             List of agent names to exclude from deployment
         """
-        pass
 
     @abstractmethod
     def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
@@ -96,7 +92,6 @@ class BaseDeploymentStrategy(ABC):
         Returns:
             True if system instructions should be deployed
         """
-        pass
 
     @abstractmethod
     def get_deployment_priority(self) -> int:
@@ -108,7 +103,6 @@ class BaseDeploymentStrategy(ABC):
         Returns:
             Priority number (lower = higher priority)
         """
-        pass
 
     def __str__(self) -> str:
         """String representation of the strategy."""

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

@@ -58,10 +58,7 @@ class ProjectAgentDeploymentStrategy(BaseDeploymentStrategy):
                 pass
 
         # Check if deployment_mode is "project" - this should be sufficient
-        if context.deployment_mode == "project":
-            return True
-
-        return False
+        return context.deployment_mode == "project"
 
     def determine_target_directory(self, context: DeploymentContext) -> Path:
         """Determine target directory for project agents.

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

@@ -76,9 +76,8 @@ class SystemAgentDeploymentStrategy(BaseDeploymentStrategy):
         # Always deploy to project directory
         if context.working_directory:
             return context.working_directory / ".claude" / "agents"
-        else:
-            # Fallback to current working directory if not specified
-            return Path.cwd() / ".claude" / "agents"
+        # Fallback to current working directory if not specified
+        return Path.cwd() / ".claude" / "agents"
 
     def get_templates_directory(self, context: DeploymentContext) -> Path:
         """Get templates directory for system agents.

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

@@ -49,10 +49,7 @@ class UserAgentDeploymentStrategy(BaseDeploymentStrategy):
         # Check for user-specific environment variable
         import os
 
-        if "CLAUDE_MPM_USER_PWD" in os.environ:
-            return True
-
-        return False
+        return "CLAUDE_MPM_USER_PWD" in os.environ
 
     def determine_target_directory(self, context: DeploymentContext) -> Path:
         """Determine target directory for user agents.
@@ -70,9 +67,8 @@ class UserAgentDeploymentStrategy(BaseDeploymentStrategy):
         # Always deploy to project directory
         if context.working_directory:
             return context.working_directory / ".claude" / "agents"
-        else:
-            # Fallback to current working directory if not specified
-            return Path.cwd() / ".claude" / "agents"
+        # Fallback to current working directory if not specified
+        return Path.cwd() / ".claude" / "agents"
 
     def get_templates_directory(self, context: DeploymentContext) -> Path:
         """Get templates directory for user agents.

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

@@ -11,8 +11,8 @@ from .template_validator import TemplateValidator
 from .validation_result import ValidationResult, ValidationSeverity
 
 __all__ = [
-    "DeploymentValidator",
     "AgentValidator",
+    "DeploymentValidator",
     "TemplateValidator",
     "ValidationResult",
     "ValidationSeverity",

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

@@ -2,7 +2,7 @@
 
 import re
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 import yaml
 

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

@@ -2,11 +2,11 @@
 
 import json
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict
 
 from claude_mpm.core.logger import get_logger
 
-from .validation_result import ValidationResult, ValidationSeverity
+from .validation_result import ValidationResult
 
 
 class TemplateValidator:

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

@@ -175,12 +175,11 @@ class ValidationResult:
         Returns:
             New ValidationResult with merged issues
         """
-        merged = ValidationResult(
+        return ValidationResult(
             is_valid=self.is_valid and other.is_valid,
             issues=self.issues + other.issues,
             metadata={**self.metadata, **other.metadata},
         )
-        return merged
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert validation result to dictionary.
@@ -208,10 +207,7 @@ class ValidationResult:
 
     def __str__(self) -> str:
         """String representation of the validation result."""
-        if self.is_valid:
-            status = "VALID"
-        else:
-            status = "INVALID"
+        status = "VALID" if self.is_valid else "INVALID"
 
         summary = f"Validation {status}"
 

claude_mpm/services/agents/loading/__init__.py

@@ -5,7 +5,7 @@ from .base_agent_manager import BaseAgentManager
 from .framework_agent_loader import FrameworkAgentLoader
 
 __all__ = [
-    "FrameworkAgentLoader",
     "AgentProfileLoader",
     "BaseAgentManager",
+    "FrameworkAgentLoader",
 ]

claude_mpm/services/agents/loading/agent_profile_loader.py

@@ -20,7 +20,6 @@ multi-file implementation for better maintainability.
 """
 
 import asyncio
-import hashlib
 import json
 import logging
 import os
@@ -28,7 +27,7 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Set, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple
 
 import yaml
 
@@ -37,7 +36,6 @@ from claude_mpm.core.config import Config
 from claude_mpm.core.unified_paths import get_path_manager
 from claude_mpm.services.agents.registry import AgentRegistry
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
-from claude_mpm.utils.path_operations import path_ops
 
 logger = logging.getLogger(__name__)
 
@@ -146,7 +144,7 @@ class AgentProfileLoader(BaseService):
         # Performance tracking
         self.load_metrics: Dict[str, float] = {}
 
-        logger.info(f"AgentProfileLoader initialized successfully")
+        logger.info("AgentProfileLoader initialized successfully")
         logger.info(f"  Working directory: {self.working_directory}")
         logger.info(f"  Framework path: {self.framework_path}")
         logger.info(f"  Tier paths: {list(self.tier_paths.keys())}")
@@ -329,7 +327,7 @@ class AgentProfileLoader(BaseService):
                     instructions = data.get("instructions", "")
 
             # Create profile
-            profile = AgentProfile(
+            return AgentProfile(
                 name=data.get("name", file_path.stem),
                 role=data.get("role", "agent"),
                 description=data.get("description", ""),
@@ -342,8 +340,6 @@ class AgentProfileLoader(BaseService):
                 status=ProfileStatus.LOADED,
             )
 
-            return profile
-
         except Exception as e:
             logger.error(f"Error parsing profile {file_path}: {e}")
             return AgentProfile(
@@ -421,9 +417,7 @@ class AgentProfileLoader(BaseService):
                 for file_path in tier_path.glob(pattern):
                     agent_name = file_path.stem
                     # Remove common suffixes
-                    if agent_name.endswith("_agent"):
-                        agent_name = agent_name[:-6]
-                    elif agent_name.endswith("-agent"):
+                    if agent_name.endswith(("_agent", "-agent")):
                         agent_name = agent_name[:-6]
 
                     if agent_name not in agents:
@@ -448,7 +442,7 @@ class AgentProfileLoader(BaseService):
         for agents in discovered.values():
             all_agents.update(agents)
 
-        return sorted(list(all_agents))
+        return sorted(all_agents)
 
     # ========================================================================
     # Improved Prompts Management
@@ -461,7 +455,7 @@ class AgentProfileLoader(BaseService):
 
         if prompt_file.exists():
             try:
-                with open(prompt_file, "r") as f:
+                with open(prompt_file) as f:
                     data = json.load(f)
                     for prompt_data in data:
                         prompt = ImprovedPrompt(

claude_mpm/services/agents/loading/base_agent_manager.py

@@ -67,7 +67,9 @@ class BaseAgentStructure:
 class BaseAgentManager(ConfigServiceBase):
     """Manages base_agent.md with structured updates and validation."""
 
-    def __init__(self, agents_dir: Optional[Path] = None, config: Optional[Dict[str, Any]] = None):
+    def __init__(
+        self, agents_dir: Optional[Path] = None, config: Optional[Dict[str, Any]] = None
+    ):
         """Initialize BaseAgentManager."""
         super().__init__("base_agent_manager", config=config)
 
@@ -75,7 +77,7 @@ class BaseAgentManager(ConfigServiceBase):
         self.agents_dir = self.get_config_value(
             "agents_dir",
             default=agents_dir or Path(__file__).parent.parent / "agents",
-            config_type=Path
+            config_type=Path,
         )
         self.base_agent_path = self.agents_dir / "BASE_AGENT_TEMPLATE.md"
         self.cache = SharedPromptCache.get_instance()
@@ -347,9 +349,7 @@ class BaseAgentManager(ConfigServiceBase):
         items = []
         for line in content.split("\n"):
             line = line.strip()
-            if line.startswith("- "):
-                items.append(line[2:].strip())
-            elif line.startswith("* "):
+            if line.startswith(("- ", "* ")):
                 items.append(line[2:].strip())
             elif line.startswith("**") and line.endswith("**"):
                 # Skip bold headers

claude_mpm/services/agents/loading/framework_agent_loader.py

@@ -12,14 +12,12 @@ This service integrates with the main agent_loader.py to provide
 markdown-based agent profiles alongside JSON-based templates.
 """
 
-import json
 import logging
 from pathlib import Path
 from typing import Any, Dict, Optional
 
 from claude_mpm.agents.agent_loader import (
     AgentTier,
-    get_agent_tier,
     list_agents_by_tier,
 )
 from claude_mpm.core.unified_paths import get_path_manager
@@ -97,7 +95,7 @@ class FrameworkAgentLoader:
         current = Path.cwd()
 
         # Check current directory and parents
-        for path in [current] + list(current.parents):
+        for path in [current, *list(current.parents)]:
             framework_instructions = path / "agents" / "INSTRUCTIONS.md"
             framework_claude = path / "agents" / "CLAUDE.md"  # Legacy
             if framework_instructions.exists() or framework_claude.exists():
@@ -110,7 +108,7 @@ class FrameworkAgentLoader:
         current = Path.cwd()
 
         # Check current directory and parents for .claude-mpm
-        for path in [current] + list(current.parents):
+        for path in [current, *list(current.parents)]:
             claude_pm_dir = path / get_path_manager().CONFIG_DIR
             if claude_pm_dir.exists():
                 return path

claude_mpm/services/agents/management/__init__.py

@@ -4,6 +4,6 @@ from .agent_capabilities_generator import AgentCapabilitiesGenerator
 from .agent_management_service import AgentManager
 
 __all__ = [
-    "AgentManager",
     "AgentCapabilitiesGenerator",
+    "AgentManager",
 ]

claude_mpm/services/agents/management/agent_capabilities_generator.py

@@ -44,15 +44,13 @@ class AgentCapabilitiesGenerator:
             )
 
             # Render template
-            content = self.template.render(
+            return self.template.render(
                 core_agents=core_agent_list,
                 detailed_capabilities=detailed_capabilities,
                 agents_by_tier=agents_by_tier,
                 total_agents=len(deployed_agents),
             )
 
-            return content
-
         except Exception as e:
             logger.error(f"Failed to generate capabilities section: {e}")
             # Return fallback content on error