claude-mpm 4.1.1__py3-none-any.whl → 4.1.3__py3-none-any.whl

claude_mpm/services/agents/deployment/async_agent_deployment.py

@@ -29,7 +29,6 @@ from typing import Any, Dict, List, Optional, Tuple
 import aiofiles
 
 from claude_mpm.config.paths import paths
-from claude_mpm.constants import EnvironmentVars, Paths
 from claude_mpm.core.config import Config
 from claude_mpm.core.logger import get_logger
 
@@ -95,12 +94,12 @@ class AsyncAgentDeploymentService:
             "parallel_files_processed": 0,
             "time_saved_ms": 0.0,
         }
-        
+
         self.logger.info(f"Base agent path: {self.base_agent_path}")
-    
+
     def _find_base_agent_file(self) -> Path:
         """Find base agent file with priority-based search.
-        
+
         Priority order:
         1. Environment variable override (CLAUDE_MPM_BASE_AGENT_PATH)
         2. Current working directory (for local development)
@@ -113,49 +112,68 @@ class AsyncAgentDeploymentService:
         if env_path:
             env_base_agent = Path(env_path)
             if env_base_agent.exists():
-                self.logger.info(f"Using environment variable base_agent: {env_base_agent}")
+                self.logger.info(
+                    f"Using environment variable base_agent: {env_base_agent}"
+                )
                 return env_base_agent
-            else:
-                self.logger.warning(f"CLAUDE_MPM_BASE_AGENT_PATH set but file doesn't exist: {env_base_agent}")
-        
+            self.logger.warning(
+                f"CLAUDE_MPM_BASE_AGENT_PATH set but file doesn't exist: {env_base_agent}"
+            )
+
         # Priority 1: Check current working directory for local development
         cwd = Path.cwd()
         cwd_base_agent = cwd / "src" / "claude_mpm" / "agents" / "base_agent.json"
         if cwd_base_agent.exists():
-            self.logger.info(f"Using local development base_agent from cwd: {cwd_base_agent}")
+            self.logger.info(
+                f"Using local development base_agent from cwd: {cwd_base_agent}"
+            )
             return cwd_base_agent
-        
+
         # Priority 2: Check known development locations
         known_dev_paths = [
-            Path("/Users/masa/Projects/claude-mpm/src/claude_mpm/agents/base_agent.json"),
-            Path.home() / "Projects" / "claude-mpm" / "src" / "claude_mpm" / "agents" / "base_agent.json",
-            Path.home() / "projects" / "claude-mpm" / "src" / "claude_mpm" / "agents" / "base_agent.json",
+            Path(
+                "/Users/masa/Projects/claude-mpm/src/claude_mpm/agents/base_agent.json"
+            ),
+            Path.home()
+            / "Projects"
+            / "claude-mpm"
+            / "src"
+            / "claude_mpm"
+            / "agents"
+            / "base_agent.json",
+            Path.home()
+            / "projects"
+            / "claude-mpm"
+            / "src"
+            / "claude_mpm"
+            / "agents"
+            / "base_agent.json",
         ]
-        
+
         for dev_path in known_dev_paths:
             if dev_path.exists():
                 self.logger.info(f"Using development base_agent: {dev_path}")
                 return dev_path
-        
+
         # Priority 3: Check user override location
         user_base_agent = Path.home() / ".claude" / "agents" / "base_agent.json"
         if user_base_agent.exists():
             self.logger.info(f"Using user override base_agent: {user_base_agent}")
             return user_base_agent
-        
+
         # Priority 4: Use framework agents directory (fallback)
         framework_base_agent = paths.agents_dir / "base_agent.json"
         if framework_base_agent.exists():
             self.logger.info(f"Using framework base_agent: {framework_base_agent}")
             return framework_base_agent
-        
+
         # If still not found, log all searched locations
         self.logger.warning("Base agent file not found in any location:")
         self.logger.warning(f"  1. CWD: {cwd_base_agent}")
         self.logger.warning(f"  2. Dev paths: {known_dev_paths}")
         self.logger.warning(f"  3. User: {user_base_agent}")
         self.logger.warning(f"  4. Framework: {framework_base_agent}")
-        
+
         # Final fallback to framework path even if it doesn't exist
         return framework_base_agent
 
@@ -233,7 +251,7 @@ class AsyncAgentDeploymentService:
             """Load and parse a single agent file asynchronously."""
             try:
                 # Non-blocking file read
-                async with aiofiles.open(file_path, "r") as f:
+                async with aiofiles.open(file_path) as f:
                     content = await f.read()
 
                 # Parse JSON in thread pool (CPU-bound)
@@ -291,13 +309,12 @@ class AsyncAgentDeploymentService:
                 required_fields = ["agent_id", "instructions"]
                 if all(field in agent for field in required_fields):
                     return agent
-                else:
-                    missing = [f for f in required_fields if f not in agent]
-                    self.logger.warning(
-                        f"Agent {agent.get('_agent_name', 'unknown')} "
-                        f"missing required fields: {missing}"
-                    )
-                    return None
+                missing = [f for f in required_fields if f not in agent]
+                self.logger.warning(
+                    f"Agent {agent.get('_agent_name', 'unknown')} "
+                    f"missing required fields: {missing}"
+                )
+                return None
             except Exception as e:
                 self.logger.error(f"Validation error: {e}")
                 return None
@@ -415,10 +432,9 @@ class AsyncAgentDeploymentService:
 
         if target_dir.name == "agents":
             return target_dir
-        elif target_dir.name in [".claude-mpm", ".claude"]:
+        if target_dir.name in [".claude-mpm", ".claude"]:
             return target_dir / "agents"
-        else:
-            return target_dir / ".claude" / "agents"
+        return target_dir / ".claude" / "agents"
 
     def _filter_excluded_agents(
         self,
@@ -494,7 +510,6 @@ class AsyncAgentDeploymentService:
 
     def _build_agent_markdown_sync(self, agent_data: Dict[str, Any]) -> str:
         """Build agent markdown content matching the synchronous deployment format."""
-        from datetime import datetime
 
         # Extract agent info from the loaded JSON data
         agent_name = agent_data.get("_agent_name", "unknown")
@@ -521,7 +536,7 @@ class AsyncAgentDeploymentService:
         )
 
         # Get tags from new format (metadata.tags) or old format
-        tags = (
+        (
             agent_data.get("metadata", {}).get("tags")
             or agent_data.get("configuration_fields", {}).get("tags")
             or agent_data.get("tags")
@@ -583,7 +598,7 @@ class AsyncAgentDeploymentService:
             f"description: {description}",
             f"version: {version_string}",
             f"base_version: {self._format_version_display(base_version)}",
-            f"author: claude-mpm",  # Identify as system agent for deployment
+            "author: claude-mpm",  # Identify as system agent for deployment
             f"tools: {tools_str}",
             f"model: {model}",
         ]
@@ -667,9 +682,8 @@ class AsyncAgentDeploymentService:
         if isinstance(version_tuple, tuple) and len(version_tuple) == 3:
             major, minor, patch = version_tuple
             return f"{major}.{minor}.{patch}"
-        else:
-            # Fallback for legacy format
-            return str(version_tuple)
+        # Fallback for legacy format
+        return str(version_tuple)
 
     async def cleanup(self):
         """Clean up resources."""
@@ -706,10 +720,9 @@ def deploy_agents_async_wrapper(
         )
 
         try:
-            results = await service.deploy_agents_async(
+            return await service.deploy_agents_async(
                 target_dir=target_dir, force_rebuild=force_rebuild, config=config
             )
-            return results
         finally:
             await service.cleanup()
 
@@ -717,7 +730,7 @@ def deploy_agents_async_wrapper(
     try:
         # Check if we're already in an async context
         try:
-            loop = asyncio.get_running_loop()
+            asyncio.get_running_loop()
             # We're in an async context, run in thread pool to avoid blocking
             import concurrent.futures
 

claude_mpm/services/agents/deployment/base_agent_locator.py

@@ -0,0 +1,132 @@
+"""Base agent locator service for finding base agent configuration files."""
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+
+class BaseAgentLocator:
+    """Service for locating base agent configuration files.
+
+    This service handles the priority-based search for base_agent.json
+    files across multiple possible locations including environment
+    variables, development paths, and user overrides.
+    """
+
+    def __init__(self, logger: Optional[logging.Logger] = None):
+        """Initialize the base agent locator.
+
+        Args:
+            logger: Optional logger instance
+        """
+        self.logger = logger or logging.getLogger(__name__)
+
+    def find_base_agent_file(self, paths_agents_dir: Path) -> Path:
+        """Find base agent file with priority-based search.
+
+        Priority order:
+        1. Environment variable override (CLAUDE_MPM_BASE_AGENT_PATH)
+        2. Current working directory (for local development)
+        3. Known development locations
+        4. User override location (~/.claude/agents/)
+        5. Framework agents directory (from paths)
+
+        Args:
+            paths_agents_dir: Framework agents directory from paths
+
+        Returns:
+            Path to base agent file
+        """
+        # Priority 0: Check environment variable override
+        env_path = os.environ.get("CLAUDE_MPM_BASE_AGENT_PATH")
+        if env_path:
+            env_base_agent = Path(env_path)
+            if env_base_agent.exists():
+                self.logger.info(
+                    f"Using environment variable base_agent: {env_base_agent}"
+                )
+                return env_base_agent
+            self.logger.warning(
+                f"CLAUDE_MPM_BASE_AGENT_PATH set but file doesn't exist: {env_base_agent}"
+            )
+
+        # Priority 1: Check current working directory for local development
+        cwd = Path.cwd()
+        cwd_base_agent = cwd / "src" / "claude_mpm" / "agents" / "base_agent.json"
+        if cwd_base_agent.exists():
+            self.logger.info(
+                f"Using local development base_agent from cwd: {cwd_base_agent}"
+            )
+            return cwd_base_agent
+
+        # Priority 2: Check known development locations
+        known_dev_paths = [
+            Path(
+                "/Users/masa/Projects/claude-mpm/src/claude_mpm/agents/base_agent.json"
+            ),
+            Path.home()
+            / "Projects"
+            / "claude-mpm"
+            / "src"
+            / "claude_mpm"
+            / "agents"
+            / "base_agent.json",
+            Path.home()
+            / "projects"
+            / "claude-mpm"
+            / "src"
+            / "claude_mpm"
+            / "agents"
+            / "base_agent.json",
+        ]
+
+        for dev_path in known_dev_paths:
+            if dev_path.exists():
+                self.logger.info(f"Using development base_agent: {dev_path}")
+                return dev_path
+
+        # Priority 3: Check user override location
+        user_base_agent = Path.home() / ".claude" / "agents" / "base_agent.json"
+        if user_base_agent.exists():
+            self.logger.info(f"Using user override base_agent: {user_base_agent}")
+            return user_base_agent
+
+        # Priority 4: Use framework agents directory (fallback)
+        framework_base_agent = paths_agents_dir / "base_agent.json"
+        if framework_base_agent.exists():
+            self.logger.info(f"Using framework base_agent: {framework_base_agent}")
+            return framework_base_agent
+
+        # If still not found, log all searched locations and raise error
+        self.logger.error("Base agent file not found in any location:")
+        self.logger.error(f"  1. CWD: {cwd_base_agent}")
+        self.logger.error(f"  2. Dev paths: {known_dev_paths}")
+        self.logger.error(f"  3. User: {user_base_agent}")
+        self.logger.error(f"  4. Framework: {framework_base_agent}")
+
+        # Final fallback to framework path even if it doesn't exist
+        # (will fail later with better error message)
+        return framework_base_agent
+
+    def determine_source_tier(self, templates_dir: Path) -> str:
+        """Determine the source tier for logging.
+
+        Args:
+            templates_dir: Templates directory path
+
+        Returns:
+            Source tier string (framework/user/project)
+        """
+        templates_str = str(templates_dir.resolve())
+
+        # Check if this is a user-level installation
+        if str(Path.home()) in templates_str and ".claude-mpm" in templates_str:
+            return "user"
+
+        # Check if this is a project-level installation
+        if ".claude-mpm" in templates_str:
+            return "project"
+
+        # Default to framework
+        return "framework"

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

@@ -8,6 +8,6 @@ from .deployment_config import DeploymentConfig
 from .deployment_config_manager import DeploymentConfigManager
 
 __all__ = [
-    "DeploymentConfigManager",
     "DeploymentConfig",
+    "DeploymentConfigManager",
 ]

claude_mpm/services/agents/deployment/config/deployment_config.py

@@ -87,8 +87,7 @@ class DeploymentConfig:
         """
         if self.case_sensitive_exclusion:
             return agent_name in self.excluded_agents
-        else:
-            return agent_name.lower() in [name.lower() for name in self.excluded_agents]
+        return agent_name.lower() in [name.lower() for name in self.excluded_agents]
 
     def get_effective_excluded_agents(self) -> List[str]:
         """Get the effective list of excluded agents.
@@ -159,12 +158,12 @@ class DeploymentConfig:
             "use_async": self.use_async,
             "target_dir": str(self.target_dir) if self.target_dir else None,
             "templates_dir": str(self.templates_dir) if self.templates_dir else None,
-            "base_agent_path": str(self.base_agent_path)
-            if self.base_agent_path
-            else None,
-            "working_directory": str(self.working_directory)
-            if self.working_directory
-            else None,
+            "base_agent_path": (
+                str(self.base_agent_path) if self.base_agent_path else None
+            ),
+            "working_directory": (
+                str(self.working_directory) if self.working_directory else None
+            ),
             "deploy_system_instructions": self.deploy_system_instructions,
             "deploy_user_instructions": self.deploy_user_instructions,
             "repair_existing_agents": self.repair_existing_agents,

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

@@ -116,7 +116,7 @@ class DeploymentTypeDetector:
                 and "/templates" not in templates_str
             ):
                 return "PROJECT"
-            elif (
+            if (
                 "/.claude-mpm/agents" in templates_str
                 and "/templates" not in templates_str
             ):

claude_mpm/services/agents/deployment/deployment_wrapper.py

@@ -1,52 +1,52 @@
 """Temporary wrapper to provide backward compatibility for CLI commands."""
 
 from pathlib import Path
-from typing import Dict, Any
+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):
+            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"
+            force_rebuild=force, deployment_mode="update"
         )
-        
+
         # Transform result to expected format
         return {
-            "deployed_count": len(result.get("deployed", [])) + len(result.get("updated", [])),
+            "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", "")
+            "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
         """
@@ -58,14 +58,14 @@ class DeploymentServiceWrapper:
                 "deployed": [],
                 "updated": [],
                 "errors": [],
-                "target_dir": ""
+                "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)
-        }
+            "target_dir": str(project_dir),
+        }

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

@@ -11,8 +11,8 @@ from .deployment_facade import DeploymentFacade
 from .sync_deployment_executor import SyncDeploymentExecutor
 
 __all__ = [
+    "AsyncDeploymentExecutor",
     "DeploymentExecutor",
     "DeploymentFacade",
-    "AsyncDeploymentExecutor",
     "SyncDeploymentExecutor",
 ]