claude-mpm 5.0.2__py3-none-any.whl → 5.1.9__py3-none-any.whl

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -51,6 +51,63 @@ class MultiSourceAgentDeploymentService:
         self.logger = get_logger(__name__)
         self.version_manager = AgentVersionManager()
 
+    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 +213,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 +254,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]]:

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -32,6 +32,9 @@ class RemoteAgentMetadata:
     routing_priority: int
     source_file: Path
     version: str  # SHA-256 hash from cache metadata
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repo
+    canonical_id: Optional[str] = None  # Format: collection_id:agent_id
 
 
 class RemoteAgentDiscoveryService:
@@ -65,6 +68,91 @@ class RemoteAgentDiscoveryService:
         self.remote_agents_dir = remote_agents_dir
         self.logger = get_logger(__name__)
 
+    def _extract_collection_id_from_path(self, file_path: Path) -> Optional[str]:
+        """Extract collection_id from repository path structure.
+
+        Collection ID is derived from the repository path structure:
+        ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/agents/...
+
+        Args:
+            file_path: Absolute path to agent Markdown file
+
+        Returns:
+            Collection ID in format "owner/repo-name" or None if not found
+
+        Example:
+            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Output: "bobmatnyc/claude-mpm-agents"
+        """
+        try:
+            # Find "remote-agents" in the path
+            path_parts = file_path.parts
+            remote_agents_idx = -1
+
+            for i, part in enumerate(path_parts):
+                if part == "remote-agents":
+                    remote_agents_idx = i
+                    break
+
+            if remote_agents_idx == -1 or remote_agents_idx + 2 >= len(path_parts):
+                self.logger.debug(
+                    f"Could not extract collection_id from path: {file_path}"
+                )
+                return None
+
+            # Extract owner and repo (next two parts after "remote-agents")
+            owner = path_parts[remote_agents_idx + 1]
+            repo = path_parts[remote_agents_idx + 2]
+
+            collection_id = f"{owner}/{repo}"
+            self.logger.debug(f"Extracted collection_id: {collection_id}")
+            return collection_id
+
+        except Exception as e:
+            self.logger.warning(
+                f"Failed to extract collection_id from {file_path}: {e}"
+            )
+            return None
+
+    def _extract_source_path_from_file(self, file_path: Path) -> Optional[str]:
+        """Extract relative source path within repository.
+
+        Source path is relative to the repository root (not the agents subdirectory).
+
+        Args:
+            file_path: Absolute path to agent Markdown file
+
+        Returns:
+            Relative path from repo root, or None if not found
+
+        Example:
+            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Output: "agents/pm.md"
+        """
+        try:
+            # Find "remote-agents" in the path
+            path_parts = file_path.parts
+            remote_agents_idx = -1
+
+            for i, part in enumerate(path_parts):
+                if part == "remote-agents":
+                    remote_agents_idx = i
+                    break
+
+            if remote_agents_idx == -1 or remote_agents_idx + 3 >= len(path_parts):
+                return None
+
+            # Path after owner/repo is the source path
+            # remote-agents/{owner}/{repo}/{source_path}
+            repo_root_idx = remote_agents_idx + 3
+            source_parts = path_parts[repo_root_idx:]
+
+            return "/".join(source_parts)
+
+        except Exception as e:
+            self.logger.warning(f"Failed to extract source_path from {file_path}: {e}")
+            return None
+
     def _generate_hierarchical_id(self, file_path: Path) -> str:
         """Generate hierarchical agent ID from file path.
 
@@ -275,17 +363,34 @@ class RemoteAgentDiscoveryService:
         # Bug #1 fix: Detect category from directory path
         category = self._detect_category_from_path(md_file)
 
+        # NEW: Extract collection metadata from path
+        collection_id = self._extract_collection_id_from_path(md_file)
+        source_path = self._extract_source_path_from_file(md_file)
+
+        # NEW: Generate canonical_id (collection_id:agent_id)
+        if collection_id:
+            canonical_id = f"{collection_id}:{agent_id}"
+        else:
+            # Fallback for legacy agents without collection
+            canonical_id = f"legacy:{agent_id}"
+
         # Convert to JSON template format and return
         # IMPORTANT: Include 'path' field for compatibility with deployment validation (ticket 1M-480)
         # Git-sourced agents must have 'path' field to match structure from AgentDiscoveryService
         return {
             "agent_id": agent_id,
+            "canonical_id": canonical_id,  # NEW: Primary matching key
+            "collection_id": collection_id,  # NEW: Collection identifier
+            "source_path": source_path,  # NEW: Path within repository
             "metadata": {
                 "name": name,
                 "description": description,
                 "version": version,
                 "author": "remote",  # Mark as remote agent
                 "category": category,  # Use detected category from path
+                "collection_id": collection_id,  # NEW: Also in metadata
+                "source_path": source_path,  # NEW: Also in metadata
+                "canonical_id": canonical_id,  # NEW: Also in metadata
             },
             "model": model,
             "source": "remote",  # Mark as remote agent
@@ -347,7 +452,12 @@ class RemoteAgentDiscoveryService:
         Returns:
             RemoteAgentMetadata if found, None otherwise
         """
-        for md_file in self.remote_agents_dir.glob("*.md"):
+        # Bug #4 fix: Search in /agents/ subdirectory, not root directory
+        agents_dir = self.remote_agents_dir / "agents"
+        if not agents_dir.exists():
+            return None
+
+        for md_file in agents_dir.rglob("*.md"):
             agent_dict = self._parse_markdown_agent(md_file)
             if agent_dict and agent_dict["metadata"]["name"] == agent_name:
                 return RemoteAgentMetadata(
@@ -359,5 +469,89 @@ class RemoteAgentDiscoveryService:
                     routing_priority=agent_dict["routing"]["priority"],
                     source_file=Path(agent_dict["source_file"]),
                     version=agent_dict["version"],
+                    collection_id=agent_dict.get("collection_id"),
+                    source_path=agent_dict.get("source_path"),
+                    canonical_id=agent_dict.get("canonical_id"),
                 )
         return None
+
+    def get_agents_by_collection(self, collection_id: str) -> List[Dict[str, Any]]:
+        """Get all agents belonging to a specific collection.
+
+        Args:
+            collection_id: Collection identifier in format "owner/repo-name"
+
+        Returns:
+            List of agent dictionaries from the specified collection
+
+        Example:
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> agents = service.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
+            >>> len(agents)
+            45
+        """
+        all_agents = self.discover_remote_agents()
+
+        # Filter by collection_id
+        collection_agents = [
+            agent for agent in all_agents if agent.get("collection_id") == collection_id
+        ]
+
+        self.logger.info(
+            f"Found {len(collection_agents)} agents in collection '{collection_id}'"
+        )
+
+        return collection_agents
+
+    def list_collections(self) -> List[Dict[str, Any]]:
+        """List all available collections with agent counts.
+
+        Returns:
+            List of collection info dictionaries with:
+            - collection_id: Collection identifier
+            - agent_count: Number of agents in collection
+            - agents: List of agent IDs in collection
+
+        Example:
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> collections = service.list_collections()
+            >>> collections
+            [
+                {
+                    "collection_id": "bobmatnyc/claude-mpm-agents",
+                    "agent_count": 45,
+                    "agents": ["pm", "engineer", "qa", ...]
+                }
+            ]
+        """
+        all_agents = self.discover_remote_agents()
+
+        # Group by collection_id
+        collections_map: Dict[str, List[str]] = {}
+
+        for agent in all_agents:
+            collection_id = agent.get("collection_id")
+            if not collection_id:
+                # Skip agents without collection (legacy)
+                continue
+
+            if collection_id not in collections_map:
+                collections_map[collection_id] = []
+
+            agent_id = agent.get("agent_id", agent.get("metadata", {}).get("name"))
+            if agent_id:
+                collections_map[collection_id].append(agent_id)
+
+        # Convert to list format
+        collections = [
+            {
+                "collection_id": coll_id,
+                "agent_count": len(agent_ids),
+                "agents": sorted(agent_ids),
+            }
+            for coll_id, agent_ids in collections_map.items()
+        ]
+
+        self.logger.info(f"Found {len(collections)} collections")
+
+        return collections

claude_mpm/services/agents/sources/git_source_sync_service.py

@@ -188,10 +188,10 @@ class GitSourceSyncService:
 
         Args:
             source_url: Base URL for raw files (without trailing slash)
-            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/agents/)
+            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/remote-agents/)
             source_id: Unique identifier for this source (for multi-source support)
 
-        Design Decision: Cache to ~/.claude-mpm/cache/agents/ (Phase 1 of refactoring)
+        Design Decision: Cache to ~/.claude-mpm/cache/remote-agents/ (canonical location)
 
         Rationale: Separates cached repository structure from deployed agents.
         This allows preserving nested directory structure in cache while
@@ -207,13 +207,13 @@ class GitSourceSyncService:
         self.source_url = source_url.rstrip("/")
         self.source_id = source_id
 
-        # Setup cache directory (Phase 1: Changed to ~/.claude-mpm/cache/agents/)
+        # Setup cache directory (canonical: ~/.claude-mpm/cache/remote-agents/)
         if cache_dir:
             self.cache_dir = Path(cache_dir)
         else:
-            # Default to ~/.claude-mpm/cache/agents/ (shared cache for nested structure)
+            # Default to ~/.claude-mpm/cache/remote-agents/ (canonical cache location)
             home = Path.home()
-            self.cache_dir = home / ".claude-mpm" / "cache" / "agents"
+            self.cache_dir = home / ".claude-mpm" / "cache" / "remote-agents"
 
         self.cache_dir.mkdir(parents=True, exist_ok=True)
 
@@ -237,6 +237,11 @@ class GitSourceSyncService:
         if etag_cache_file.exists():
             self._migrate_etag_cache(etag_cache_file)
 
+        # NEW: Initialize git manager for cache (Phase 1 integration)
+        from claude_mpm.services.agents.cache_git_manager import CacheGitManager
+
+        self.git_manager = CacheGitManager(self.cache_dir)
+
     def sync_agents(
         self,
         force_refresh: bool = False,
@@ -273,6 +278,33 @@ class GitSourceSyncService:
 
         start_time = time.time()
 
+        # NEW: Pre-sync git operations (Phase 1 integration)
+        if self.git_manager.is_git_repo():
+            logger.debug("Cache is a git repository, checking for updates...")
+
+            # Warn about uncommitted changes
+            if self.git_manager.has_uncommitted_changes():
+                uncommitted_count = len(
+                    self.git_manager.get_status().get("uncommitted", [])
+                )
+                logger.warning(
+                    f"Cache has {uncommitted_count} uncommitted change(s). "
+                    "These will be preserved, but consider committing them."
+                )
+
+            # Pull latest if online (non-blocking)
+            try:
+                success, msg = self.git_manager.pull_latest()
+                if success:
+                    logger.info(f"✅ Git pull: {msg}")
+                else:
+                    logger.warning(f"⚠️  Git pull failed: {msg}")
+                    logger.info("Continuing with HTTP sync as fallback")
+            except Exception as e:
+                logger.warning(f"Git pull error (continuing with HTTP sync): {e}")
+        else:
+            logger.debug("Cache is not a git repository, skipping git operations")
+
         results = {
             "synced": [],
             "cached": [],

claude_mpm/services/analysis/__init__.py

@@ -0,0 +1,25 @@
+"""
+Analysis services for Claude MPM.
+
+Provides postmortem analysis and error improvement suggestions.
+"""
+
+from .postmortem_service import (
+    ActionType,
+    ErrorAnalysis,
+    ErrorCategory,
+    ImprovementAction,
+    PostmortemReport,
+    PostmortemService,
+    get_postmortem_service,
+)
+
+__all__ = [
+    "ActionType",
+    "ErrorAnalysis",
+    "ErrorCategory",
+    "ImprovementAction",
+    "PostmortemReport",
+    "PostmortemService",
+    "get_postmortem_service",
+]