claude-mpm 5.0.9__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/services/agents/agent_review_service.py

@@ -0,0 +1,280 @@
+"""Agent review service for comparing project agents with managed agents.
+
+WHY: This service helps users maintain a clean agent directory by:
+1. Identifying which agents are managed vs custom
+2. Detecting outdated versions of managed agents
+3. Finding unused agents that don't match the detected toolchain
+4. Safely archiving unnecessary agents instead of deleting them
+
+DESIGN DECISIONS:
+- Archive to .claude/agents/unused/ instead of deleting (safe, recoverable)
+- Add timestamps to archived files to prevent conflicts
+- Preserve custom user agents (not in managed set)
+- Compare versions to detect outdated managed agents
+"""
+
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Set
+
+from claude_mpm.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class AgentReviewService:
+    """Service for reviewing and managing project agents.
+
+    This service analyzes the relationship between project agents and managed
+    agents from the claude-mpm-agents repository, categorizing them as:
+    - Managed: In sync with managed agents
+    - Outdated: Older version of managed agent exists
+    - Custom: User-created agents not in managed set
+    - Unused: Not recommended for this project's toolchain
+    """
+
+    def __init__(self):
+        """Initialize the agent review service."""
+        self.logger = get_logger(__name__)
+
+    def review_project_agents(
+        self,
+        project_agents_dir: Path,
+        managed_agents: List[Dict[str, Any]],
+        recommended_agent_ids: Set[str],
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """Review existing project agents and categorize them.
+
+        Args:
+            project_agents_dir: Directory containing project agents (.claude/agents/)
+            managed_agents: List of managed agent dicts from cache
+            recommended_agent_ids: Set of agent IDs recommended for this toolchain
+
+        Returns:
+            Dictionary with categorized agents:
+            {
+                "managed": [...],      # In sync with managed
+                "outdated": [...],     # Older version exists
+                "custom": [...],       # User-created
+                "unused": [...],       # Not needed for this toolchain
+            }
+        """
+        results = {
+            "managed": [],
+            "outdated": [],
+            "custom": [],
+            "unused": [],
+        }
+
+        if not project_agents_dir.exists():
+            self.logger.debug(
+                f"Project agents directory does not exist: {project_agents_dir}"
+            )
+            return results
+
+        # Build lookup map of managed agents by ID
+        managed_by_id = {agent["agent_id"]: agent for agent in managed_agents}
+
+        # Scan project agents
+        for agent_file in project_agents_dir.glob("*.md"):
+            # Skip the unused directory itself
+            if agent_file.name == "unused":
+                continue
+
+            agent_name = agent_file.stem
+
+            # Parse agent to get version and metadata
+            project_agent_info = self._parse_project_agent(agent_file)
+
+            # Check if this is a managed agent
+            if agent_name in managed_by_id:
+                managed_agent = managed_by_id[agent_name]
+
+                # Compare versions
+                project_version = project_agent_info.get("version", "unknown")
+                managed_version = managed_agent.get("version", "unknown")
+
+                if self._is_outdated(project_version, managed_version):
+                    # Outdated version of managed agent
+                    results["outdated"].append(
+                        {
+                            "name": agent_name,
+                            "path": agent_file,
+                            "current_version": project_version,
+                            "available_version": managed_version,
+                            "recommended": agent_name in recommended_agent_ids,
+                        }
+                    )
+                else:
+                    # Up-to-date managed agent
+                    results["managed"].append(
+                        {
+                            "name": agent_name,
+                            "path": agent_file,
+                            "version": project_version,
+                            "recommended": agent_name in recommended_agent_ids,
+                        }
+                    )
+            else:
+                # Custom user agent (not in managed set)
+                results["custom"].append(
+                    {
+                        "name": agent_name,
+                        "path": agent_file,
+                        "version": project_agent_info.get("version", "unknown"),
+                    }
+                )
+
+        # Identify unused agents (managed or outdated but not recommended)
+        for category in ["managed", "outdated"]:
+            for agent in results[category][:]:  # Copy list to modify during iteration
+                if not agent.get("recommended", False):
+                    # This managed/outdated agent is not recommended for this toolchain
+                    results["unused"].append(agent)
+                    results[category].remove(agent)
+
+        self.logger.info(
+            f"Agent review complete: "
+            f"{len(results['managed'])} managed, "
+            f"{len(results['outdated'])} outdated, "
+            f"{len(results['custom'])} custom, "
+            f"{len(results['unused'])} unused"
+        )
+
+        return results
+
+    def archive_agents(
+        self, agents_to_archive: List[Dict[str, Any]], project_agents_dir: Path
+    ) -> Dict[str, Any]:
+        """Archive agents by moving them to .claude/agents/unused/.
+
+        Args:
+            agents_to_archive: List of agent dicts with 'name' and 'path' keys
+            project_agents_dir: Base agents directory (.claude/agents/)
+
+        Returns:
+            Dictionary with archival results:
+            {
+                "archived": [...],  # Successfully archived
+                "errors": [...],    # Archival errors
+            }
+        """
+        results = {"archived": [], "errors": []}
+
+        if not agents_to_archive:
+            return results
+
+        # Create unused directory
+        unused_dir = project_agents_dir / "unused"
+        unused_dir.mkdir(exist_ok=True)
+
+        for agent in agents_to_archive:
+            agent_path = agent["path"]
+            agent_name = agent["name"]
+
+            try:
+                # Generate timestamped filename to avoid conflicts
+                timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+                archived_name = f"{agent_name}_{timestamp}.md"
+                archived_path = unused_dir / archived_name
+
+                # Move the file
+                shutil.move(str(agent_path), str(archived_path))
+
+                results["archived"].append(
+                    {
+                        "name": agent_name,
+                        "original_path": str(agent_path),
+                        "archived_path": str(archived_path),
+                    }
+                )
+
+                self.logger.debug(f"Archived {agent_name} to {archived_path}")
+
+            except Exception as e:
+                error_msg = f"Failed to archive {agent_name}: {e}"
+                self.logger.error(error_msg)
+                results["errors"].append(error_msg)
+
+        self.logger.info(
+            f"Archived {len(results['archived'])} agents, "
+            f"{len(results['errors'])} errors"
+        )
+
+        return results
+
+    def _parse_project_agent(self, agent_file: Path) -> Dict[str, Any]:
+        """Parse a project agent file to extract metadata.
+
+        Args:
+            agent_file: Path to agent Markdown file
+
+        Returns:
+            Dictionary with agent metadata (version, name, etc.)
+        """
+        try:
+            content = agent_file.read_text(encoding="utf-8")
+
+            # Extract version from YAML frontmatter
+            import re
+
+            version_match = re.search(
+                r'^version:\s*["\']?(.+?)["\']?$', content, re.MULTILINE
+            )
+            version = version_match.group(1) if version_match else "unknown"
+
+            return {
+                "version": version,
+                "name": agent_file.stem,
+            }
+
+        except Exception as e:
+            self.logger.warning(f"Failed to parse agent {agent_file.name}: {e}")
+            return {"version": "unknown", "name": agent_file.stem}
+
+    def _is_outdated(self, current_version: str, available_version: str) -> bool:
+        """Check if current version is outdated compared to available version.
+
+        Args:
+            current_version: Currently deployed version
+            available_version: Available version from managed agents
+
+        Returns:
+            True if current version is outdated
+        """
+        # Handle unknown versions
+        if current_version == "unknown" or available_version == "unknown":
+            return False
+
+        # Simple string comparison for now
+        # TODO: Implement semantic version comparison (1.2.3 vs 1.2.4)
+        return current_version != available_version
+
+    def get_archive_summary(self, project_agents_dir: Path) -> Dict[str, Any]:
+        """Get summary of archived agents.
+
+        Args:
+            project_agents_dir: Base agents directory (.claude/agents/)
+
+        Returns:
+            Dictionary with archive statistics
+        """
+        unused_dir = project_agents_dir / "unused"
+
+        if not unused_dir.exists():
+            return {"count": 0, "agents": []}
+
+        archived_files = list(unused_dir.glob("*.md"))
+
+        return {
+            "count": len(archived_files),
+            "agents": [
+                {
+                    "name": f.stem,
+                    "path": str(f),
+                    "size_bytes": f.stat().st_size,
+                }
+                for f in archived_files
+            ],
+        }

claude_mpm/services/agents/cache_git_manager.py

@@ -29,7 +29,7 @@ Error Handling:
 
 Example:
     >>> from pathlib import Path
-    >>> manager = CacheGitManager(Path.home() / ".claude-mpm/cache/remote-agents")
+    >>> manager = CacheGitManager(Path.home() / ".claude-mpm/cache/agents")
     >>> if manager.is_git_repo():
     ...     status = manager.get_status()
     ...     print(f"Branch: {status['branch']}, Uncommitted: {len(status['uncommitted'])}")
@@ -76,7 +76,7 @@ class CacheGitManager:
             timeout: Git command timeout in seconds (default: 30)
 
         Example:
-            >>> cache_dir = Path.home() / ".claude-mpm/cache/remote-agents"
+            >>> cache_dir = Path.home() / ".claude-mpm/cache/agents"
             >>> manager = CacheGitManager(cache_dir)
         """
         self.cache_path = Path(cache_path)
@@ -105,12 +105,12 @@ class CacheGitManager:
 
         Example:
             >>> # Case 1: cache_path inside repo (searches upward)
-            >>> # cache_path: ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents
-            >>> # Found at: ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents
+            >>> # cache_path: ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents
+            >>> # Found at: ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents
 
             >>> # Case 2: repo nested in cache_path (searches downward)
-            >>> # cache_path: ~/.claude-mpm/cache/remote-agents
-            >>> # Found at: ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents
+            >>> # cache_path: ~/.claude-mpm/cache/agents
+            >>> # Found at: ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents
         """
         # Strategy 1: Search upward (cache_path is inside repo)
         current = self.cache_path

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -876,13 +876,13 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             user_agents_dir = potential_user_dir
             self.logger.info(f"Found user agents at: {user_agents_dir}")
 
-        # Check for remote agents (cached from GitHub)
-        remote_agents_dir = None
+        # Check for agents cache (from Git sources)
+        agents_cache_dir = None
         cache_dir = user_home / ".claude-mpm" / "cache"
-        potential_remote_dir = cache_dir / "remote-agents"
-        if potential_remote_dir.exists():
-            remote_agents_dir = potential_remote_dir
-            self.logger.info(f"Found remote agents cache at: {remote_agents_dir}")
+        potential_cache_dir = cache_dir / "agents"
+        if potential_cache_dir.exists():
+            agents_cache_dir = potential_cache_dir
+            self.logger.info(f"Found agents cache at: {agents_cache_dir}")
 
         # Get agents with version comparison and cleanup (4-tier discovery)
         agents_to_deploy, agent_sources, cleanup_results = (
@@ -890,7 +890,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                 system_templates_dir=system_templates_dir,
                 project_agents_dir=project_agents_dir,
                 user_agents_dir=user_agents_dir,
-                remote_agents_dir=remote_agents_dir,  # NEW: 4th tier
+                agents_cache_dir=agents_cache_dir,  # NEW: 4th tier
                 working_directory=self.working_directory,
                 excluded_agents=excluded_agents,
                 config=config,
@@ -898,6 +898,9 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             )
         )
 
+        # Keep track of all enabled agents before filtering (for cleanup)
+        all_enabled_agents = agents_to_deploy.copy()
+
         # Compare with deployed versions if agents directory exists
         if agents_dir.exists():
             comparison_results = self.multi_source_service.compare_deployed_versions(
@@ -954,6 +957,25 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                         f"All {len(comparison_results.get('up_to_date', []))} agents are up to date"
                     )
 
+        # Cleanup excluded agents (remove agents not in deployment list)
+        # CRITICAL: Use all_enabled_agents (before filtering for updates) to preserve up-to-date agents
+        # Bug fix (1M-XXX): Previously used filtered agents_to_deploy which could be empty,
+        # causing all agents to be removed when everything was up-to-date
+        exclusion_cleanup_results = self.multi_source_service.cleanup_excluded_agents(
+            deployed_agents_dir=agents_dir,
+            agents_to_deploy=all_enabled_agents,
+        )
+
+        # Add exclusion cleanup results to main cleanup results
+        if exclusion_cleanup_results.get("removed"):
+            cleanup_results.setdefault("excluded_removed", []).extend(
+                exclusion_cleanup_results["removed"]
+            )
+            self.logger.info(
+                f"Removed {len(exclusion_cleanup_results['removed'])} excluded agents: "
+                f"{', '.join(exclusion_cleanup_results['removed'])}"
+            )
+
         # Convert to list of Path objects
         template_files = list(agents_to_deploy.values())
 

claude_mpm/services/agents/deployment/agent_discovery_service.py

@@ -215,9 +215,8 @@ class AgentDiscoveryService:
             # Extract YAML frontmatter
             frontmatter = self._extract_yaml_frontmatter(template_content)
             if not frontmatter:
-                self.logger.warning(
-                    f"No valid YAML frontmatter in {template_file.name}"
-                )
+                # Silently return None for files without frontmatter
+                # (e.g., PM instruction templates in templates/ directory)
                 return None
 
             # Extract metadata directly from frontmatter (flat structure)
@@ -249,7 +248,7 @@ class AgentDiscoveryService:
             return agent_info
 
         except yaml.YAMLError as e:
-            self.logger.error(f"Invalid YAML frontmatter in {template_file.name}: {e}")
+            self.logger.warning(f"Invalid YAML frontmatter in {template_file.name}: {e}")
             return None
         except Exception as e:
             self.logger.error(
@@ -432,7 +431,7 @@ class AgentDiscoveryService:
             return True
 
         except yaml.YAMLError:
-            self.logger.error(
+            self.logger.warning(
                 f"Invalid YAML frontmatter in template: {template_file.name}"
             )
             return False

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -129,13 +129,14 @@ class AgentTemplateBuilder:
                 base_templates.append(base_agent_file)
                 self.logger.debug(f"Found BASE-AGENT.md at: {base_agent_file}")
 
-            # Stop at git repository root if detected
+            # Stop at git repository root if detected (check AFTER finding BASE-AGENT.md)
             if (current_dir / ".git").exists():
                 self.logger.debug(f"Reached git repository root at: {current_dir}")
                 break
 
-            # Stop at common repository root indicators
-            if current_dir.name in [".claude-mpm", "remote-agents", "cache"]:
+            # Stop at common repository root indicators (check AFTER finding BASE-AGENT.md)
+            # Stop at cache root or .claude-mpm directory
+            if current_dir.name in [".claude-mpm", "cache"]:
                 self.logger.debug(
                     f"Reached repository root indicator at: {current_dir}"
                 )
@@ -675,6 +676,7 @@ Only include memories that are:
 """
             content = content + memory_instructions
 
+        # Combine frontmatter and content
         return frontmatter + content
 
     def build_agent_yaml(

claude_mpm/services/agents/deployment/agents_directory_resolver.py

@@ -8,7 +8,7 @@ DEPLOYMENT ARCHITECTURE:
 
 Agent Source Locations (Discovery):
 -----------------------------------
-1. System Agents:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/
+1. System Agents:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/
    - Synced from GitHub repository
    - Read-only (managed by git pull)
    - 44+ agents organized by category
@@ -39,7 +39,7 @@ Why Project-Level Deployment?
 Example Flow:
 -------------
 1. User runs: claude-mpm agents deploy
-2. Agents synced from GitHub → ~/.claude-mpm/cache/remote-agents/
+2. Agents synced from GitHub → ~/.claude-mpm/cache/agents/
 3. Agents deployed FROM cache → .claude/agents/
 4. Claude Code discovers agents FROM .claude/agents/