claude-mpm 4.0.28__py3-none-any.whl → 4.0.30__py3-none-any.whl

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -36,7 +36,7 @@ try:
 except ImportError:
     # Fallback values if constants module not available
     class NetworkConfig:
-        SOCKETIO_PORT_RANGE = (8080, 8099)
+        SOCKETIO_PORT_RANGE = (8765, 8785)
         RECONNECTION_DELAY = 0.5
         SOCKET_WAIT_TIMEOUT = 1.0
 

claude_mpm/scripts/mcp_server.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""MCP Server launcher script for Claude Desktop.
+"""MCP Server launcher script for Claude Code.
 
-This script launches the MCP gateway server for Claude Desktop integration.
+This script launches the MCP gateway server for Claude Code integration.
 It handles proper Python path setup and error reporting to stderr.
 """
 

claude_mpm/services/agents/agent_builder.py

@@ -0,0 +1,455 @@
+"""Agent Builder Service for programmatic agent creation and management.
+
+This service provides comprehensive agent lifecycle management including:
+- Template-based agent generation
+- Agent variant creation with inheritance
+- Configuration validation and sanitization
+- PM instruction customization
+- Integration with deployment services
+"""
+
+import json
+import logging
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from claude_mpm.core.exceptions import AgentDeploymentError
+from claude_mpm.core.logging_config import get_logger
+
+
+class AgentBuilderService:
+    """Service for building and managing agent configurations."""
+    
+    # Valid agent models
+    VALID_MODELS = ["sonnet", "opus", "haiku"]
+    
+    # Valid tool choices
+    VALID_TOOL_CHOICES = ["auto", "required", "any", "none"]
+    
+    # Agent categories
+    AGENT_CATEGORIES = [
+        "engineering", "qa", "documentation", "ops", 
+        "research", "security", "system", "utility"
+    ]
+    
+    def __init__(self, templates_dir: Optional[Path] = None):
+        """Initialize the Agent Builder Service.
+        
+        Args:
+            templates_dir: Path to agent templates directory
+        """
+        self.logger = get_logger(__name__)
+        self.templates_dir = templates_dir or Path(__file__).parent.parent.parent / "agents" / "templates"
+        self._template_cache = {}
+        
+    def create_agent(
+        self,
+        agent_id: str,
+        name: str,
+        description: str,
+        model: str = "sonnet",
+        tool_choice: str = "auto",
+        instructions: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        base_template: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Create a new agent configuration.
+        
+        Args:
+            agent_id: Unique identifier for the agent
+            name: Display name for the agent
+            description: Agent purpose and capabilities
+            model: LLM model to use (sonnet/opus/haiku)
+            tool_choice: Tool selection strategy
+            instructions: Markdown instructions content
+            metadata: Additional agent metadata
+            base_template: Optional base template to extend
+            
+        Returns:
+            Complete agent configuration dictionary
+            
+        Raises:
+            AgentDeploymentError: If validation fails
+        """
+        # Validate inputs
+        self._validate_agent_id(agent_id)
+        self._validate_model(model)
+        self._validate_tool_choice(tool_choice)
+        
+        # Start with base template if provided
+        if base_template:
+            config = self._load_template(base_template)
+            config["id"] = agent_id  # Override ID
+        else:
+            config = {}
+            
+        # Build agent configuration
+        config.update({
+            "id": agent_id,
+            "name": name,
+            "prompt": f"{agent_id}.md",
+            "model": model,
+            "tool_choice": tool_choice
+        })
+        
+        # Build metadata
+        agent_metadata = {
+            "description": description,
+            "version": "1.0.0",
+            "created": datetime.now().isoformat(),
+            "author": "Agent Manager",
+            "category": "custom"
+        }
+        
+        if metadata:
+            agent_metadata.update(metadata)
+            
+        config["metadata"] = agent_metadata
+        
+        # Generate instructions if not provided
+        if instructions is None:
+            instructions = self._generate_default_instructions(agent_id, name, description)
+            
+        return config, instructions
+        
+    def create_variant(
+        self,
+        base_agent_id: str,
+        variant_id: str,
+        variant_name: str,
+        modifications: Dict[str, Any],
+        instructions_append: Optional[str] = None
+    ) -> Tuple[Dict[str, Any], str]:
+        """Create an agent variant based on an existing agent.
+        
+        Args:
+            base_agent_id: ID of the base agent to extend
+            variant_id: Unique ID for the variant
+            variant_name: Display name for the variant
+            modifications: Configuration changes for the variant
+            instructions_append: Additional instructions to append
+            
+        Returns:
+            Tuple of (variant configuration, variant instructions)
+            
+        Raises:
+            AgentDeploymentError: If base agent not found or validation fails
+        """
+        # Load base agent
+        base_config = self._load_template(base_agent_id)
+        base_instructions = self._load_instructions(base_agent_id)
+        
+        # Validate variant ID
+        self._validate_agent_id(variant_id)
+        
+        # Create variant configuration
+        variant_config = base_config.copy()
+        variant_config["id"] = variant_id
+        variant_config["name"] = variant_name
+        variant_config["prompt"] = f"{variant_id}.md"
+        
+        # Apply modifications
+        for key, value in modifications.items():
+            if key in ["model", "tool_choice"]:
+                if key == "model":
+                    self._validate_model(value)
+                elif key == "tool_choice":
+                    self._validate_tool_choice(value)
+            variant_config[key] = value
+            
+        # Update metadata
+        if "metadata" not in variant_config:
+            variant_config["metadata"] = {}
+            
+        variant_config["metadata"].update({
+            "base_agent": base_agent_id,
+            "variant": True,
+            "variant_created": datetime.now().isoformat()
+        })
+        
+        # Build variant instructions
+        variant_instructions = f"# {variant_name} (Variant of {base_config.get('name', base_agent_id)})\n\n"
+        variant_instructions += base_instructions
+        
+        if instructions_append:
+            variant_instructions += f"\n\n## Variant-Specific Instructions\n\n{instructions_append}"
+            
+        return variant_config, variant_instructions
+        
+    def validate_configuration(self, config: Dict[str, Any]) -> List[str]:
+        """Validate an agent configuration.
+        
+        Args:
+            config: Agent configuration to validate
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        # Required fields
+        required_fields = ["id", "name", "prompt", "model"]
+        for field in required_fields:
+            if field not in config:
+                errors.append(f"Missing required field: {field}")
+                
+        # Validate ID
+        if "id" in config:
+            try:
+                self._validate_agent_id(config["id"])
+            except AgentDeploymentError as e:
+                errors.append(str(e))
+                
+        # Validate model
+        if "model" in config:
+            try:
+                self._validate_model(config["model"])
+            except AgentDeploymentError as e:
+                errors.append(str(e))
+                
+        # Validate tool_choice
+        if "tool_choice" in config:
+            try:
+                self._validate_tool_choice(config["tool_choice"])
+            except AgentDeploymentError as e:
+                errors.append(str(e))
+                
+        # Validate metadata
+        if "metadata" in config:
+            if not isinstance(config["metadata"], dict):
+                errors.append("Metadata must be a dictionary")
+                
+        return errors
+        
+    def generate_pm_instructions(
+        self,
+        delegation_patterns: Optional[List[str]] = None,
+        workflow_overrides: Optional[Dict[str, str]] = None,
+        custom_rules: Optional[List[str]] = None
+    ) -> str:
+        """Generate customized PM instructions.
+        
+        Args:
+            delegation_patterns: Custom delegation patterns
+            workflow_overrides: Workflow sequence modifications
+            custom_rules: Additional PM rules
+            
+        Returns:
+            Customized PM instructions markdown
+        """
+        instructions = "# Custom PM Instructions\n\n"
+        
+        if delegation_patterns:
+            instructions += "## Custom Delegation Patterns\n\n"
+            for pattern in delegation_patterns:
+                instructions += f"- {pattern}\n"
+            instructions += "\n"
+            
+        if workflow_overrides:
+            instructions += "## Workflow Overrides\n\n"
+            for workflow, override in workflow_overrides.items():
+                instructions += f"### {workflow}\n{override}\n\n"
+                
+        if custom_rules:
+            instructions += "## Additional Rules\n\n"
+            for rule in custom_rules:
+                instructions += f"- {rule}\n"
+                
+        return instructions
+        
+    def list_available_templates(self) -> List[Dict[str, Any]]:
+        """List all available agent templates.
+        
+        Returns:
+            List of template metadata dictionaries
+        """
+        templates = []
+        
+        if not self.templates_dir.exists():
+            return templates
+            
+        for template_file in self.templates_dir.glob("*.json"):
+            try:
+                with open(template_file, 'r') as f:
+                    config = json.load(f)
+                    
+                # Use filename stem as ID if not specified in config
+                template_id = config.get("id") or template_file.stem
+                    
+                templates.append({
+                    "id": template_id,
+                    "name": config.get("name", template_id),
+                    "description": config.get("metadata", {}).get("description"),
+                    "category": config.get("metadata", {}).get("category"),
+                    "version": config.get("metadata", {}).get("version"),
+                    "file": str(template_file)
+                })
+            except Exception as e:
+                self.logger.warning(f"Failed to load template {template_file}: {e}")
+                
+        return templates
+        
+    def _validate_agent_id(self, agent_id: str) -> None:
+        """Validate agent ID format.
+        
+        Args:
+            agent_id: Agent ID to validate
+            
+        Raises:
+            AgentDeploymentError: If ID is invalid
+        """
+        if not agent_id:
+            raise AgentDeploymentError("Agent ID cannot be empty")
+            
+        if len(agent_id) > 50:
+            raise AgentDeploymentError("Agent ID must be 50 characters or less")
+            
+        if not re.match(r'^[a-z0-9-]+$', agent_id):
+            raise AgentDeploymentError(
+                "Agent ID must contain only lowercase letters, numbers, and hyphens"
+            )
+            
+    def _validate_model(self, model: str) -> None:
+        """Validate model selection.
+        
+        Args:
+            model: Model to validate
+            
+        Raises:
+            AgentDeploymentError: If model is invalid
+        """
+        if model not in self.VALID_MODELS:
+            raise AgentDeploymentError(
+                f"Invalid model '{model}'. Must be one of: {', '.join(self.VALID_MODELS)}"
+            )
+            
+    def _validate_tool_choice(self, tool_choice: str) -> None:
+        """Validate tool choice setting.
+        
+        Args:
+            tool_choice: Tool choice to validate
+            
+        Raises:
+            AgentDeploymentError: If tool choice is invalid
+        """
+        if tool_choice not in self.VALID_TOOL_CHOICES:
+            raise AgentDeploymentError(
+                f"Invalid tool_choice '{tool_choice}'. Must be one of: {', '.join(self.VALID_TOOL_CHOICES)}"
+            )
+            
+    def _load_template(self, template_id: str) -> Dict[str, Any]:
+        """Load an agent template.
+        
+        Args:
+            template_id: Template ID to load
+            
+        Returns:
+            Template configuration dictionary
+            
+        Raises:
+            AgentDeploymentError: If template not found
+        """
+        if template_id in self._template_cache:
+            return self._template_cache[template_id].copy()
+            
+        template_file = self.templates_dir / f"{template_id}.json"
+        
+        if not template_file.exists():
+            raise AgentDeploymentError(f"Template '{template_id}' not found")
+            
+        try:
+            with open(template_file, 'r') as f:
+                config = json.load(f)
+                self._template_cache[template_id] = config
+                return config.copy()
+        except Exception as e:
+            raise AgentDeploymentError(f"Failed to load template '{template_id}': {e}")
+            
+    def _load_instructions(self, agent_id: str) -> str:
+        """Load agent instructions.
+        
+        Args:
+            agent_id: Agent ID to load instructions for
+            
+        Returns:
+            Instructions markdown content
+            
+        Raises:
+            AgentDeploymentError: If instructions not found
+        """
+        # Try multiple possible locations
+        possible_files = [
+            self.templates_dir / f"{agent_id}.md",
+            self.templates_dir / f"{agent_id}_instructions.md",
+            self.templates_dir / f"{agent_id}-instructions.md"
+        ]
+        
+        for instructions_file in possible_files:
+            if instructions_file.exists():
+                try:
+                    with open(instructions_file, 'r') as f:
+                        return f.read()
+                except Exception as e:
+                    self.logger.warning(f"Failed to read instructions from {instructions_file}: {e}")
+                    
+        # If no instructions found, return empty
+        return ""
+        
+    def _generate_default_instructions(self, agent_id: str, name: str, description: str) -> str:
+        """Generate default agent instructions.
+        
+        Args:
+            agent_id: Agent identifier
+            name: Agent display name
+            description: Agent description
+            
+        Returns:
+            Default instructions markdown
+        """
+        return f"""# {name}
+
+## Core Identity
+
+You are {name}, a specialized agent in the Claude MPM framework.
+
+## Purpose
+
+{description}
+
+## Responsibilities
+
+- Primary focus on your specialized domain
+- Collaborate with other agents as needed
+- Follow Claude MPM framework conventions
+- Maintain high quality standards
+
+## Operating Principles
+
+1. **Expertise**: Apply deep knowledge in your domain
+2. **Efficiency**: Complete tasks effectively and quickly
+3. **Communication**: Provide clear, actionable responses
+4. **Collaboration**: Work well with other agents
+5. **Quality**: Maintain high standards in all outputs
+
+## Output Format
+
+Provide structured responses with:
+- Clear summaries of actions taken
+- Detailed results when appropriate
+- Any issues or blockers encountered
+- Recommendations for next steps
+
+## Integration
+
+- Follow framework patterns and conventions
+- Use appropriate tools for the task
+- Coordinate with PM for complex workflows
+- Report completion status clearly
+
+---
+
+*Agent ID: {agent_id}*
+*Generated by Agent Manager*
+"""

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -60,17 +60,23 @@ class AgentTemplateBuilder:
             raise
 
         # Extract tools from template with fallback
+        # Handle both dict and list formats for capabilities (backward compatibility)
+        capabilities = template_data.get("capabilities", {})
+        capabilities_tools = capabilities.get("tools") if isinstance(capabilities, dict) else None
+        
         tools = (
             template_data.get("tools")
-            or template_data.get("capabilities", {}).get("tools")
+            or capabilities_tools
             or template_data.get("configuration_fields", {}).get("tools")
             or ["Read", "Write", "Edit", "Grep", "Glob", "LS"]  # Default fallback
         )
 
         # Extract model from template with fallback
+        capabilities_model = capabilities.get("model") if isinstance(capabilities, dict) else None
+        
         model = (
             template_data.get("model")
-            or template_data.get("capabilities", {}).get("model")
+            or capabilities_model
             or template_data.get("configuration_fields", {}).get("model")
             or "sonnet"  # Default fallback
         )
@@ -132,7 +138,8 @@ class AgentTemplateBuilder:
         # Extract custom metadata fields
         agent_version = template_data.get("agent_version", "1.0.0")
         agent_type = template_data.get("agent_type", "general")
-        model_type = template_data.get("capabilities", {}).get("model", "sonnet")
+        # Use the capabilities_model we already extracted earlier
+        model_type = capabilities_model or "sonnet"
 
         # Map our model types to Claude Code format
         if model_type in ["opus", "sonnet", "haiku"]:

claude_mpm/services/agents/deployment/agent_validator.py

@@ -324,6 +324,7 @@ class AgentValidator:
         agent_info = {
             "file": agent_file.name,
             "name": agent_file.stem,
+            "path": str(agent_file),
             "description": "No description",
             "version": "unknown",
         }

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -363,6 +363,10 @@ class MultiSourceAgentDeploymentService:
                     source_match = re.search(r'^source:\s*(.+)$', deployed_content, re.MULTILINE)
                     if source_match:
                         deployed_source = source_match.group(1).strip()
+                
+                # If source is still unknown, try to infer it from deployment context
+                if deployed_source == "unknown":
+                    deployed_source = self._infer_agent_source_from_context(agent_name, deployed_agents_dir)
             except Exception as e:
                 self.logger.warning(f"Error reading deployed agent '{agent_name}': {e}")
                 comparison_results["needs_update"].append(agent_name)
@@ -438,4 +442,68 @@ class MultiSourceAgentDeploymentService:
                     f"{downgrade['template_version']}"
                 )
         
-        return comparison_results
+        return comparison_results
+    
+    def _infer_agent_source_from_context(self, agent_name: str, deployed_agents_dir: Path) -> str:
+        """Infer the source of a deployed agent when source metadata is missing.
+        
+        This method attempts to determine the agent source based on:
+        1. Deployment context (development vs pipx)
+        2. Agent naming patterns
+        3. Known system agents
+        
+        Args:
+            agent_name: Name of the agent
+            deployed_agents_dir: Directory where agent is deployed
+            
+        Returns:
+            Inferred source string (system/project/user)
+        """
+        # List of known system agents that ship with claude-mpm
+        system_agents = {
+            "pm", "engineer", "qa", "research", "documentation", "ops", 
+            "security", "web-ui", "api-qa", "version-control"
+        }
+        
+        # If this is a known system agent, it's from system
+        if agent_name in system_agents:
+            return "system"
+        
+        # Check deployment context
+        from ....core.unified_paths import get_path_manager
+        path_manager = get_path_manager()
+        
+        # If deployed_agents_dir is under user home/.claude/agents, check context
+        user_claude_dir = Path.home() / ".claude" / "agents"
+        if deployed_agents_dir == user_claude_dir:
+            # Check if we're in development mode
+            try:
+                from ....core.unified_paths import DeploymentContext, PathContext
+                deployment_context = PathContext.detect_deployment_context()
+                
+                if deployment_context in (DeploymentContext.DEVELOPMENT, DeploymentContext.EDITABLE_INSTALL):
+                    # In development mode, unknown agents are likely system agents being tested
+                    return "system"
+                elif deployment_context == DeploymentContext.PIPX_INSTALL:
+                    # In pipx mode, unknown agents could be system agents
+                    # Check if agent follows system naming patterns
+                    if agent_name.count('-') <= 2 and len(agent_name) <= 20:
+                        return "system"
+            except Exception:
+                pass
+        
+        # Check if deployed to project-specific directory
+        try:
+            project_root = path_manager.project_root
+            if str(deployed_agents_dir).startswith(str(project_root)):
+                return "project"
+        except Exception:
+            pass
+        
+        # Default inference based on naming patterns
+        # System agents typically have simple names
+        if '-' not in agent_name or agent_name.count('-') <= 1:
+            return "system"
+        
+        # Complex names are more likely to be user/project agents
+        return "user"

claude_mpm/services/diagnostics/__init__.py

@@ -0,0 +1,18 @@
+"""
+Diagnostic service for claude-mpm health checks.
+
+WHY: Provide a comprehensive diagnostic tool to help users identify and fix
+common issues with their claude-mpm installation and configuration.
+
+DESIGN DECISIONS:
+- Modular check system for easy extension
+- Interface-based design for consistency
+- Clear status levels (ok, warning, error)
+- Actionable fix suggestions
+"""
+
+from .diagnostic_runner import DiagnosticRunner
+from .doctor_reporter import DoctorReporter
+from .models import DiagnosticResult, DiagnosticStatus
+
+__all__ = ["DiagnosticRunner", "DoctorReporter", "DiagnosticResult", "DiagnosticStatus"]

claude_mpm/services/diagnostics/checks/__init__.py

@@ -0,0 +1,30 @@
+"""
+Diagnostic checks for claude-mpm doctor command.
+
+WHY: Modular checks allow for easy extension and testing of individual
+diagnostic components.
+"""
+
+from .agent_check import AgentCheck
+from .base_check import BaseDiagnosticCheck
+from .claude_desktop_check import ClaudeDesktopCheck
+from .common_issues_check import CommonIssuesCheck
+from .configuration_check import ConfigurationCheck
+from .filesystem_check import FilesystemCheck
+from .installation_check import InstallationCheck
+from .mcp_check import MCPCheck
+from .monitor_check import MonitorCheck
+from .startup_log_check import StartupLogCheck
+
+__all__ = [
+    "BaseDiagnosticCheck",
+    "InstallationCheck",
+    "ConfigurationCheck",
+    "ClaudeDesktopCheck",
+    "AgentCheck",
+    "MCPCheck",
+    "MonitorCheck",
+    "FilesystemCheck",
+    "CommonIssuesCheck",
+    "StartupLogCheck",
+]