claude-mpm 5.1.8__py3-none-any.whl → 5.4.22__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/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)

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -129,12 +129,13 @@ 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
+            # Stop at common repository root indicators (check AFTER finding BASE-AGENT.md)
+            # This ensures we check the 'agents' directory before stopping at 'remote-agents'
             if current_dir.name in [".claude-mpm", "remote-agents", "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/multi_source_deployment_service.py

@@ -16,6 +16,8 @@ import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+import yaml
+
 from claude_mpm.core.config import Config
 from claude_mpm.core.logging_config import get_logger
 
@@ -51,6 +53,127 @@ class MultiSourceAgentDeploymentService:
         self.logger = get_logger(__name__)
         self.version_manager = AgentVersionManager()
 
+    def _read_template_version(self, template_path: Path) -> Optional[str]:
+        """Read version from template file (supports both .md and .json formats).
+
+        For .md files: Extract version from YAML frontmatter
+        For .json files: Extract version from JSON structure
+
+        Args:
+            template_path: Path to template file
+
+        Returns:
+            Version string or None if version cannot be extracted
+        """
+        try:
+            if template_path.suffix == ".md":
+                # Parse markdown with YAML frontmatter
+                content = template_path.read_text()
+
+                # Extract YAML frontmatter (between --- markers)
+                if not content.strip().startswith("---"):
+                    return None
+
+                parts = content.split("---", 2)
+                if len(parts) < 3:
+                    return None
+
+                # Parse YAML frontmatter
+                frontmatter = yaml.safe_load(parts[1])
+                if not frontmatter:
+                    return None
+
+                # Extract version from frontmatter
+                version = frontmatter.get("version")
+                return version if version else None
+
+            if template_path.suffix == ".json":
+                # Parse JSON template
+                template_data = json.loads(template_path.read_text())
+                metadata = template_data.get("metadata", {})
+                version = (
+                    template_data.get("agent_version")
+                    or template_data.get("version")
+                    or metadata.get("version")
+                )
+                return version if version else None
+
+            self.logger.warning(
+                f"Unknown template format: {template_path.suffix} for {template_path.name}"
+            )
+            return None
+
+        except yaml.YAMLError as e:
+            self.logger.warning(
+                f"Invalid YAML frontmatter in {template_path.name}: {e}"
+            )
+            return None
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Invalid JSON in {template_path.name}: {e}")
+            return None
+        except Exception as e:
+            self.logger.warning(
+                f"Error reading template version from {template_path.name}: {e}"
+            )
+            return None
+
+    def _build_canonical_id_for_agent(self, agent_info: Dict[str, Any]) -> str:
+        """Build or retrieve canonical_id for an agent.
+
+        NEW: Supports enhanced agent matching via canonical_id.
+
+        Priority:
+        1. Use existing canonical_id from agent_info if present
+        2. Generate from collection_id + agent_id if available
+        3. Fallback to legacy:{filename} for backward compatibility
+
+        Args:
+            agent_info: Agent dictionary with metadata
+
+        Returns:
+            Canonical ID string for matching
+
+        Example:
+            Remote agent: "bobmatnyc/claude-mpm-agents:pm"
+            Legacy agent: "legacy:custom-agent"
+        """
+        # Priority 1: Existing canonical_id
+        if "canonical_id" in agent_info:
+            return agent_info["canonical_id"]
+
+        # Priority 2: Generate from collection_id + agent_id
+        collection_id = agent_info.get("collection_id")
+        agent_id = agent_info.get("agent_id")
+
+        if collection_id and agent_id:
+            canonical_id = f"{collection_id}:{agent_id}"
+            # Cache it in agent_info for future use
+            agent_info["canonical_id"] = canonical_id
+            return canonical_id
+
+        # Priority 3: Fallback to legacy format
+        # Use filename or agent name
+        agent_name = agent_info.get("name") or agent_info.get("metadata", {}).get(
+            "name", "unknown"
+        )
+
+        # Extract filename from path
+        path_str = (
+            agent_info.get("path")
+            or agent_info.get("file_path")
+            or agent_info.get("source_file")
+        )
+
+        if path_str:
+            filename = Path(path_str).stem
+            canonical_id = f"legacy:{filename}"
+        else:
+            canonical_id = f"legacy:{agent_name}"
+
+        # Cache it
+        agent_info["canonical_id"] = canonical_id
+        return canonical_id
+
     def discover_agents_from_all_sources(
         self,
         system_templates_dir: Optional[Path] = None,
@@ -156,11 +279,19 @@ class MultiSourceAgentDeploymentService:
                     agent_info["source"] = source_name
                     agent_info["source_dir"] = str(source_dir)
 
+                    # NEW: Build canonical_id for enhanced matching
+                    canonical_id = self._build_canonical_id_for_agent(agent_info)
+
+                    # Group by canonical_id (PRIMARY) for enhanced matching
+                    # This allows matching agents from different sources with same canonical_id
+                    # while maintaining backward compatibility with name-based matching
+                    matching_key = canonical_id
+
                     # Initialize list if this is the first occurrence of this agent
-                    if agent_name not in agents_by_name:
-                        agents_by_name[agent_name] = []
+                    if matching_key not in agents_by_name:
+                        agents_by_name[matching_key] = []
 
-                    agents_by_name[agent_name].append(agent_info)
+                    agents_by_name[matching_key].append(agent_info)
 
                 # Use more specific log message
                 self.logger.info(
@@ -189,6 +320,48 @@ class MultiSourceAgentDeploymentService:
 
         return agents_by_name
 
+    def get_agents_by_collection(
+        self,
+        collection_id: str,
+        remote_agents_dir: Optional[Path] = None,
+    ) -> List[Dict[str, Any]]:
+        """Get all agents from a specific collection.
+
+        NEW: Enables collection-based agent selection.
+
+        Args:
+            collection_id: Collection identifier (e.g., "bobmatnyc/claude-mpm-agents")
+            remote_agents_dir: Directory containing remote agents cache
+
+        Returns:
+            List of agent dictionaries from the specified collection
+
+        Example:
+            >>> service = MultiSourceAgentDeploymentService()
+            >>> agents = service.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
+            >>> len(agents)
+            45
+        """
+        if not remote_agents_dir:
+            cache_dir = Path.home() / ".claude-mpm" / "cache"
+            remote_agents_dir = cache_dir / "remote-agents"
+
+        if not remote_agents_dir.exists():
+            self.logger.warning(
+                f"Remote agents directory not found: {remote_agents_dir}"
+            )
+            return []
+
+        # Use RemoteAgentDiscoveryService to get collection agents
+        remote_service = RemoteAgentDiscoveryService(remote_agents_dir)
+        collection_agents = remote_service.get_agents_by_collection(collection_id)
+
+        self.logger.info(
+            f"Retrieved {len(collection_agents)} agents from collection '{collection_id}'"
+        )
+
+        return collection_agents
+
     def select_highest_version_agents(
         self, agents_by_name: Dict[str, List[Dict[str, Any]]]
     ) -> Dict[str, Dict[str, Any]]:
@@ -720,17 +893,20 @@ class MultiSourceAgentDeploymentService:
                 comparison_results["needs_update"].append(agent_name)
                 continue
 
-            # 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")
-                    or metadata.get("version", "0.0.0")
+            # Read template version using format-aware helper
+            version_string = self._read_template_version(template_path)
+            if not version_string:
+                self.logger.warning(
+                    f"Could not extract version from template for '{agent_name}', skipping"
                 )
+                continue
+
+            try:
+                template_version = self.version_manager.parse_version(version_string)
             except Exception as e:
-                self.logger.warning(f"Error reading template for '{agent_name}': {e}")
+                self.logger.warning(
+                    f"Error parsing version '{version_string}' for '{agent_name}': {e}"
+                )
                 continue
 
             # Read deployed version