claude-mpm 4.0.32__py3-none-any.whl → 4.1.0__py3-none-any.whl

claude_mpm/services/agents/deployment/agents_directory_resolver.py

@@ -15,32 +15,25 @@ class AgentsDirectoryResolver:
     def __init__(
         self,
         working_directory: Path,
-        is_system_deployment: bool,
-        is_project_specific: bool,
     ):
         """
         Initialize the resolver.
 
         Args:
             working_directory: Current working directory
-            is_system_deployment: Whether this is a system agent deployment
-            is_project_specific: Whether this is a project-specific deployment
         """
         self.working_directory = working_directory
-        self.is_system_deployment = is_system_deployment
-        self.is_project_specific = is_project_specific
 
     def determine_agents_directory(self, target_dir: Optional[Path]) -> Path:
         """
         Determine the correct agents directory based on input.
-
-        Different deployment scenarios require different directory
-        structures. This method centralizes the logic for consistency.
-
-        HIERARCHY:
-        - System agents → Deploy to ~/.claude/agents/ (user's home directory)
-        - User custom agents from ~/.claude-mpm/agents/ → Deploy to ~/.claude/agents/
-        - Project-specific agents from <project>/.claude-mpm/agents/ → Deploy to <project>/.claude/agents/
+        
+        MODIFIED: Always deploy to project .claude/agents directory
+        regardless of agent source (system, user, or project).
+        
+        This ensures all agents are deployed at the project level while
+        maintaining discovery from both user (~/.claude-mpm) and project
+        (.claude-mpm) directories.
 
         Args:
             target_dir: Optional target directory
@@ -49,17 +42,9 @@ class AgentsDirectoryResolver:
             Path to agents directory
         """
         if not target_dir:
-            # Default deployment location depends on agent source
-            # Check if we're deploying system agents or user/project agents
-            if self.is_system_deployment:
-                # System agents go to user's home ~/.claude/agents/
-                return Path.home() / ".claude" / "agents"
-            elif self.is_project_specific:
-                # Project agents stay in project directory
-                return self.working_directory / ".claude" / "agents"
-            else:
-                # Default: User custom agents go to home ~/.claude/agents/
-                return Path.home() / ".claude" / "agents"
+            # Always deploy to project directory
+            # This is the key change - all agents go to project .claude/agents
+            return self.working_directory / ".claude" / "agents"
 
         # If target_dir provided, use it directly (caller decides structure)
         target_dir = Path(target_dir)

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -13,6 +13,7 @@ Key Features:
 
 import json
 import logging
+import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -190,8 +191,9 @@ class MultiSourceAgentDeploymentService:
         user_agents_dir: Optional[Path] = None,
         working_directory: Optional[Path] = None,
         excluded_agents: Optional[List[str]] = None,
-        config: Optional[Config] = None
-    ) -> Tuple[Dict[str, Path], Dict[str, str]]:
+        config: Optional[Config] = None,
+        cleanup_outdated: bool = True
+    ) -> Tuple[Dict[str, Path], Dict[str, str], Dict[str, Any]]:
         """Get the highest version agents from all sources for deployment.
         
         Args:
@@ -201,11 +203,13 @@ class MultiSourceAgentDeploymentService:
             working_directory: Current working directory for finding project agents
             excluded_agents: List of agent names to exclude from deployment
             config: Configuration object for additional filtering
+            cleanup_outdated: Whether to cleanup outdated user agents (default: True)
             
         Returns:
             Tuple of:
             - Dictionary mapping agent names to template file paths
             - Dictionary mapping agent names to their source
+            - Dictionary with cleanup results (removed, preserved, errors)
         """
         # Discover all available agents
         agents_by_name = self.discover_agents_from_all_sources(
@@ -218,6 +222,27 @@ class MultiSourceAgentDeploymentService:
         # Select highest version for each agent
         selected_agents = self.select_highest_version_agents(agents_by_name)
         
+        # Clean up outdated user agents if enabled
+        cleanup_results = {"removed": [], "preserved": [], "errors": []}
+        if cleanup_outdated:
+            # Check if cleanup is enabled in config or environment
+            cleanup_enabled = True
+            
+            # Check environment variable first (for CI/CD and testing)
+            env_cleanup = os.environ.get("CLAUDE_MPM_CLEANUP_USER_AGENTS", "").lower()
+            if env_cleanup in ["false", "0", "no", "disabled"]:
+                cleanup_enabled = False
+                self.logger.debug("User agent cleanup disabled via environment variable")
+            
+            # Check config if environment doesn't disable it
+            if cleanup_enabled and config:
+                cleanup_enabled = config.get("agent_deployment.cleanup_outdated_user_agents", True)
+            
+            if cleanup_enabled:
+                cleanup_results = self.cleanup_outdated_user_agents(
+                    agents_by_name, selected_agents
+                )
+        
         # Apply exclusion filters
         if excluded_agents:
             for agent_name in excluded_agents:
@@ -256,7 +281,168 @@ class MultiSourceAgentDeploymentService:
             f"user: {sum(1 for s in agent_sources.values() if s == 'user')})"
         )
         
-        return agents_to_deploy, agent_sources
+        return agents_to_deploy, agent_sources, cleanup_results
+    
+    def cleanup_outdated_user_agents(
+        self,
+        agents_by_name: Dict[str, List[Dict[str, Any]]],
+        selected_agents: Dict[str, Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Remove outdated user agents when project or system agents have higher versions.
+        
+        WHY: When project agents are updated to newer versions, outdated user agent
+        copies should be removed to prevent confusion and ensure the latest version
+        is always used. User agents with same or higher versions are preserved to
+        respect user customizations.
+        
+        Args:
+            agents_by_name: Dictionary mapping agent names to list of agent info from different sources
+            selected_agents: Dictionary mapping agent names to the selected highest version agent
+            
+        Returns:
+            Dictionary with cleanup results:
+            - removed: List of removed agent info
+            - preserved: List of preserved agent info with reasons
+            - errors: List of errors during cleanup
+        """
+        cleanup_results = {
+            "removed": [],
+            "preserved": [],
+            "errors": []
+        }
+        
+        # Get user agents directory
+        user_agents_dir = Path.home() / ".claude-mpm" / "agents"
+        
+        # Safety check - only operate on user agents directory
+        if not user_agents_dir.exists():
+            self.logger.debug("User agents directory does not exist, no cleanup needed")
+            return cleanup_results
+        
+        for agent_name, agent_versions in agents_by_name.items():
+            # Skip if only one version exists
+            if len(agent_versions) < 2:
+                continue
+                
+            selected = selected_agents.get(agent_name)
+            if not selected:
+                continue
+            
+            # Process each version of this agent
+            for agent_info in agent_versions:
+                # Only consider user agents for cleanup
+                if agent_info["source"] != "user":
+                    continue
+                
+                # Safety check - ensure path is within user agents directory
+                user_agent_path = Path(agent_info["path"])
+                try:
+                    # Resolve paths to compare them safely
+                    resolved_user_path = user_agent_path.resolve()
+                    resolved_user_agents_dir = user_agents_dir.resolve()
+                    
+                    # Verify the agent is actually in the user agents directory
+                    if not str(resolved_user_path).startswith(str(resolved_user_agents_dir)):
+                        self.logger.warning(
+                            f"Skipping cleanup for {agent_name}: path {user_agent_path} "
+                            f"is not within user agents directory"
+                        )
+                        cleanup_results["errors"].append({
+                            "agent": agent_name,
+                            "error": "Path outside user agents directory"
+                        })
+                        continue
+                except Exception as e:
+                    self.logger.error(f"Error resolving paths for {agent_name}: {e}")
+                    cleanup_results["errors"].append({
+                        "agent": agent_name,
+                        "error": f"Path resolution error: {e}"
+                    })
+                    continue
+                
+                # Compare versions
+                user_version = self.version_manager.parse_version(
+                    agent_info.get("version", "0.0.0")
+                )
+                selected_version = self.version_manager.parse_version(
+                    selected.get("version", "0.0.0")
+                )
+                
+                version_comparison = self.version_manager.compare_versions(
+                    user_version, selected_version
+                )
+                
+                # Determine action based on version comparison and selected source
+                if version_comparison < 0 and selected["source"] in ["project", "system"]:
+                    # User agent has lower version than selected project/system agent - remove it
+                    if user_agent_path.exists():
+                        try:
+                            # Log before removal for audit trail
+                            self.logger.info(
+                                f"Removing outdated user agent: {agent_name} "
+                                f"v{self.version_manager.format_version_display(user_version)} "
+                                f"(superseded by {selected['source']} "
+                                f"v{self.version_manager.format_version_display(selected_version)})"
+                            )
+                            
+                            # Remove the file
+                            user_agent_path.unlink()
+                            
+                            cleanup_results["removed"].append({
+                                "name": agent_name,
+                                "version": self.version_manager.format_version_display(user_version),
+                                "path": str(user_agent_path),
+                                "reason": f"Superseded by {selected['source']} v{self.version_manager.format_version_display(selected_version)}"
+                            })
+                        except PermissionError as e:
+                            error_msg = f"Permission denied removing {agent_name}: {e}"
+                            self.logger.error(error_msg)
+                            cleanup_results["errors"].append({
+                                "agent": agent_name,
+                                "error": error_msg
+                            })
+                        except Exception as e:
+                            error_msg = f"Error removing {agent_name}: {e}"
+                            self.logger.error(error_msg)
+                            cleanup_results["errors"].append({
+                                "agent": agent_name,
+                                "error": error_msg
+                            })
+                else:
+                    # Preserve the user agent
+                    if version_comparison >= 0:
+                        reason = "User version same or higher than selected version"
+                    elif selected["source"] == "user":
+                        reason = "User agent is the selected version"
+                    else:
+                        reason = "User customization preserved"
+                        
+                    cleanup_results["preserved"].append({
+                        "name": agent_name,
+                        "version": self.version_manager.format_version_display(user_version),
+                        "reason": reason
+                    })
+                    
+                    self.logger.debug(
+                        f"Preserving user agent {agent_name} "
+                        f"v{self.version_manager.format_version_display(user_version)}: {reason}"
+                    )
+        
+        # Log cleanup summary
+        if cleanup_results["removed"]:
+            self.logger.info(
+                f"Cleanup complete: removed {len(cleanup_results['removed'])} outdated user agents"
+            )
+        if cleanup_results["preserved"]:
+            self.logger.debug(
+                f"Preserved {len(cleanup_results['preserved'])} user agents"
+            )
+        if cleanup_results["errors"]:
+            self.logger.warning(
+                f"Encountered {len(cleanup_results['errors'])} errors during cleanup"
+            )
+        
+        return cleanup_results
     
     def _apply_config_filters(
         self, 
@@ -321,6 +507,7 @@ class MultiSourceAgentDeploymentService:
             "needs_update": [],
             "up_to_date": [],
             "new_agents": [],
+            "orphaned_agents": [],  # Agents without templates
             "version_upgrades": [],
             "version_downgrades": [],
             "source_changes": []
@@ -341,9 +528,11 @@ class MultiSourceAgentDeploymentService:
             # Read template version
             try:
                 template_data = json.loads(template_path.read_text())
+                metadata = template_data.get("metadata", {})
                 template_version = self.version_manager.parse_version(
                     template_data.get("agent_version") or 
-                    template_data.get("version", "0.0.0")
+                    template_data.get("version") or
+                    metadata.get("version", "0.0.0")
                 )
             except Exception as e:
                 self.logger.warning(f"Error reading template for '{agent_name}': {e}")
@@ -411,13 +600,20 @@ class MultiSourceAgentDeploymentService:
                     "source": agent_sources[agent_name]
                 })
         
+        # Check for orphaned agents (deployed but no template)
+        orphaned = self._detect_orphaned_agents_simple(deployed_agents_dir, agents_to_deploy)
+        comparison_results["orphaned_agents"] = orphaned
+        
         # Log summary
-        self.logger.info(
-            f"Version comparison complete: "
-            f"{len(comparison_results['needs_update'])} need updates, "
-            f"{len(comparison_results['up_to_date'])} up to date, "
+        summary_parts = [
+            f"{len(comparison_results['needs_update'])} need updates",
+            f"{len(comparison_results['up_to_date'])} up to date",
             f"{len(comparison_results['new_agents'])} new agents"
-        )
+        ]
+        if comparison_results["orphaned_agents"]:
+            summary_parts.append(f"{len(comparison_results['orphaned_agents'])} orphaned")
+        
+        self.logger.info(f"Version comparison complete: {', '.join(summary_parts)}")
         
         if comparison_results["version_upgrades"]:
             for upgrade in comparison_results["version_upgrades"]:
@@ -436,10 +632,24 @@ class MultiSourceAgentDeploymentService:
         
         if comparison_results["version_downgrades"]:
             for downgrade in comparison_results["version_downgrades"]:
-                self.logger.warning(
-                    f"  Warning: {downgrade['name']} deployed version "
+                # Changed from warning to debug - deployed versions higher than templates
+                # are not errors, just informational
+                self.logger.debug(
+                    f"  Note: {downgrade['name']} deployed version "
                     f"{downgrade['deployed_version']} is higher than template "
-                    f"{downgrade['template_version']}"
+                    f"{downgrade['template_version']} (keeping deployed version)"
+                )
+        
+        # Log orphaned agents if found
+        if comparison_results["orphaned_agents"]:
+            self.logger.info(
+                f"Found {len(comparison_results['orphaned_agents'])} orphaned agent(s) "
+                f"(deployed without templates):"
+            )
+            for orphan in comparison_results["orphaned_agents"]:
+                self.logger.info(
+                    f"  - {orphan['name']} v{orphan['version']} "
+                    f"(consider removing or creating a template)"
                 )
         
         return comparison_results
@@ -506,4 +716,177 @@ class MultiSourceAgentDeploymentService:
             return "system"
         
         # Complex names are more likely to be user/project agents
-        return "user"
+        return "user"
+    
+    def detect_orphaned_agents(
+        self, 
+        deployed_agents_dir: Path,
+        available_agents: Dict[str, Any]
+    ) -> List[Dict[str, Any]]:
+        """Detect deployed agents that don't have corresponding templates.
+        
+        WHY: Orphaned agents can cause confusion with version warnings.
+        This method identifies them so they can be handled appropriately.
+        
+        Args:
+            deployed_agents_dir: Directory containing deployed agents
+            available_agents: Dictionary of available agents from all sources
+            
+        Returns:
+            List of orphaned agent information
+        """
+        orphaned = []
+        
+        if not deployed_agents_dir.exists():
+            return orphaned
+        
+        # Build a mapping of file stems to agent names for comparison
+        # Since available_agents uses display names like "Code Analysis Agent"
+        # but deployed files use stems like "code_analyzer"
+        available_stems = set()
+        stem_to_name = {}
+        
+        for agent_name, agent_sources in available_agents.items():
+            # Get the file path from the first source to extract the stem
+            if agent_sources and isinstance(agent_sources, list) and len(agent_sources) > 0:
+                first_source = agent_sources[0]
+                if 'file_path' in first_source:
+                    file_path = Path(first_source['file_path'])
+                    stem = file_path.stem
+                    available_stems.add(stem)
+                    stem_to_name[stem] = agent_name
+        
+        for deployed_file in deployed_agents_dir.glob("*.md"):
+            agent_stem = deployed_file.stem
+            
+            # Skip if this agent has a template (check by stem, not display name)
+            if agent_stem in available_stems:
+                continue
+            
+            # This is an orphaned agent
+            try:
+                deployed_content = deployed_file.read_text()
+                deployed_version, _, _ = self.version_manager.extract_version_from_frontmatter(
+                    deployed_content
+                )
+                version_str = self.version_manager.format_version_display(deployed_version)
+            except Exception:
+                version_str = "unknown"
+            
+            orphaned.append({
+                "name": agent_stem,
+                "file": str(deployed_file),
+                "version": version_str
+            })
+        
+        return orphaned
+    
+    def _detect_orphaned_agents_simple(
+        self, 
+        deployed_agents_dir: Path,
+        agents_to_deploy: Dict[str, Path]
+    ) -> List[Dict[str, Any]]:
+        """Simple orphan detection that works with agents_to_deploy structure.
+        
+        Args:
+            deployed_agents_dir: Directory containing deployed agents
+            agents_to_deploy: Dictionary mapping file stems to template paths
+            
+        Returns:
+            List of orphaned agent information
+        """
+        orphaned = []
+        
+        if not deployed_agents_dir.exists():
+            return orphaned
+        
+        # agents_to_deploy already contains file stems as keys
+        available_stems = set(agents_to_deploy.keys())
+        
+        for deployed_file in deployed_agents_dir.glob("*.md"):
+            agent_stem = deployed_file.stem
+            
+            # Skip if this agent has a template (check by stem)
+            if agent_stem in available_stems:
+                continue
+            
+            # This is an orphaned agent
+            try:
+                deployed_content = deployed_file.read_text()
+                deployed_version, _, _ = self.version_manager.extract_version_from_frontmatter(
+                    deployed_content
+                )
+                version_str = self.version_manager.format_version_display(deployed_version)
+            except Exception:
+                version_str = "unknown"
+            
+            orphaned.append({
+                "name": agent_stem,
+                "file": str(deployed_file),
+                "version": version_str
+            })
+        
+        return orphaned
+    
+    def cleanup_orphaned_agents(
+        self,
+        deployed_agents_dir: Path,
+        dry_run: bool = True
+    ) -> Dict[str, Any]:
+        """Clean up orphaned agents that don't have templates.
+        
+        WHY: Orphaned agents can accumulate over time and cause confusion.
+        This method provides a way to clean them up systematically.
+        
+        Args:
+            deployed_agents_dir: Directory containing deployed agents
+            dry_run: If True, only report what would be removed
+            
+        Returns:
+            Dictionary with cleanup results
+        """
+        results = {
+            "orphaned": [],
+            "removed": [],
+            "errors": []
+        }
+        
+        # First, discover all available agents from all sources
+        all_agents = self.discover_agents_from_all_sources()
+        available_names = set(all_agents.keys())
+        
+        # Detect orphaned agents
+        orphaned = self.detect_orphaned_agents(deployed_agents_dir, all_agents)
+        results["orphaned"] = orphaned
+        
+        if not orphaned:
+            self.logger.info("No orphaned agents found")
+            return results
+        
+        self.logger.info(f"Found {len(orphaned)} orphaned agent(s)")
+        
+        for orphan in orphaned:
+            agent_file = Path(orphan["file"])
+            
+            if dry_run:
+                self.logger.info(
+                    f"  Would remove: {orphan['name']} v{orphan['version']}"
+                )
+            else:
+                try:
+                    agent_file.unlink()
+                    results["removed"].append(orphan["name"])
+                    self.logger.info(
+                        f"  Removed: {orphan['name']} v{orphan['version']}"
+                    )
+                except Exception as e:
+                    error_msg = f"Failed to remove {orphan['name']}: {e}"
+                    results["errors"].append(error_msg)
+                    self.logger.error(f"  {error_msg}")
+        
+        if dry_run and orphaned:
+            self.logger.info(
+                "Run with dry_run=False to actually remove orphaned agents"
+            )
+        
+        return results

claude_mpm/services/agents/deployment/pipeline/steps/target_directory_step.py

@@ -37,8 +37,9 @@ class TargetDirectorySetupStep(BaseDeploymentStep):
                 if context.target_dir:
                     context.actual_target_dir = context.target_dir
                 else:
-                    # Default to user's home .claude/agents directory
-                    context.actual_target_dir = Path.home() / ".claude" / "agents"
+                    # MODIFIED: Default to project .claude/agents directory
+                    # All agents now deploy to the project level
+                    context.actual_target_dir = Path.cwd() / ".claude" / "agents"
 
             # Create target directory if it doesn't exist
             context.actual_target_dir.mkdir(parents=True, exist_ok=True)

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

@@ -63,15 +63,22 @@ class SystemAgentDeploymentStrategy(BaseDeploymentStrategy):
     def determine_target_directory(self, context: DeploymentContext) -> Path:
         """Determine target directory for system agents.
 
-        System agents are always deployed to ~/.claude/agents/
+        MODIFIED: System agents are now deployed to project .claude/agents/
+        to maintain consistency with the new deployment behavior.
+        All agents (system, user, project) deploy to the project level.
 
         Args:
             context: Deployment context
 
         Returns:
-            Path to ~/.claude/agents/
+            Path to <project>/.claude/agents/
         """
-        return Path.home() / ".claude" / "agents"
+        # 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"
 
     def get_templates_directory(self, context: DeploymentContext) -> Path:
         """Get templates directory for system agents.

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

@@ -57,26 +57,22 @@ class UserAgentDeploymentStrategy(BaseDeploymentStrategy):
     def determine_target_directory(self, context: DeploymentContext) -> Path:
         """Determine target directory for user agents.
 
-        User agents can be deployed to various user-specific locations.
+        MODIFIED: User agents are now deployed to project .claude/agents/
+        to maintain consistency with the new deployment behavior.
+        All agents (system, user, project) deploy to the project level.
 
         Args:
             context: Deployment context
 
         Returns:
-            Path to user agents directory
+            Path to <project>/.claude/agents/
         """
-        if context.target_dir:
-            return context.target_dir
-
-        # Check for user-specific environment variable
-        import os
-
-        if "CLAUDE_MPM_USER_PWD" in os.environ:
-            user_pwd = Path(os.environ["CLAUDE_MPM_USER_PWD"])
-            return user_pwd / ".claude" / "agents"
-
-        # Default to user's home directory
-        return Path.home() / ".claude-mpm" / "agents"
+        # 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"
 
     def get_templates_directory(self, context: DeploymentContext) -> Path:
         """Get templates directory for user agents.