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

claude_mpm/services/agents/deployment/agent_validator.py

@@ -326,17 +326,41 @@ class AgentValidator:
             "path": str(agent_file),
             "description": "No description",
             "version": "unknown",
+            "type": "agent",  # Default type
         }
 
-        # Extract from YAML frontmatter
+        # Extract ONLY from YAML frontmatter (between --- markers)
         lines = content.split("\n")
+        in_frontmatter = False
+        frontmatter_ended = False
+
         for line in lines:
-            if line.startswith("name:"):
-                agent_info["name"] = line.split(":", 1)[1].strip().strip("\"'")
-            elif line.startswith("description:"):
-                agent_info["description"] = line.split(":", 1)[1].strip().strip("\"'")
-            elif line.startswith("version:"):
-                agent_info["version"] = line.split(":", 1)[1].strip().strip("\"'")
+            stripped_line = line.strip()
+
+            # Track frontmatter boundaries
+            if stripped_line == "---":
+                if not in_frontmatter:
+                    in_frontmatter = True
+                    continue
+                frontmatter_ended = True
+                break  # Stop parsing after frontmatter ends
+
+            # Only parse within frontmatter
+            if not in_frontmatter or frontmatter_ended:
+                continue
+
+            if stripped_line.startswith("name:"):
+                agent_info["name"] = stripped_line.split(":", 1)[1].strip().strip("\"'")
+            elif stripped_line.startswith("description:"):
+                agent_info["description"] = (
+                    stripped_line.split(":", 1)[1].strip().strip("\"'")
+                )
+            elif stripped_line.startswith("version:"):
+                agent_info["version"] = (
+                    stripped_line.split(":", 1)[1].strip().strip("\"'")
+                )
+            elif stripped_line.startswith("type:"):
+                agent_info["type"] = stripped_line.split(":", 1)[1].strip().strip("\"'")
 
         return agent_info
 

claude_mpm/services/agents/deployment/agent_version_manager.py

@@ -237,11 +237,14 @@ class AgentVersionManager:
 
             # Skip non-system agents (user-created)
             # Check for various author formats used by system agents
-            if not any(author in deployed_content.lower() for author in [
-                "author: claude-mpm",
-                "author: claude mpm team",
-                "author: claude mpm"
-            ]):
+            if not any(
+                author in deployed_content.lower()
+                for author in [
+                    "author: claude-mpm",
+                    "author: claude mpm team",
+                    "author: claude mpm",
+                ]
+            ):
                 return (False, "not a system agent")
 
             # Extract version info from YAML frontmatter

claude_mpm/services/agents/deployment/agent_versioning.py

@@ -30,5 +30,5 @@ class AgentVersionManager:
             for part in parts:
                 int(part)
             return True
-        except:
+        except Exception:
             return False

claude_mpm/services/agents/deployment/agents_directory_resolver.py

@@ -2,6 +2,47 @@
 
 This module handles determining the correct agents directory for deployment
 based on different deployment scenarios and target directories.
+
+DEPLOYMENT ARCHITECTURE:
+=======================
+
+Agent Source Locations (Discovery):
+-----------------------------------
+1. System Agents:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/
+   - Synced from GitHub repository
+   - Read-only (managed by git pull)
+   - 44+ agents organized by category
+
+2. User Agents:    ~/.claude-mpm/agents/
+   - User-created custom agents
+   - Personal agent definitions
+
+3. Project Agents: .claude-mpm/agents/
+   - Project-specific agents
+   - Overrides for system/user agents
+
+Agent Deployment Target (Runtime):
+----------------------------------
+ALL AGENTS DEPLOY TO: <project_root>/.claude/agents/
+   - Single deployment location for ALL agents (system, user, project)
+   - Claude Code discovers agents from this directory
+   - Ensures consistent agent availability across sessions
+   - Simplifies agent management and version control
+
+Why Project-Level Deployment?
+------------------------------
+1. **Consistency**: All team members work with same agents
+2. **Versioning**: Agent deployments tracked in git
+3. **Isolation**: Different projects can have different agent versions
+4. **Performance**: No global agent conflicts or version mismatches
+
+Example Flow:
+-------------
+1. User runs: claude-mpm agents deploy
+2. Agents synced from GitHub → ~/.claude-mpm/cache/remote-agents/
+3. Agents deployed FROM cache → .claude/agents/
+4. Claude Code discovers agents FROM .claude/agents/
+
 Extracted from AgentDeploymentService to reduce complexity.
 """
 
@@ -28,36 +69,81 @@ class AgentsDirectoryResolver:
         """
         Determine the correct agents directory based on input.
 
-        MODIFIED: Always deploy to project .claude/agents directory
-        regardless of agent source (system, user, or project).
+        DEPLOYMENT STRATEGY:
+        ====================
+        Always deploy to project .claude/agents directory regardless of agent
+        source (system, user, or project). This ensures:
+        - All agents available in single location
+        - Claude Code agent discovery works consistently
+        - Version control tracks deployed agents
+        - No global agent conflicts between projects
 
-        This ensures all agents are deployed at the project level while
-        maintaining discovery from both user (~/.claude-mpm) and project
-        (.claude-mpm) directories.
+        LOGIC FLOW:
+        -----------
+        1. If target_dir is None (default case):
+           → Deploy to: <working_directory>/.claude/agents
+           → This is 99% of use cases (standard deployment)
+
+        2. If target_dir is provided explicitly:
+           → Normalize the path based on directory name:
+             - Already "agents" directory? → Use as-is
+             - Is ".claude-mpm" directory? → Add /agents
+             - Is ".claude" directory? → Add /agents
+             - Otherwise? → Treat as project root, add /.claude/agents
+
+        EXAMPLES:
+        ---------
+        Standard deployment (target_dir=None):
+          working_directory = /Users/masa/Projects/my-app
+          → Returns: /Users/masa/Projects/my-app/.claude/agents
+
+        Explicit target (target_dir="/some/path/.claude"):
+          → Returns: /some/path/.claude/agents
+
+        Explicit target (target_dir="/some/path/.claude/agents"):
+          → Returns: /some/path/.claude/agents (no modification)
 
         Args:
-            target_dir: Optional target directory
+            target_dir: Optional target directory override
+                       None = use default project .claude/agents (recommended)
+                       Path = explicitly specify deployment location (advanced)
 
         Returns:
-            Path to agents directory
+            Path: Resolved agents directory path
+
+        Note:
+            The default behavior (target_dir=None) is the recommended approach.
+            Only provide target_dir for advanced use cases or testing.
         """
         if not target_dir:
-            # Always deploy to project directory
-            # This is the key change - all agents go to project .claude/agents
+            # DEFAULT CASE: Deploy to project .claude/agents directory
+            # This is the standard behavior for all normal deployments
+            # Example: /Users/masa/Projects/my-app → /Users/masa/Projects/my-app/.claude/agents
             return self.working_directory / ".claude" / "agents"
 
-        # If target_dir provided, use it directly (caller decides structure)
+        # EXPLICIT TARGET CASE: User/caller provided specific target directory
+        # Normalize target_dir to proper agents directory based on structure
         target_dir = Path(target_dir)
 
-        # Check if this is already an agents directory
+        # Pattern 1: Already an agents directory
         if target_dir.name == "agents":
-            # Already an agents directory, use as-is
+            # Already targeting agents dir explicitly, use as-is
+            # Example: /some/path/.claude/agents → /some/path/.claude/agents
             return target_dir
+
+        # Pattern 2: Targeting .claude-mpm directory
         if target_dir.name == ".claude-mpm":
-            # .claude-mpm directory, add agents subdirectory
+            # Add agents subdirectory to .claude-mpm
+            # Example: /some/path/.claude-mpm → /some/path/.claude-mpm/agents
             return target_dir / "agents"
+
+        # Pattern 3: Targeting .claude directory
         if target_dir.name == ".claude":
-            # .claude directory, add agents subdirectory
+            # Add agents subdirectory to .claude
+            # Example: /some/path/.claude → /some/path/.claude/agents
             return target_dir / "agents"
-        # Assume it's a project directory, add .claude/agents
+
+        # Pattern 4: Targeting project root or other directory
+        # Assume it's a project directory, add full .claude/agents path
+        # Example: /some/project → /some/project/.claude/agents
         return target_dir / ".claude" / "agents"

claude_mpm/services/agents/deployment/async_agent_deployment.py

@@ -200,9 +200,10 @@ class AsyncAgentDeploymentService:
                 return str(directory), []
 
             # Use asyncio to run glob in executor (since Path.glob is blocking)
+            # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
             loop = asyncio.get_event_loop()
             files = await loop.run_in_executor(
-                self.executor, lambda: list(directory.glob("*.json"))
+                self.executor, lambda: list(directory.glob("*.md"))
             )
 
             self.logger.debug(f"Found {len(files)} agents in {directory}")
@@ -224,7 +225,7 @@ class AsyncAgentDeploymentService:
 
         elapsed = (time.time() - start_time) * 1000
         self._metrics["time_saved_ms"] += max(0, (len(directories) * 75) - elapsed)
-        self.logger.info(f"Discovered agents in {elapsed:.1f}ms (parallel scan)")
+        self.logger.debug(f"Discovered agents in {elapsed:.1f}ms (parallel scan)")
 
         return discovered
 

claude_mpm/services/agents/deployment/deployment_config_loader.py

@@ -5,7 +5,7 @@ Extracted from AgentDeploymentService to reduce complexity and improve maintaina
 """
 
 import logging
-from typing import Optional, Tuple
+from typing import Any, Dict, Optional, Tuple
 
 from claude_mpm.core.config import Config
 
@@ -34,8 +34,13 @@ class DeploymentConfigLoader:
         if config is None:
             config = Config()
 
-        # Get agent exclusion configuration
-        excluded_agents = config.get("agent_deployment.excluded_agents", [])
+        # Get new configuration format first, fall back to legacy
+        disabled_agents = config.get("agent_deployment.disabled_agents", [])
+
+        # Fall back to legacy excluded_agents if disabled_agents is empty
+        if not disabled_agents:
+            disabled_agents = config.get("agent_deployment.excluded_agents", [])
+
         case_sensitive = config.get("agent_deployment.case_sensitive", False)
         exclude_dependencies = config.get(
             "agent_deployment.exclude_dependencies", False
@@ -43,12 +48,131 @@ class DeploymentConfigLoader:
 
         # Normalize excluded agents list for comparison
         if not case_sensitive:
-            excluded_agents = [agent.lower() for agent in excluded_agents]
+            disabled_agents = [agent.lower() for agent in disabled_agents]
 
         # Log exclusion configuration if agents are being excluded
-        if excluded_agents:
-            self.logger.info(f"Excluding agents from deployment: {excluded_agents}")
+        if disabled_agents:
+            self.logger.info(f"Excluding agents from deployment: {disabled_agents}")
             self.logger.debug(f"Case sensitive matching: {case_sensitive}")
             self.logger.debug(f"Exclude dependencies: {exclude_dependencies}")
 
-        return config, excluded_agents
+        return config, disabled_agents
+
+    def get_deployment_settings(
+        self, config: Optional[Config] = None
+    ) -> Dict[str, Any]:
+        """
+        Get comprehensive deployment settings from configuration.
+
+        Args:
+            config: Optional configuration object
+
+        Returns:
+            Dictionary of deployment settings
+        """
+        if config is None:
+            config = Config()
+
+        return {
+            "enabled_agents": config.get("agent_deployment.enabled_agents", []),
+            "disabled_agents": config.get("agent_deployment.disabled_agents", [])
+            or config.get("agent_deployment.excluded_agents", []),
+            "deploy_system_agents": config.get(
+                "agent_deployment.deploy_system_agents", True
+            ),
+            "deploy_local_agents": config.get(
+                "agent_deployment.deploy_local_agents", True
+            ),
+            "deploy_user_agents": config.get(
+                "agent_deployment.deploy_user_agents", True
+            ),
+            "prefer_local_over_system": config.get(
+                "agent_deployment.prefer_local_over_system", True
+            ),
+            "version_comparison": config.get(
+                "agent_deployment.version_comparison", True
+            ),
+            "case_sensitive": config.get("agent_deployment.case_sensitive", False),
+            "exclude_dependencies": config.get(
+                "agent_deployment.exclude_dependencies", False
+            ),
+        }
+
+    def should_deploy_agent(
+        self, agent_id: str, agent_source: str, config: Optional[Config] = None
+    ) -> bool:
+        """
+        Check if an agent should be deployed based on configuration.
+
+        Args:
+            agent_id: The agent identifier
+            agent_source: The source of the agent ('system', 'local', 'user')
+            config: Optional configuration object
+
+        Returns:
+            True if the agent should be deployed, False otherwise
+        """
+        if config is None:
+            config = Config()
+
+        settings = self.get_deployment_settings(config)
+
+        # Check startup configuration for system agents
+        if agent_source == "system":
+            # Check startup configuration first
+            startup_enabled = config.get("startup.enabled_agents", [])
+            if startup_enabled:
+                # Normalize for comparison
+                check_id = agent_id if settings["case_sensitive"] else agent_id.lower()
+                startup_list = (
+                    startup_enabled
+                    if settings["case_sensitive"]
+                    else [a.lower() for a in startup_enabled]
+                )
+                if check_id not in startup_list:
+                    self.logger.debug(
+                        f"Skipping system agent {agent_id} - not in startup enabled list"
+                    )
+                    return False
+
+        # Check if the source type is enabled
+        if agent_source == "system" and not settings["deploy_system_agents"]:
+            self.logger.debug(
+                f"Skipping system agent {agent_id} - system agents disabled"
+            )
+            return False
+        if agent_source == "local" and not settings["deploy_local_agents"]:
+            self.logger.debug(
+                f"Skipping local agent {agent_id} - local agents disabled"
+            )
+            return False
+        if agent_source == "user" and not settings["deploy_user_agents"]:
+            self.logger.debug(f"Skipping user agent {agent_id} - user agents disabled")
+            return False
+
+        # Normalize agent_id for comparison if not case sensitive
+        check_id = agent_id if settings["case_sensitive"] else agent_id.lower()
+
+        # Check enabled list (if specified, only these agents are deployed)
+        enabled = settings["enabled_agents"]
+        if enabled:
+            enabled_list = (
+                enabled if settings["case_sensitive"] else [a.lower() for a in enabled]
+            )
+            if check_id not in enabled_list:
+                self.logger.debug(f"Skipping agent {agent_id} - not in enabled list")
+                return False
+
+        # Check disabled list
+        disabled = settings["disabled_agents"]
+        if disabled:
+            disabled_list = (
+                disabled
+                if settings["case_sensitive"]
+                else [a.lower() for a in disabled]
+            )
+            if check_id in disabled_list:
+                self.logger.debug(f"Skipping agent {agent_id} - in disabled list")
+                return False
+
+        return True

claude_mpm/services/agents/deployment/deployment_type_detector.py

@@ -63,13 +63,11 @@ class DeploymentTypeDetector:
         """
         # Check if we're in a project directory with .claude-mpm/agents
         project_agents_dir = working_directory / ".claude-mpm" / "agents"
-        if project_agents_dir.exists():
-            # Check if templates_dir points to project agents
-            if templates_dir and templates_dir.exists():
-                try:
-                    return project_agents_dir.resolve() == templates_dir.resolve()
-                except Exception:
-                    pass
+        if project_agents_dir.exists() and templates_dir and templates_dir.exists():
+            try:
+                return project_agents_dir.resolve() == templates_dir.resolve()
+            except Exception:
+                pass
         return False
 
     @staticmethod
@@ -86,13 +84,11 @@ class DeploymentTypeDetector:
             True if deploying user custom agents, False otherwise
         """
         user_agents_dir = Path.home() / ".claude-mpm" / "agents"
-        if user_agents_dir.exists():
-            # Check if templates_dir points to user agents
-            if templates_dir and templates_dir.exists():
-                try:
-                    return user_agents_dir.resolve() == templates_dir.resolve()
-                except Exception:
-                    pass
+        if user_agents_dir.exists() and templates_dir and templates_dir.exists():
+            try:
+                return user_agents_dir.resolve() == templates_dir.resolve()
+            except Exception:
+                pass
         return False
 
     @staticmethod

claude_mpm/services/agents/deployment/deployment_wrapper.py

@@ -1,5 +1,6 @@
 """Temporary wrapper to provide backward compatibility for CLI commands."""
 
+import contextlib
 from pathlib import Path
 from typing import Any, Dict
 
@@ -69,3 +70,60 @@ class DeploymentServiceWrapper:
             "errors": [],
             "target_dir": str(project_dir),
         }
+
+    def get_agent_details(self, agent_name: str) -> Dict[str, Any]:
+        """Get detailed information for a specific agent.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Agent details dictionary or empty dict if not found
+        """
+        try:
+            # Try to get from list of available agents
+            available_agents = self.service.list_available_agents()
+            for agent in available_agents:
+                if agent.get("name") == agent_name:
+                    # Get template path for the agent
+                    templates_dir = self.service.templates_dir
+                    agent_path = templates_dir / f"{agent_name}.md"
+
+                    # Read agent content if file exists
+                    if agent_path.exists():
+                        with agent_path.open() as f:
+                            content = f.read()
+
+                        # Parse metadata from content
+                        import yaml
+
+                        metadata = {}
+                        if content.startswith("---"):
+                            # Extract frontmatter
+                            parts = content.split("---", 2)
+                            if len(parts) >= 2:
+                                with contextlib.suppress(yaml.YAMLError):
+                                    metadata = yaml.safe_load(parts[1])
+
+                        return {
+                            "name": agent_name,
+                            "path": str(agent_path),
+                            "type": agent.get("type", "agent"),
+                            "version": metadata.get("version", "1.0.0"),
+                            "description": metadata.get("description", ""),
+                            "specializations": metadata.get("specializations", []),
+                            "metadata": metadata,
+                            "content": content,
+                            "exists": True,
+                        }
+
+            # Agent not found in available agents
+            return {
+                "name": agent_name,
+                "exists": False,
+                "error": f"Agent '{agent_name}' not found",
+            }
+
+        except Exception as e:
+            # Return error information
+            return {"name": agent_name, "exists": False, "error": str(e)}

claude_mpm/services/agents/deployment/facade/deployment_facade.py

@@ -89,9 +89,9 @@ class DeploymentFacade:
 
             results["metadata"]["facade_version"] = "1.0.0"
             results["metadata"]["selected_executor"] = executor.get_executor_name()
-            results["metadata"][
-                "executor_characteristics"
-            ] = executor.get_performance_characteristics()
+            results["metadata"]["executor_characteristics"] = (
+                executor.get_performance_characteristics()
+            )
 
             return results
 

claude_mpm/services/agents/deployment/interface_adapter.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import Any, Dict, List, Tuple
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.interfaces import AgentDeploymentInterface
 from claude_mpm.core.logger import get_logger
 
@@ -195,7 +196,7 @@ class AgentDeploymentInterfaceAdapter(AgentDeploymentInterface):
             # Ensure the result is a dictionary
             if not isinstance(status, dict):
                 return {
-                    "status": "unknown",
+                    "status": OperationResult.UNKNOWN,
                     "error": "Invalid status format from deployment service",
                     "interface_version": "1.0.0",
                     "adapter_used": True,
@@ -210,7 +211,7 @@ class AgentDeploymentInterfaceAdapter(AgentDeploymentInterface):
         except Exception as e:
             self.logger.error(f"Failed to get deployment status: {e}", exc_info=True)
             return {
-                "status": "error",
+                "status": OperationResult.ERROR,
                 "error": str(e),
                 "interface_version": "1.0.0",
                 "adapter_used": True,