claude-mpm 5.4.21__py3-none-any.whl → 5.4.36__py3-none-any.whl

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -42,7 +42,7 @@ class RemoteAgentMetadata:
 class RemoteAgentDiscoveryService:
     """Discovers and converts remote Markdown agents to JSON format.
 
-    Remote agents are discovered from the cache directory (~/.claude-mpm/cache/remote-agents/)
+    Remote agents are discovered from the cache directory (~/.claude-mpm/cache/agents/)
     where they are stored as Markdown files. This service:
     1. Discovers all *.md files in the remote agents cache
     2. Parses Markdown frontmatter and content to extract metadata
@@ -61,20 +61,20 @@ class RemoteAgentDiscoveryService:
     - Flexibility: Supports optional sections with defaults
     """
 
-    def __init__(self, remote_agents_dir: Path):
+    def __init__(self, agents_cache_dir: Path):
         """Initialize the remote agent discovery service.
 
         Args:
-            remote_agents_dir: Directory containing cached remote agent Markdown files
+            agents_cache_dir: Directory containing cached agent Markdown files
         """
-        self.remote_agents_dir = remote_agents_dir
+        self.agents_cache_dir = agents_cache_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/...
+        ~/.claude-mpm/cache/agents/{owner}/{repo}/agents/...
 
         Args:
             file_path: Absolute path to agent Markdown file
@@ -83,28 +83,29 @@ class RemoteAgentDiscoveryService:
             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
+            Input:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/pm.md
             Output: "bobmatnyc/claude-mpm-agents"
         """
         try:
-            # Find "remote-agents" in the path
+            # Find "agents" cache directory in the path (looking for .claude-mpm/cache/agents)
             path_parts = file_path.parts
-            remote_agents_idx = -1
+            agents_cache_idx = -1
 
             for i, part in enumerate(path_parts):
-                if part == "remote-agents":
-                    remote_agents_idx = i
+                # Look for cache/agents pattern
+                if part == "agents" and i > 0 and path_parts[i - 1] == "cache":
+                    agents_cache_idx = i
                     break
 
-            if remote_agents_idx == -1 or remote_agents_idx + 2 >= len(path_parts):
+            if agents_cache_idx == -1 or agents_cache_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]
+            # Extract owner and repo (next two parts after "cache/agents")
+            owner = path_parts[agents_cache_idx + 1]
+            repo = path_parts[agents_cache_idx + 2]
 
             collection_id = f"{owner}/{repo}"
             self.logger.debug(f"Extracted collection_id: {collection_id}")
@@ -128,25 +129,26 @@ class RemoteAgentDiscoveryService:
             Relative path from repo root, or None if not found
 
         Example:
-            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Input:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/pm.md
             Output: "agents/pm.md"
         """
         try:
-            # Find "remote-agents" in the path
+            # Find "agents" cache directory in the path
             path_parts = file_path.parts
-            remote_agents_idx = -1
+            agents_cache_idx = -1
 
             for i, part in enumerate(path_parts):
-                if part == "remote-agents":
-                    remote_agents_idx = i
+                # Look for cache/agents pattern
+                if part == "agents" and i > 0 and path_parts[i - 1] == "cache":
+                    agents_cache_idx = i
                     break
 
-            if remote_agents_idx == -1 or remote_agents_idx + 3 >= len(path_parts):
+            if agents_cache_idx == -1 or agents_cache_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
+            # cache/agents/{owner}/{repo}/{source_path}
+            repo_root_idx = agents_cache_idx + 3
             source_parts = path_parts[repo_root_idx:]
 
             return "/".join(source_parts)
@@ -273,7 +275,7 @@ class RemoteAgentDiscoveryService:
 
         Supports both cache structures:
         1. Git repo: Calculate relative to /agents/ subdirectory
-        2. Flattened cache: Calculate relative to remote_agents_dir directly
+        2. Flattened cache: Calculate relative to agents_cache_dir directly
 
         Example (Git repo):
             Input:  /cache/bobmatnyc/claude-mpm-agents/agents/engineer/backend/python-engineer.md
@@ -281,8 +283,8 @@ class RemoteAgentDiscoveryService:
             Output: engineer/backend/python-engineer
 
         Example (Flattened cache):
-            Input:  /cache/remote-agents/engineer/python-engineer.md
-            Root:   /cache/remote-agents
+            Input:  /cache/agents/engineer/python-engineer.md
+            Root:   /cache/agents
             Output: engineer/python-engineer
 
         Args:
@@ -293,7 +295,7 @@ class RemoteAgentDiscoveryService:
         """
         try:
             # Try git repo structure first: /agents/ subdirectory
-            agents_dir = self.remote_agents_dir / "agents"
+            agents_dir = self.agents_cache_dir / "agents"
             if agents_dir.exists():
                 try:
                     relative_path = file_path.relative_to(agents_dir)
@@ -301,12 +303,12 @@ class RemoteAgentDiscoveryService:
                 except ValueError:
                     pass  # Not under agents_dir, try flattened structure
 
-            # Try flattened cache structure: calculate relative to remote_agents_dir
+            # Try flattened cache structure: calculate relative to agents_cache_dir
             try:
-                relative_path = file_path.relative_to(self.remote_agents_dir)
+                relative_path = file_path.relative_to(self.agents_cache_dir)
                 return str(relative_path.with_suffix("")).replace("\\", "/")
             except ValueError:
-                pass  # Not under remote_agents_dir either
+                pass  # Not under agents_cache_dir either
 
             # Fall back to filename
             self.logger.warning(
@@ -327,7 +329,7 @@ class RemoteAgentDiscoveryService:
 
         Supports both cache structures:
         1. Git repo: Calculate relative to /agents/ subdirectory
-        2. Flattened cache: Calculate relative to remote_agents_dir directly
+        2. Flattened cache: Calculate relative to agents_cache_dir directly
 
         Example (Git repo):
             Input:  /cache/bobmatnyc/claude-mpm-agents/agents/engineer/backend/python-engineer.md
@@ -335,8 +337,8 @@ class RemoteAgentDiscoveryService:
             Output: engineer/backend
 
         Example (Flattened cache):
-            Input:  /cache/remote-agents/engineer/python-engineer.md
-            Root:   /cache/remote-agents
+            Input:  /cache/agents/engineer/python-engineer.md
+            Root:   /cache/agents
             Output: engineer
 
         Args:
@@ -347,7 +349,7 @@ class RemoteAgentDiscoveryService:
         """
         try:
             # Try git repo structure first: /agents/ subdirectory
-            agents_dir = self.remote_agents_dir / "agents"
+            agents_dir = self.agents_cache_dir / "agents"
             if agents_dir.exists():
                 try:
                     relative_path = file_path.relative_to(agents_dir)
@@ -356,13 +358,13 @@ class RemoteAgentDiscoveryService:
                 except ValueError:
                     pass  # Not under agents_dir, try flattened structure
 
-            # Try flattened cache structure: calculate relative to remote_agents_dir
+            # Try flattened cache structure: calculate relative to agents_cache_dir
             try:
-                relative_path = file_path.relative_to(self.remote_agents_dir)
+                relative_path = file_path.relative_to(self.agents_cache_dir)
                 parts = relative_path.parts[:-1]  # Exclude filename
                 return "/".join(parts) if parts else "universal"
             except ValueError:
-                pass  # Not under remote_agents_dir either
+                pass  # Not under agents_cache_dir either
 
             return "universal"
         except Exception:
@@ -385,7 +387,7 @@ class RemoteAgentDiscoveryService:
             List of agent dictionaries in JSON template format
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> agents = service.discover_remote_agents()
             >>> len(agents)
             5
@@ -394,9 +396,9 @@ class RemoteAgentDiscoveryService:
         """
         agents = []
 
-        if not self.remote_agents_dir.exists():
+        if not self.agents_cache_dir.exists():
             self.logger.debug(
-                f"Remote agents directory does not exist: {self.remote_agents_dir}"
+                f"Agents cache directory does not exist: {self.agents_cache_dir}"
             )
             return agents
 
@@ -406,8 +408,8 @@ class RemoteAgentDiscoveryService:
         # 3. Flattened cache: {path}/ - directly contains category directories (legacy)
 
         # Priority 1: Check for dist/agents/ (built output with BASE-AGENT composition)
-        dist_agents_dir = self.remote_agents_dir / "dist" / "agents"
-        agents_dir = self.remote_agents_dir / "agents"
+        dist_agents_dir = self.agents_cache_dir / "dist" / "agents"
+        agents_dir = self.agents_cache_dir / "agents"
 
         if dist_agents_dir.exists():
             # PREFERRED: Use built agents from dist/agents/
@@ -431,18 +433,18 @@ class RemoteAgentDiscoveryService:
                 "documentation",
             ]
             has_categories = any(
-                (self.remote_agents_dir / cat).exists() for cat in category_dirs
+                (self.agents_cache_dir / cat).exists() for cat in category_dirs
             )
 
             if has_categories:
                 self.logger.debug(
-                    f"Using flattened cache structure: {self.remote_agents_dir}"
+                    f"Using flattened cache structure: {self.agents_cache_dir}"
                 )
-                scan_dir = self.remote_agents_dir
+                scan_dir = self.agents_cache_dir
             else:
                 self.logger.warning(
                     f"No agent directories found. Checked: {dist_agents_dir}, {agents_dir}, "
-                    f"and category directories in {self.remote_agents_dir}. "
+                    f"and category directories in {self.agents_cache_dir}. "
                     f"Expected agents in /dist/agents/, /agents/, or category directories."
                 )
                 return agents
@@ -482,16 +484,16 @@ class RemoteAgentDiscoveryService:
 
         # In flattened cache mode, also exclude files from git repository subdirectories
         # (files under directories that contain .git folder)
-        if scan_dir == self.remote_agents_dir:
+        if scan_dir == self.agents_cache_dir:
             filtered_files = []
             for f in md_files:
                 # Check if this file is inside a git repository (has .git in path)
-                # Git repos are at {remote_agents_dir}/{owner}/{repo}/.git
-                path_parts = f.relative_to(self.remote_agents_dir).parts
+                # Git repos are at {agents_cache_dir}/{owner}/{repo}/.git
+                path_parts = f.relative_to(self.agents_cache_dir).parts
                 if len(path_parts) >= 2:
                     # Check if this looks like a git repo path (owner/repo)
                     potential_repo = (
-                        self.remote_agents_dir / path_parts[0] / path_parts[1]
+                        self.agents_cache_dir / path_parts[0] / path_parts[1]
                     )
                     if (potential_repo / ".git").exists():
                         # This file is in a git repo, skip it (we'll handle git repos separately)
@@ -518,7 +520,7 @@ class RemoteAgentDiscoveryService:
                 self.logger.warning(f"Failed to parse remote agent {md_file.name}: {e}")
 
         self.logger.info(
-            f"Discovered {len(agents)} remote agents from {self.remote_agents_dir.name}"
+            f"Discovered {len(agents)} remote agents from {self.agents_cache_dir.name}"
         )
         return agents
 
@@ -735,7 +737,7 @@ class RemoteAgentDiscoveryService:
             RemoteAgentMetadata if found, None otherwise
         """
         # Bug #4 fix: Search in /agents/ subdirectory, not root directory
-        agents_dir = self.remote_agents_dir / "agents"
+        agents_dir = self.agents_cache_dir / "agents"
         if not agents_dir.exists():
             return None
 
@@ -767,7 +769,7 @@ class RemoteAgentDiscoveryService:
             List of agent dictionaries from the specified collection
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> agents = service.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
             >>> len(agents)
             45
@@ -795,7 +797,7 @@ class RemoteAgentDiscoveryService:
             - agents: List of agent IDs in collection
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> collections = service.list_collections()
             >>> collections
             [

claude_mpm/services/agents/git_source_manager.py

@@ -50,10 +50,10 @@ class GitSourceManager:
 
         Args:
             cache_root: Root directory for repository caches.
-                       Defaults to ~/.claude-mpm/cache/remote-agents/
+                       Defaults to ~/.claude-mpm/cache/agents/
         """
         if cache_root is None:
-            cache_root = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            cache_root = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         self.cache_root = cache_root
         self.cache_root.mkdir(parents=True, exist_ok=True)

claude_mpm/services/agents/recommender.py

@@ -226,9 +226,11 @@ class AgentRecommenderService(BaseService, IAgentRecommender):
         if max_agents is not None:
             recommendations = recommendations[:max_agents]
 
-        # Check if toolchain is unknown and we have no recommendations
-        if not recommendations and toolchain.primary_language.lower() == "unknown":
-            self.logger.info("Toolchain unknown - applying default configuration")
+        # Check if we have no recommendations (any reason: unknown language, low scores, etc.)
+        if not recommendations:
+            self.logger.info(
+                f"No agents scored above threshold for {toolchain.primary_language}; using defaults"
+            )
 
             # Get default configuration
             default_config = self._capabilities_config.get("default_configuration", {})

claude_mpm/services/agents/single_tier_deployment_service.py

@@ -78,14 +78,14 @@ class SingleTierDeploymentService:
             config: Agent source configuration with repositories
             deployment_dir: Target deployment directory (.claude/agents/)
             cache_root: Cache root for repositories
-                       (defaults to ~/.claude-mpm/cache/remote-agents/)
+                       (defaults to ~/.claude-mpm/cache/agents/)
         """
         self.config = config
         self.deployment_dir = deployment_dir
         self.deployment_dir.mkdir(parents=True, exist_ok=True)
 
         if cache_root is None:
-            cache_root = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            cache_root = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         self.cache_root = cache_root
         self.git_source_manager = GitSourceManager(cache_root)

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/remote-agents/)
+            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/agents/)
             source_id: Unique identifier for this source (for multi-source support)
 
-        Design Decision: Cache to ~/.claude-mpm/cache/remote-agents/ (canonical location)
+        Design Decision: Cache to ~/.claude-mpm/cache/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 (canonical: ~/.claude-mpm/cache/remote-agents/)
+        # Setup cache directory (canonical: ~/.claude-mpm/cache/agents/)
         if cache_dir:
             self.cache_dir = Path(cache_dir)
         else:
-            # Default to ~/.claude-mpm/cache/remote-agents/ (canonical cache location)
+            # Default to ~/.claude-mpm/cache/agents/ (canonical cache location)
             home = Path.home()
-            self.cache_dir = home / ".claude-mpm" / "cache" / "remote-agents"
+            self.cache_dir = home / ".claude-mpm" / "cache" / "agents"
 
         self.cache_dir.mkdir(parents=True, exist_ok=True)
 

claude_mpm/services/agents/startup_sync.py

@@ -110,6 +110,26 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
         else:
             cache_dir = None  # Will use default
 
+        # Check for old cache directory names and provide migration guidance
+        # This handles users upgrading from older versions
+        old_cache_paths = [
+            Path.home() / ".claude-mpm" / "cache" / "remote-agents",
+        ]
+        new_cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
+
+        for old_cache in old_cache_paths:
+            if old_cache.exists() and not new_cache_dir.exists():
+                logger.warning(f"Found old cache directory: {old_cache}")
+                logger.warning(
+                    "The cache directory location has changed to: ~/.claude-mpm/cache/agents"
+                )
+                logger.warning("To migrate your existing cache, run:")
+                logger.warning(f"  mv {old_cache} {new_cache_dir}")
+                logger.info(
+                    "Agents will be re-synced to the new cache location automatically."
+                )
+                break  # Only show warning once
+
         # Sync each enabled source
         for source_config in sources:
             try:
@@ -217,7 +237,7 @@ def get_sync_status() -> Dict[str, Any]:
             "enabled": agent_sync_config.get("enabled", True),
             "sources_configured": len(enabled_sources),
             "cache_dir": agent_sync_config.get(
-                "cache_dir", "~/.claude-mpm/cache/remote-agents"
+                "cache_dir", "~/.claude-mpm/cache/agents"
             ),
         }
 
@@ -233,7 +253,7 @@ def get_sync_status() -> Dict[str, Any]:
         return {
             "enabled": False,
             "sources_configured": 0,
-            "cache_dir": "~/.claude-mpm/cache/remote-agents",
+            "cache_dir": "~/.claude-mpm/cache/agents",
             "last_sync": None,
             "error": str(e),
         }

claude_mpm/services/diagnostics/checks/agent_check.py

@@ -66,9 +66,9 @@ class AgentCheck(BaseDiagnosticCheck):
 
             if deployed_count == 0:
                 status = ValidationSeverity.ERROR
-                message = f"No agents deployed (0/{available_count} available)"
+                message = f"No agents deployed (0/{available_count} cached)"
                 fix_command = "claude-mpm agents deploy"
-                fix_description = "Deploy all available agents"
+                fix_description = "Deploy all cached agents"
             elif deployed_count < available_count:
                 status = ValidationSeverity.WARNING
                 message = f"{deployed_count}/{available_count} agents deployed"

claude_mpm/services/diagnostics/checks/agent_sources_check.py

@@ -432,7 +432,7 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
 
     def _check_cache_directory(self) -> DiagnosticResult:
         """Check cache directory health."""
-        cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+        cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         if not cache_dir.exists():
             return DiagnosticResult(

claude_mpm/services/git/git_operations_service.py

@@ -12,10 +12,10 @@ Design Decisions:
 
 Example:
     >>> service = GitOperationsService()
-    >>> success = service.create_branch(Path("~/.claude-mpm/cache/remote-agents"), "improve/research-memory")
+    >>> success = service.create_branch(Path("~/.claude-mpm/cache/agents"), "improve/research-memory")
     >>> if success:
-    ...     service.stage_files(Path("~/.claude-mpm/cache/remote-agents"), ["agents/research.md"])
-    ...     service.commit(Path("~/.claude-mpm/cache/remote-agents"), "feat: improve research agent memory handling")
+    ...     service.stage_files(Path("~/.claude-mpm/cache/agents"), ["agents/research.md"])
+    ...     service.commit(Path("~/.claude-mpm/cache/agents"), "feat: improve research agent memory handling")
 """
 
 import logging
@@ -68,7 +68,7 @@ class GitOperationsService:
 
         Example:
             >>> service = GitOperationsService()
-            >>> service.is_git_repo(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service.is_git_repo(Path("~/.claude-mpm/cache/agents"))
             True
         """
         try:
@@ -150,7 +150,7 @@ class GitOperationsService:
         Example:
             >>> service = GitOperationsService()
             >>> service.create_and_checkout_branch(
-            ...     Path("~/.claude-mpm/cache/remote-agents"),
+            ...     Path("~/.claude-mpm/cache/agents"),
             ...     "improve/research-memory",
             ...     "main"
             ... )
@@ -245,7 +245,7 @@ class GitOperationsService:
         Example:
             >>> service = GitOperationsService()
             >>> service.commit(
-            ...     Path("~/.claude-mpm/cache/remote-agents"),
+            ...     Path("~/.claude-mpm/cache/agents"),
             ...     "feat(agent): improve research agent memory handling\\n\\n- Add hard limit of 5 files"
             ... )
             True
@@ -289,7 +289,7 @@ class GitOperationsService:
 
         Example:
             >>> service = GitOperationsService()
-            >>> service.push(Path("~/.claude-mpm/cache/remote-agents"), "improve/research-memory")
+            >>> service.push(Path("~/.claude-mpm/cache/agents"), "improve/research-memory")
             True
         """
         self._validate_repo(repo_path)
@@ -489,7 +489,7 @@ class GitOperationsService:
 
         Example:
             >>> service = GitOperationsService()
-            >>> valid, msg = service.validate_repo(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> valid, msg = service.validate_repo(Path("~/.claude-mpm/cache/agents"))
             >>> if not valid:
             ...     print(f"Repository invalid: {msg}")
         """