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

claude_mpm/services/agent_capabilities_service.py

@@ -0,0 +1,271 @@
+from pathlib import Path
+
+"""Agent capabilities service for discovering and generating agent capability descriptions.
+
+This service handles:
+1. Agent discovery from multiple directories (system, user, project)
+2. Agent categorization based on content and naming
+3. Generation of capability descriptions for Claude
+4. Fallback capabilities when no agents are found
+
+Extracted from ClaudeRunner to follow Single Responsibility Principle.
+"""
+
+import logging
+from typing import Dict, Optional
+
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.logging_config import get_logger
+from claude_mpm.services.core.interfaces import AgentCapabilitiesInterface
+
+
+class AgentCapabilitiesService(BaseService, AgentCapabilitiesInterface):
+    """Service for discovering and generating agent capability descriptions."""
+
+    def __init__(self):
+        """Initialize the agent capabilities service."""
+        super().__init__(name="agent_capabilities_service")
+
+    async def _initialize(self) -> None:
+        """Initialize the service. No special initialization needed."""
+        pass
+
+    async def _cleanup(self) -> None:
+        """Cleanup service resources. No cleanup needed."""
+        pass
+
+    def generate_agent_capabilities(self, agent_type: str = "general") -> str:
+        """Generate formatted agent capabilities for Claude.
+
+        Args:
+            agent_type: Type of agent to generate capabilities for
+
+        Returns:
+            Formatted capabilities string for Claude consumption
+        """
+        # Delegate to the existing implementation
+        return self.generate_deployed_agent_capabilities()
+
+    def generate_deployed_agent_capabilities(self) -> str:
+        """Generate agent capabilities from deployed agents following Claude Code's hierarchy.
+
+        Follows the agent precedence order:
+        1. Project agents (.claude/agents/) - highest priority
+        2. User agents (~/.config/claude/agents/) - middle priority
+        3. System agents (claude-desktop installation) - lowest priority
+
+        Project agents override user/system agents with the same ID.
+
+        Returns:
+            str: Formatted agent capabilities description
+        """
+        try:
+            # Track discovered agents by ID to handle overrides
+            discovered_agents = {}
+
+            # 1. First read system agents (lowest priority)
+            system_agents_dirs = [
+                Path.home()
+                / "Library"
+                / "Application Support"
+                / "Claude"
+                / "agents",  # macOS
+                Path.home() / ".config" / "claude" / "agents",  # Linux
+                Path.home() / "AppData" / "Roaming" / "Claude" / "agents",  # Windows
+            ]
+
+            for system_dir in system_agents_dirs:
+                if system_dir.exists():
+                    self._discover_agents_from_dir(
+                        system_dir, discovered_agents, "system"
+                    )
+                    break
+
+            # 2. Then read user agents (middle priority, overrides system)
+            user_agents_dir = Path.home() / ".config" / "claude" / "agents"
+            if user_agents_dir.exists():
+                self._discover_agents_from_dir(
+                    user_agents_dir, discovered_agents, "user"
+                )
+
+            # 3. Finally read project agents (highest priority, overrides all)
+            project_agents_dir = Path.cwd() / ".claude" / "agents"
+            if project_agents_dir.exists():
+                self._discover_agents_from_dir(
+                    project_agents_dir, discovered_agents, "project"
+                )
+
+            if not discovered_agents:
+                self.logger.warning("No agents found in any tier")
+                return self._get_fallback_capabilities()
+
+            # Build capabilities section from discovered agents using list and join for better performance
+            section_parts = [
+                "\n## Available Agent Capabilities\n\n",
+                "You have the following specialized agents available for delegation:\n\n",
+            ]
+
+            # Group agents by category
+            agents_by_category = {}
+            for agent_id, agent_info in discovered_agents.items():
+                category = agent_info["category"]
+                if category not in agents_by_category:
+                    agents_by_category[category] = []
+                agents_by_category[category].append(agent_info)
+
+            # Output agents by category
+            for category in sorted(agents_by_category.keys()):
+                section_parts.append(f"\n### {category} Agents\n")
+                for agent in sorted(
+                    agents_by_category[category], key=lambda x: x["name"]
+                ):
+                    tier_indicator = (
+                        f" [{agent['tier']}]" if agent["tier"] != "project" else ""
+                    )
+                    section_parts.append(
+                        f"- **{agent['name']}** (`{agent['id']}`{tier_indicator}): {agent['description']}\n"
+                    )
+
+            # Add summary
+            section_parts.append(
+                f"\n**Total Available Agents**: {len(discovered_agents)}\n"
+            )
+
+            # Show tier distribution
+            tier_counts = {}
+            for agent in discovered_agents.values():
+                tier = agent["tier"]
+                tier_counts[tier] = tier_counts.get(tier, 0) + 1
+
+            if len(tier_counts) > 1:
+                section_parts.append("**Agent Sources**: ")
+                tier_summary = []
+                for tier in ["project", "user", "system"]:
+                    if tier in tier_counts:
+                        tier_summary.append(f"{tier_counts[tier]} {tier}")
+                section_parts.append(", ".join(tier_summary) + "\n")
+
+            section_parts.append(
+                "Use the agent ID in parentheses when delegating tasks via the Task tool.\n"
+            )
+
+            # Join all parts for final section
+            section = "".join(section_parts)
+
+            self.logger.info(
+                f"Generated capabilities for {len(discovered_agents)} agents "
+                + f"(project: {tier_counts.get('project', 0)}, "
+                + f"user: {tier_counts.get('user', 0)}, "
+                + f"system: {tier_counts.get('system', 0)})"
+            )
+            return section
+
+        except Exception as e:
+            self.logger.error(f"Failed to generate deployed agent capabilities: {e}")
+            return self._get_fallback_capabilities()
+
+    def _discover_agents_from_dir(
+        self, agents_dir: Path, discovered_agents: dict, tier: str
+    ):
+        """Discover agents from a specific directory and add/override in discovered_agents.
+
+        Args:
+            agents_dir: Directory to search for agent .md files
+            discovered_agents: Dictionary to update with discovered agents
+            tier: The tier this directory represents (system/user/project)
+        """
+        if not agents_dir.exists():
+            return
+
+        agent_files = list(agents_dir.glob("*.md"))
+        for agent_file in sorted(agent_files):
+            try:
+                agent_id = agent_file.stem
+
+                # Read agent content
+                content = agent_file.read_text(encoding="utf-8")
+
+                # Extract name and description from content
+                lines = content.split("\n")
+                name = agent_id.replace("-", " ").replace("_", " ").title()
+                description = f"Specialized agent for {agent_id.replace('-', ' ')}"
+
+                # Try to extract better name and description from content
+                for line in lines:
+                    line = line.strip()
+                    if line.startswith("# "):
+                        name = line[2:].strip()
+                    elif line.startswith("Description:"):
+                        description = line[12:].strip()
+                    elif "description" in line.lower() and ":" in line:
+                        description = line.split(":", 1)[1].strip()
+
+                # Categorize the agent
+                category = self._categorize_agent(agent_id, content)
+
+                # Add/override in discovered agents (higher tier overrides lower)
+                discovered_agents[agent_id] = {
+                    "id": agent_id,
+                    "name": name,
+                    "description": description,
+                    "category": category,
+                    "tier": tier,
+                    "path": str(agent_file),
+                }
+
+                self.logger.debug(f"Discovered {tier} agent: {agent_id} ({category})")
+
+            except Exception as e:
+                self.logger.debug(f"Could not parse agent {agent_file}: {e}")
+                continue
+
+    def _categorize_agent(self, agent_id: str, content: str) -> str:
+        """Categorize an agent based on its ID and content."""
+        agent_id_lower = agent_id.lower()
+        content_lower = content.lower()
+
+        if "engineer" in agent_id_lower or "engineering" in content_lower:
+            return "Development"
+        elif "research" in agent_id_lower or "research" in content_lower:
+            return "Research"
+        elif (
+            "qa" in agent_id_lower
+            or "test" in agent_id_lower
+            or "quality" in content_lower
+        ):
+            return "Quality Assurance"
+        elif "doc" in agent_id_lower or "documentation" in content_lower:
+            return "Documentation"
+        elif "security" in agent_id_lower or "security" in content_lower:
+            return "Security"
+        elif "data" in agent_id_lower or "database" in content_lower:
+            return "Data"
+        elif (
+            "ops" in agent_id_lower
+            or "deploy" in agent_id_lower
+            or "operations" in content_lower
+        ):
+            return "Operations"
+        elif "git" in agent_id_lower or "version" in content_lower:
+            return "Version Control"
+        else:
+            return "General"
+
+    def _get_fallback_capabilities(self) -> str:
+        """Return fallback agent capabilities when deployed agents can't be read."""
+        return """
+## Available Agent Capabilities
+
+You have the following specialized agents available for delegation:
+
+- **Engineer Agent**: Code implementation and development
+- **Research Agent**: Investigation and analysis
+- **QA Agent**: Testing and quality assurance
+- **Documentation Agent**: Documentation creation and maintenance
+- **Security Agent**: Security analysis and protection
+- **Data Engineer Agent**: Data management and pipelines
+- **Ops Agent**: Deployment and operations
+- **Version Control Agent**: Git operations and version management
+
+Use these agents to delegate specialized work via the Task tool.
+"""

claude_mpm/services/agents/__init__.py

@@ -1,52 +1,43 @@
 """Agent services module - hierarchical organization of agent-related services."""
 
 # Registry exports
-from .registry.agent_registry import (
-    AgentRegistry,
-    AgentMetadata,
-    AgentTier,
-    AgentType,
-)
-from .registry.deployed_agent_discovery import DeployedAgentDiscovery
-from .registry.modification_tracker import (
-    AgentModificationTracker,
-    ModificationType,
-    ModificationTier,
-    AgentModification,
-    ModificationHistory,
-)
-
-# Loading exports
-from .loading.framework_agent_loader import FrameworkAgentLoader
-from .loading.agent_profile_loader import AgentProfileLoader
-from .loading.base_agent_manager import BaseAgentManager
-
 # Deployment exports
 from .deployment.agent_deployment import AgentDeploymentService
 from .deployment.agent_lifecycle_manager import (
     AgentLifecycleManager,
-    LifecycleState,
-    LifecycleOperation,
     AgentLifecycleRecord,
+    LifecycleOperation,
     LifecycleOperationResult,
+    LifecycleState,
 )
 from .deployment.agent_versioning import AgentVersionManager
+from .loading.agent_profile_loader import AgentProfileLoader
+from .loading.base_agent_manager import BaseAgentManager
+
+# Loading exports
+from .loading.framework_agent_loader import FrameworkAgentLoader
+from .management.agent_capabilities_generator import AgentCapabilitiesGenerator
+
+# Management exports
+from .management.agent_management_service import AgentManager
 
 # Memory exports
-from .memory.agent_memory_manager import (
-    AgentMemoryManager,
-    get_memory_manager,
-)
+from .memory.agent_memory_manager import AgentMemoryManager, get_memory_manager
 from .memory.agent_persistence_service import (
     AgentPersistenceService,
-    PersistenceStrategy,
     PersistenceOperation,
     PersistenceRecord,
+    PersistenceStrategy,
+)
+from .registry import AgentMetadata, AgentRegistry, AgentTier, AgentType
+from .registry.deployed_agent_discovery import DeployedAgentDiscovery
+from .registry.modification_tracker import (
+    AgentModification,
+    AgentModificationTracker,
+    ModificationHistory,
+    ModificationTier,
+    ModificationType,
 )
-
-# Management exports
-from .management.agent_management_service import AgentManager
-from .management.agent_capabilities_generator import AgentCapabilitiesGenerator
 
 __all__ = [
     # Registry
@@ -82,4 +73,4 @@ __all__ = [
     # Management
     "AgentManager",
     "AgentCapabilitiesGenerator",
-]
+]

claude_mpm/services/agents/deployment/__init__.py

@@ -3,10 +3,10 @@
 from .agent_deployment import AgentDeploymentService
 from .agent_lifecycle_manager import (
     AgentLifecycleManager,
-    LifecycleState,
-    LifecycleOperation,
     AgentLifecycleRecord,
+    LifecycleOperation,
     LifecycleOperationResult,
+    LifecycleState,
 )
 from .agent_versioning import AgentVersionManager
 
@@ -18,4 +18,4 @@ __all__ = [
     "AgentLifecycleRecord",
     "LifecycleOperationResult",
     "AgentVersionManager",
-]
+]

claude_mpm/services/agents/deployment/agent_config_provider.py

@@ -0,0 +1,310 @@
+"""Agent configuration provider for deployment service.
+
+This module provides agent-specific configurations and tools for different agent types.
+Extracted from AgentDeploymentService to reduce complexity and improve maintainability.
+"""
+
+from typing import Any, Dict, List
+
+from claude_mpm.core.constants import ResourceLimits, SystemLimits, TimeoutConfig
+
+
+class AgentConfigProvider:
+    """Provides agent-specific configurations and tools."""
+
+    @staticmethod
+    def get_agent_tools(agent_name: str, metadata: Dict[str, Any]) -> List[str]:
+        """
+        Get appropriate tools for an agent based on its type.
+
+        Args:
+            agent_name: Name of the agent
+            metadata: Agent metadata
+
+        Returns:
+            List of tool names
+        """
+        # Base tools all agents should have
+        base_tools = [
+            "Read",
+            "Write",
+            "Edit",
+            "MultiEdit",
+            "Grep",
+            "Glob",
+            "LS",
+            "TodoWrite",
+        ]
+
+        # Agent-specific tools
+        agent_tools = {
+            "engineer": base_tools + ["Bash", "WebSearch", "WebFetch"],
+            "qa": base_tools + ["Bash", "WebSearch"],
+            "documentation": base_tools + ["WebSearch", "WebFetch"],
+            "research": base_tools + ["WebSearch", "WebFetch", "Bash"],
+            "security": base_tools + ["Bash", "WebSearch", "Grep"],
+            "ops": base_tools + ["Bash", "WebSearch"],
+            "data_engineer": base_tools + ["Bash", "WebSearch"],
+            "version_control": base_tools + ["Bash"],
+        }
+
+        # Return specific tools or default set
+        return agent_tools.get(agent_name, base_tools + ["Bash", "WebSearch"])
+
+    @staticmethod
+    def get_agent_specific_config(agent_name: str) -> Dict[str, Any]:
+        """
+        Get agent-specific configuration based on agent type.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Dictionary of agent-specific configuration
+        """
+        # Base configuration all agents share
+        base_config = {
+            "timeout": TimeoutConfig.DEFAULT_TIMEOUT,
+            "max_tokens": SystemLimits.MAX_TOKEN_LIMIT,
+            "memory_limit": ResourceLimits.STANDARD_MEMORY_RANGE[
+                0
+            ],  # Use lower bound of standard memory
+            "cpu_limit": ResourceLimits.STANDARD_CPU_RANGE[
+                1
+            ],  # Use upper bound of standard CPU
+            "network_access": True,
+        }
+
+        # Agent-specific configurations
+        configs = AgentConfigProvider._get_agent_configs(base_config)
+
+        # Return the specific config or a default
+        return configs.get(
+            agent_name, AgentConfigProvider._get_default_config(agent_name, base_config)
+        )
+
+    @staticmethod
+    def _get_agent_configs(base_config: Dict[str, Any]) -> Dict[str, Dict[str, Any]]:
+        """Get all agent-specific configurations."""
+        return {
+            "engineer": {
+                **base_config,
+                "description": "Code implementation, development, and inline documentation",
+                "tags": '["engineer", "development", "coding", "implementation"]',
+                "tools": '["Read", "Write", "Edit", "MultiEdit", "Bash", "Grep", "Glob", "LS", "WebSearch", "TodoWrite"]',
+                "temperature": 0.2,
+                "when_to_use": [
+                    "Code implementation needed",
+                    "Bug fixes required",
+                    "Refactoring tasks",
+                ],
+                "specialized_knowledge": [
+                    "Programming best practices",
+                    "Design patterns",
+                    "Code optimization",
+                ],
+                "unique_capabilities": [
+                    "Write production code",
+                    "Debug complex issues",
+                    "Refactor codebases",
+                ],
+                "primary_role": "Code implementation and development",
+                "specializations": '["coding", "debugging", "refactoring", "optimization"]',
+                "authority": "ALL code implementation decisions",
+            },
+            "qa": {
+                **base_config,
+                "description": "Quality assurance, testing, and validation",
+                "tags": '["qa", "testing", "quality", "validation"]',
+                "tools": '["Read", "Write", "Edit", "Bash", "Grep", "Glob", "LS", "TodoWrite"]',
+                "temperature": 0.1,
+                "when_to_use": [
+                    "Testing needed",
+                    "Quality validation",
+                    "Test coverage analysis",
+                ],
+                "specialized_knowledge": [
+                    "Testing methodologies",
+                    "Quality metrics",
+                    "Test automation",
+                ],
+                "unique_capabilities": [
+                    "Execute test suites",
+                    "Identify edge cases",
+                    "Validate quality",
+                ],
+                "primary_role": "Testing and quality assurance",
+                "specializations": '["testing", "validation", "quality-assurance", "coverage"]',
+                "authority": "ALL testing and quality decisions",
+            },
+            "documentation": {
+                **base_config,
+                "description": "Documentation creation, maintenance, and changelog generation",
+                "tags": '["documentation", "writing", "changelog", "docs"]',
+                "tools": '["Read", "Write", "Edit", "MultiEdit", "Grep", "Glob", "LS", "WebSearch", "TodoWrite"]',
+                "temperature": 0.3,
+                "when_to_use": [
+                    "Documentation updates needed",
+                    "Changelog generation",
+                    "README updates",
+                ],
+                "specialized_knowledge": [
+                    "Technical writing",
+                    "Documentation standards",
+                    "Semantic versioning",
+                ],
+                "unique_capabilities": [
+                    "Create clear documentation",
+                    "Generate changelogs",
+                    "Maintain docs",
+                ],
+                "primary_role": "Documentation and technical writing",
+                "specializations": '["technical-writing", "changelog", "api-docs", "guides"]',
+                "authority": "ALL documentation decisions",
+            },
+            "research": {
+                **base_config,
+                "description": "Technical research, analysis, and investigation",
+                "tags": '["research", "analysis", "investigation", "evaluation"]',
+                "tools": '["Read", "Grep", "Glob", "LS", "WebSearch", "WebFetch", "TodoWrite"]',
+                "temperature": 0.4,
+                "when_to_use": [
+                    "Technical research needed",
+                    "Solution evaluation",
+                    "Best practices investigation",
+                ],
+                "specialized_knowledge": [
+                    "Research methodologies",
+                    "Technical analysis",
+                    "Evaluation frameworks",
+                ],
+                "unique_capabilities": [
+                    "Deep investigation",
+                    "Comparative analysis",
+                    "Evidence-based recommendations",
+                ],
+                "primary_role": "Research and technical analysis",
+                "specializations": '["investigation", "analysis", "evaluation", "recommendations"]',
+                "authority": "ALL research decisions",
+            },
+            "security": {
+                **base_config,
+                "description": "Security analysis, vulnerability assessment, and protection",
+                "tags": '["security", "vulnerability", "protection", "audit"]',
+                "tools": '["Read", "Grep", "Glob", "LS", "Bash", "WebSearch", "TodoWrite"]',
+                "temperature": 0.1,
+                "when_to_use": [
+                    "Security review needed",
+                    "Vulnerability assessment",
+                    "Security audit",
+                ],
+                "specialized_knowledge": [
+                    "Security best practices",
+                    "OWASP guidelines",
+                    "Vulnerability patterns",
+                ],
+                "unique_capabilities": [
+                    "Identify vulnerabilities",
+                    "Security auditing",
+                    "Threat modeling",
+                ],
+                "primary_role": "Security analysis and protection",
+                "specializations": '["vulnerability-assessment", "security-audit", "threat-modeling", "protection"]',
+                "authority": "ALL security decisions",
+            },
+            "ops": {
+                **base_config,
+                "description": "Deployment, operations, and infrastructure management",
+                "tags": '["ops", "deployment", "infrastructure", "devops"]',
+                "tools": '["Read", "Write", "Edit", "Bash", "Grep", "Glob", "LS", "TodoWrite"]',
+                "temperature": 0.2,
+                "when_to_use": [
+                    "Deployment configuration",
+                    "Infrastructure setup",
+                    "CI/CD pipeline work",
+                ],
+                "specialized_knowledge": [
+                    "Deployment best practices",
+                    "Infrastructure as code",
+                    "CI/CD",
+                ],
+                "unique_capabilities": [
+                    "Configure deployments",
+                    "Manage infrastructure",
+                    "Automate operations",
+                ],
+                "primary_role": "Operations and deployment management",
+                "specializations": '["deployment", "infrastructure", "automation", "monitoring"]',
+                "authority": "ALL operations decisions",
+            },
+            "data_engineer": {
+                **base_config,
+                "description": "Data pipeline management and AI API integrations",
+                "tags": '["data", "pipeline", "etl", "ai-integration"]',
+                "tools": '["Read", "Write", "Edit", "Bash", "Grep", "Glob", "LS", "WebSearch", "TodoWrite"]',
+                "temperature": 0.2,
+                "when_to_use": [
+                    "Data pipeline setup",
+                    "Database design",
+                    "AI API integration",
+                ],
+                "specialized_knowledge": [
+                    "Data architectures",
+                    "ETL processes",
+                    "AI/ML APIs",
+                ],
+                "unique_capabilities": [
+                    "Design data schemas",
+                    "Build pipelines",
+                    "Integrate AI services",
+                ],
+                "primary_role": "Data engineering and AI integration",
+                "specializations": '["data-pipelines", "etl", "database", "ai-integration"]',
+                "authority": "ALL data engineering decisions",
+            },
+            "version_control": {
+                **base_config,
+                "description": "Git operations, version management, and release coordination",
+                "tags": '["git", "version-control", "release", "branching"]',
+                "tools": '["Read", "Bash", "Grep", "Glob", "LS", "TodoWrite"]',
+                "temperature": 0.1,
+                "network_access": False,  # Git operations are local
+                "when_to_use": [
+                    "Git operations needed",
+                    "Version bumping",
+                    "Release management",
+                ],
+                "specialized_knowledge": [
+                    "Git workflows",
+                    "Semantic versioning",
+                    "Release processes",
+                ],
+                "unique_capabilities": [
+                    "Complex git operations",
+                    "Version management",
+                    "Release coordination",
+                ],
+                "primary_role": "Version control and release management",
+                "specializations": '["git", "versioning", "branching", "releases"]',
+                "authority": "ALL version control decisions",
+            },
+        }
+
+    @staticmethod
+    def _get_default_config(
+        agent_name: str, base_config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Get default configuration for unknown agent types."""
+        return {
+            **base_config,
+            "description": f"{agent_name.title()} agent for specialized tasks",
+            "tags": f'["{agent_name}", "specialized", "mpm"]',
+            "tools": '["Read", "Write", "Edit", "Grep", "Glob", "LS", "TodoWrite"]',
+            "temperature": 0.3,
+            "when_to_use": [f"When {agent_name} expertise is needed"],
+            "specialized_knowledge": [f"{agent_name.title()} domain knowledge"],
+            "unique_capabilities": [f"{agent_name.title()} specialized operations"],
+            "primary_role": f"{agent_name.title()} operations",
+            "specializations": f'["{agent_name}"]',
+            "authority": f"ALL {agent_name} decisions",
+        }