claude-mpm 3.9.11__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/services/agents/deployment/agent_discovery_service.py

@@ -0,0 +1,387 @@
+"""Agent Discovery Service
+
+This service handles the discovery, filtering, and metadata extraction of agent templates.
+Provides centralized logic for finding available agents and determining which should be deployed.
+
+Extracted from AgentDeploymentService as part of the refactoring to improve
+maintainability and testability.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.config import Config
+from claude_mpm.core.logging_config import get_logger
+
+
+class AgentDiscoveryService:
+    """Service for discovering and filtering agent templates.
+
+    This service handles:
+    - Agent template discovery across multiple directories
+    - Template filtering based on configuration
+    - Agent metadata extraction and validation
+    - Available agent listing and categorization
+    """
+
+    def __init__(self, templates_dir: Path):
+        """Initialize the agent discovery service.
+
+        Args:
+            templates_dir: Directory containing agent templates
+        """
+        self.logger = get_logger(__name__)
+        self.templates_dir = templates_dir
+
+    def list_available_agents(self) -> List[Dict[str, Any]]:
+        """
+        List all available agent templates with their metadata.
+
+        Returns:
+            List of agent information dictionaries containing:
+            - name: Agent name
+            - description: Agent description
+            - version: Agent version
+            - tools: List of tools the agent uses
+            - specializations: Agent specializations
+            - file_path: Path to template file
+        """
+        agents = []
+
+        if not self.templates_dir.exists():
+            self.logger.warning(
+                f"Templates directory does not exist: {self.templates_dir}"
+            )
+            return agents
+
+        # Find all JSON template files
+        template_files = list(self.templates_dir.glob("*.json"))
+
+        for template_file in template_files:
+            try:
+                agent_info = self._extract_agent_metadata(template_file)
+                if agent_info:
+                    agents.append(agent_info)
+
+            except Exception as e:
+                self.logger.error(
+                    f"Failed to process template {template_file.name}: {e}"
+                )
+                continue
+
+        # Sort by agent name for consistent ordering
+        agents.sort(key=lambda x: x.get("name", ""))
+
+        self.logger.info(f"Discovered {len(agents)} available agent templates")
+        return agents
+
+    def get_filtered_templates(
+        self, excluded_agents: List[str], config: Optional[Config] = None
+    ) -> List[Path]:
+        """
+        Get filtered list of template files based on configuration.
+
+        Args:
+            excluded_agents: List of agent names to exclude
+            config: Configuration object for additional filtering
+
+        Returns:
+            List of template file paths to deploy
+        """
+        if not self.templates_dir.exists():
+            self.logger.error(f"Templates directory not found: {self.templates_dir}")
+            return []
+
+        # Get all template files
+        template_files = list(self.templates_dir.glob("*.json"))
+
+        if not template_files:
+            self.logger.warning(f"No agent templates found in {self.templates_dir}")
+            return []
+
+        # Apply exclusion filtering
+        filtered_files = []
+        excluded_count = 0
+
+        for template_file in template_files:
+            agent_name = template_file.stem
+
+            # Check if agent is excluded
+            if self._is_agent_excluded(agent_name, excluded_agents, config):
+                excluded_count += 1
+                self.logger.debug(f"Excluding agent: {agent_name}")
+                continue
+
+            # Validate template file
+            if self._validate_template_file(template_file):
+                filtered_files.append(template_file)
+            else:
+                self.logger.warning(f"Invalid template file: {template_file.name}")
+
+        self.logger.info(
+            f"Found {len(template_files)} templates, excluded {excluded_count}, deploying {len(filtered_files)}"
+        )
+        return filtered_files
+
+    def find_agent_template(self, agent_name: str) -> Optional[Path]:
+        """
+        Find template file for a specific agent.
+
+        Args:
+            agent_name: Name of the agent to find
+
+        Returns:
+            Path to template file if found, None otherwise
+        """
+        template_file = self.templates_dir / f"{agent_name}.json"
+
+        if template_file.exists():
+            if self._validate_template_file(template_file):
+                return template_file
+            else:
+                self.logger.error(f"Invalid template file: {template_file}")
+                return None
+
+        self.logger.error(f"Template not found for agent: {agent_name}")
+        return None
+
+    def get_agent_categories(self) -> Dict[str, List[str]]:
+        """
+        Categorize available agents by type/specialization.
+
+        Returns:
+            Dictionary mapping categories to lists of agent names
+        """
+        categories = {}
+        agents = self.list_available_agents()
+
+        for agent in agents:
+            agent_name = agent.get("name", "unknown")
+            specializations = agent.get("specializations", [])
+
+            # Categorize by specializations
+            if specializations:
+                for spec in specializations:
+                    if spec not in categories:
+                        categories[spec] = []
+                    categories[spec].append(agent_name)
+            else:
+                # Default category for agents without specializations
+                if "general" not in categories:
+                    categories["general"] = []
+                categories["general"].append(agent_name)
+
+        return categories
+
+    def _extract_agent_metadata(self, template_file: Path) -> Optional[Dict[str, Any]]:
+        """
+        Extract metadata from an agent template file.
+
+        Args:
+            template_file: Path to the template file
+
+        Returns:
+            Dictionary with agent metadata or None if extraction fails
+        """
+        try:
+            # Read and parse template file
+            template_content = template_file.read_text()
+            template_data = json.loads(template_content)
+
+            # Extract basic metadata from the metadata section (per agent schema)
+            metadata = template_data.get("metadata", {})
+            capabilities = template_data.get("capabilities", {})
+
+            agent_info = {
+                "name": metadata.get("name", template_file.stem),
+                "description": metadata.get("description", "No description available"),
+                "version": template_data.get(
+                    "agent_version", template_data.get("version", "1.0.0")
+                ),
+                "tools": capabilities.get("tools", []),
+                "specializations": metadata.get(
+                    "tags", []
+                ),  # Use tags as specializations
+                "file": template_file.name,
+                "path": str(template_file),
+                "file_path": str(template_file),  # Keep for backward compatibility
+                "size": template_file.stat().st_size,
+                "model": capabilities.get("model", "sonnet"),
+                "author": metadata.get("author", "unknown"),
+            }
+
+            # Validate required fields
+            if not agent_info["name"]:
+                self.logger.warning(f"Template missing name: {template_file.name}")
+                return None
+
+            return agent_info
+
+        except json.JSONDecodeError as e:
+            self.logger.error(f"Invalid JSON in template {template_file.name}: {e}")
+            return None
+        except Exception as e:
+            self.logger.error(
+                f"Failed to extract metadata from {template_file.name}: {e}"
+            )
+            return None
+
+    def _is_agent_excluded(
+        self,
+        agent_name: str,
+        excluded_agents: List[str],
+        config: Optional[Config] = None,
+    ) -> bool:
+        """
+        Check if an agent should be excluded from deployment.
+
+        Args:
+            agent_name: Name of the agent to check
+            excluded_agents: List of explicitly excluded agents
+            config: Configuration object for additional exclusion rules
+
+        Returns:
+            True if agent should be excluded, False otherwise
+        """
+        # Check explicit exclusion list
+        if excluded_agents:
+            # Determine case sensitivity from config
+            case_sensitive = True
+            if config:
+                case_sensitive = config.get(
+                    "agent_deployment.case_sensitive_exclusion", True
+                )
+
+            if case_sensitive:
+                if agent_name in excluded_agents:
+                    return True
+            else:
+                # Case-insensitive comparison
+                agent_name_lower = agent_name.lower()
+                excluded_lower = [name.lower() for name in excluded_agents]
+                if agent_name_lower in excluded_lower:
+                    return True
+
+        # Check for additional exclusion rules from config
+        if config:
+            # Check pattern-based exclusions
+            exclusion_patterns = config.get("agent_deployment.exclusion_patterns", [])
+            for pattern in exclusion_patterns:
+                if pattern in agent_name:
+                    return True
+
+            # Check environment-specific exclusions
+            environment = config.get("environment", "development")
+            env_exclusions = config.get(
+                f"agent_deployment.{environment}_exclusions", []
+            )
+            if agent_name in env_exclusions:
+                return True
+
+        return False
+
+    def _validate_template_file(self, template_file: Path) -> bool:
+        """
+        Validate that a template file is properly formatted.
+
+        Args:
+            template_file: Path to template file to validate
+
+        Returns:
+            True if template is valid, False otherwise
+        """
+        try:
+            # Check file exists and is readable
+            if not template_file.exists():
+                return False
+
+            # Parse JSON content
+            content = template_file.read_text()
+            template_data = json.loads(content)
+
+            # Check required fields in metadata section (per agent schema)
+            metadata = template_data.get("metadata", {})
+            required_fields = ["name", "description"]
+            for field in required_fields:
+                if field not in metadata:
+                    self.logger.warning(
+                        f"Template {template_file.name} missing required field in metadata: {field}"
+                    )
+                    return False
+
+            # Validate agent ID format (Claude Code requirements)
+            # Use agent_id for validation, not the display name
+            agent_id = template_data.get("agent_id", "")
+            if not self._is_valid_agent_name(agent_id):
+                self.logger.warning(
+                    f"Invalid agent ID format in {template_file.name}: {agent_id}"
+                )
+                return False
+
+            return True
+
+        except json.JSONDecodeError:
+            self.logger.error(f"Invalid JSON in template: {template_file.name}")
+            return False
+        except Exception as e:
+            self.logger.error(
+                f"Template validation failed for {template_file.name}: {e}"
+            )
+            return False
+
+    def _is_valid_agent_name(self, agent_name: str) -> bool:
+        """
+        Validate agent name format according to Claude Code requirements.
+
+        Args:
+            agent_name: Agent name to validate
+
+        Returns:
+            True if name is valid, False otherwise
+        """
+        import re
+
+        # Claude Code requires lowercase letters, numbers, and hyphens only
+        # Must start with letter, no consecutive hyphens, no trailing hyphens
+        pattern = r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+
+        return bool(re.match(pattern, agent_name))
+
+    def get_discovery_stats(self) -> Dict[str, Any]:
+        """
+        Get statistics about agent discovery.
+
+        Returns:
+            Dictionary with discovery statistics
+        """
+        stats = {
+            "total_templates": 0,
+            "valid_templates": 0,
+            "invalid_templates": 0,
+            "categories": {},
+            "templates_directory": str(self.templates_dir),
+            "directory_exists": self.templates_dir.exists(),
+        }
+
+        if not self.templates_dir.exists():
+            return stats
+
+        # Count template files
+        template_files = list(self.templates_dir.glob("*.json"))
+        stats["total_templates"] = len(template_files)
+
+        # Validate each template
+        valid_count = 0
+        for template_file in template_files:
+            if self._validate_template_file(template_file):
+                valid_count += 1
+
+        stats["valid_templates"] = valid_count
+        stats["invalid_templates"] = stats["total_templates"] - valid_count
+
+        # Get category distribution
+        stats["categories"] = self.get_agent_categories()
+
+        return stats

claude_mpm/services/agents/deployment/agent_environment_manager.py

@@ -0,0 +1,293 @@
+"""Agent Environment Manager Service
+
+This service handles environment configuration for Claude agent discovery and execution.
+Manages environment variables, paths, and runtime configuration.
+
+Extracted from AgentDeploymentService as part of the refactoring to improve
+maintainability and testability.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logging_config import get_logger
+
+
+class AgentEnvironmentManager:
+    """Service for managing Claude agent environment configuration.
+
+    This service handles:
+    - Setting Claude environment variables
+    - Managing agent discovery paths
+    - Configuring runtime parameters
+    - Environment validation and verification
+    """
+
+    def __init__(self):
+        """Initialize the environment manager."""
+        self.logger = get_logger(__name__)
+
+    def set_claude_environment(
+        self, config_dir: Optional[Path] = None
+    ) -> Dict[str, str]:
+        """
+        Set Claude environment variables for agent discovery.
+
+        This configures the environment so Claude can discover and use deployed agents.
+        Essential for proper agent functionality in Claude Code.
+
+        Args:
+            config_dir: Claude configuration directory (default: .claude/)
+
+        Returns:
+            Dictionary of environment variables that were set
+        """
+        if not config_dir:
+            config_dir = Path.cwd() / ".claude"
+
+        # Ensure config directory exists
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Set environment variables for Claude agent discovery
+        env_vars = {
+            "CLAUDE_CONFIG_DIR": str(config_dir.absolute()),
+            "CLAUDE_MAX_PARALLEL_SUBAGENTS": "3",  # Reasonable default
+            "CLAUDE_TIMEOUT": "300",  # 5 minutes default timeout
+        }
+
+        # Apply environment variables
+        for key, value in env_vars.items():
+            os.environ[key] = value
+            self.logger.debug(f"Set environment variable: {key}={value}")
+
+        self.logger.info(
+            f"Claude environment configured for agent discovery in {config_dir}"
+        )
+        return env_vars
+
+    def get_current_environment(self) -> Dict[str, str]:
+        """
+        Get current Claude-related environment variables.
+
+        Returns:
+            Dictionary of current Claude environment variables
+        """
+        claude_env_vars = {}
+
+        # Check for Claude-specific environment variables
+        claude_prefixes = ["CLAUDE_", "ANTHROPIC_"]
+
+        for key, value in os.environ.items():
+            if any(key.startswith(prefix) for prefix in claude_prefixes):
+                claude_env_vars[key] = value
+
+        return claude_env_vars
+
+    def validate_environment(self, config_dir: Optional[Path] = None) -> Dict[str, Any]:
+        """
+        Validate the current Claude environment configuration.
+
+        Args:
+            config_dir: Claude configuration directory to validate
+
+        Returns:
+            Dictionary with validation results
+        """
+        if not config_dir:
+            config_dir = Path.cwd() / ".claude"
+
+        validation_results = {
+            "valid": True,
+            "warnings": [],
+            "errors": [],
+            "config_dir_exists": False,
+            "agents_dir_exists": False,
+            "environment_variables": {},
+            "recommendations": [],
+        }
+
+        # Check if config directory exists
+        if config_dir.exists():
+            validation_results["config_dir_exists"] = True
+            self.logger.debug(f"Config directory exists: {config_dir}")
+        else:
+            validation_results["valid"] = False
+            validation_results["errors"].append(
+                f"Config directory does not exist: {config_dir}"
+            )
+
+        # Check if agents directory exists
+        agents_dir = config_dir / "agents"
+        if agents_dir.exists():
+            validation_results["agents_dir_exists"] = True
+            self.logger.debug(f"Agents directory exists: {agents_dir}")
+        else:
+            validation_results["warnings"].append(
+                f"Agents directory does not exist: {agents_dir}"
+            )
+
+        # Check environment variables
+        current_env = self.get_current_environment()
+        validation_results["environment_variables"] = current_env
+
+        # Validate required environment variables
+        required_vars = ["CLAUDE_CONFIG_DIR"]
+        for var in required_vars:
+            if var not in current_env:
+                validation_results["warnings"].append(
+                    f"Missing environment variable: {var}"
+                )
+                validation_results["recommendations"].append(
+                    f"Set {var} to point to your Claude config directory"
+                )
+
+        # Check if CLAUDE_CONFIG_DIR points to the right place
+        if "CLAUDE_CONFIG_DIR" in current_env:
+            env_config_dir = Path(current_env["CLAUDE_CONFIG_DIR"])
+            if env_config_dir != config_dir.absolute():
+                validation_results["warnings"].append(
+                    f"CLAUDE_CONFIG_DIR ({env_config_dir}) doesn't match expected path ({config_dir.absolute()})"
+                )
+
+        # Performance recommendations
+        if "CLAUDE_MAX_PARALLEL_SUBAGENTS" not in current_env:
+            validation_results["recommendations"].append(
+                "Consider setting CLAUDE_MAX_PARALLEL_SUBAGENTS for better performance"
+            )
+
+        if "CLAUDE_TIMEOUT" not in current_env:
+            validation_results["recommendations"].append(
+                "Consider setting CLAUDE_TIMEOUT to prevent long-running operations"
+            )
+
+        return validation_results
+
+    def setup_development_environment(
+        self, config_dir: Optional[Path] = None
+    ) -> Dict[str, Any]:
+        """
+        Set up a complete development environment for Claude agents.
+
+        Args:
+            config_dir: Claude configuration directory
+
+        Returns:
+            Dictionary with setup results
+        """
+        if not config_dir:
+            config_dir = Path.cwd() / ".claude"
+
+        setup_results = {
+            "success": True,
+            "created_directories": [],
+            "set_environment_variables": {},
+            "errors": [],
+        }
+
+        try:
+            # Create necessary directories
+            directories_to_create = [
+                config_dir,
+                config_dir / "agents",
+                config_dir / "logs",
+                config_dir / "cache",
+            ]
+
+            for directory in directories_to_create:
+                if not directory.exists():
+                    directory.mkdir(parents=True, exist_ok=True)
+                    setup_results["created_directories"].append(str(directory))
+                    self.logger.info(f"Created directory: {directory}")
+
+            # Set up environment variables
+            env_vars = self.set_claude_environment(config_dir)
+            setup_results["set_environment_variables"] = env_vars
+
+            # Create a basic .gitignore for the config directory
+            gitignore_path = config_dir / ".gitignore"
+            if not gitignore_path.exists():
+                gitignore_content = """# Claude configuration files
+logs/
+cache/
+*.log
+*.tmp
+
+# Keep agents directory but ignore specific files if needed
+# agents/
+"""
+                gitignore_path.write_text(gitignore_content)
+                self.logger.info(f"Created .gitignore: {gitignore_path}")
+
+        except Exception as e:
+            setup_results["success"] = False
+            setup_results["errors"].append(str(e))
+            self.logger.error(f"Failed to set up development environment: {e}")
+
+        return setup_results
+
+    def get_environment_info(self) -> Dict[str, Any]:
+        """
+        Get comprehensive information about the current environment.
+
+        Returns:
+            Dictionary with environment information
+        """
+        current_env = self.get_current_environment()
+
+        info = {
+            "claude_environment_variables": current_env,
+            "python_path": os.environ.get("PYTHONPATH", "Not set"),
+            "current_working_directory": str(Path.cwd()),
+            "user_home_directory": str(Path.home()),
+            "claude_config_locations": self._find_claude_config_locations(),
+        }
+
+        return info
+
+    def cleanup_environment(self) -> Dict[str, Any]:
+        """
+        Clean up Claude environment variables.
+
+        Returns:
+            Dictionary with cleanup results
+        """
+        cleanup_results = {"removed_variables": [], "errors": []}
+
+        try:
+            # Remove Claude-specific environment variables
+            claude_vars = [
+                key for key in os.environ.keys() if key.startswith("CLAUDE_")
+            ]
+
+            for var in claude_vars:
+                if var in os.environ:
+                    del os.environ[var]
+                    cleanup_results["removed_variables"].append(var)
+                    self.logger.debug(f"Removed environment variable: {var}")
+
+            self.logger.info(
+                f"Cleaned up {len(cleanup_results['removed_variables'])} environment variables"
+            )
+
+        except Exception as e:
+            cleanup_results["errors"].append(str(e))
+            self.logger.error(f"Error during environment cleanup: {e}")
+
+        return cleanup_results
+
+    def _find_claude_config_locations(self) -> list:
+        """Find potential Claude configuration directories."""
+        potential_locations = [
+            Path.cwd() / ".claude",
+            Path.home() / ".claude",
+            Path.home() / ".config" / "claude",
+        ]
+
+        existing_locations = []
+        for location in potential_locations:
+            if location.exists():
+                existing_locations.append(str(location))
+
+        return existing_locations