claude-mpm 4.3.6__py3-none-any.whl → 4.3.12__py3-none-any.whl

claude_mpm/cli/startup_logging.py

@@ -18,7 +18,7 @@ import logging
 import shutil
 import subprocess
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, Optional
 
@@ -339,14 +339,27 @@ class StartupStatusLogger:
 
     def _check_socketio_dependencies(self) -> Dict[str, Any]:
         """Check if Socket.IO dependencies are available."""
+        import importlib.util
+
         result = {"available": False, "error": None}
 
         try:
-            import aiohttp
-            import engineio
-            import socketio
+            # Check for socketio dependencies without importing them
+            aiohttp_spec = importlib.util.find_spec("aiohttp")
+            engineio_spec = importlib.util.find_spec("engineio")
+            socketio_spec = importlib.util.find_spec("socketio")
 
-            result["available"] = True
+            if aiohttp_spec and engineio_spec and socketio_spec:
+                result["available"] = True
+            else:
+                missing = []
+                if not aiohttp_spec:
+                    missing.append("aiohttp")
+                if not engineio_spec:
+                    missing.append("engineio")
+                if not socketio_spec:
+                    missing.append("socketio")
+                result["error"] = f"Missing dependencies: {', '.join(missing)}"
         except ImportError as e:
             result["error"] = f"Missing dependencies: {e}"
         except Exception as e:
@@ -493,7 +506,7 @@ def setup_startup_logging(project_root: Optional[Path] = None) -> Path:
     log_dir.mkdir(parents=True, exist_ok=True)
 
     # Generate timestamp for log file
-    timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d-%H-%M-%S")
     log_file = log_dir / f"startup-{timestamp}.log"
 
     # Create file handler with detailed formatting
@@ -516,7 +529,7 @@ def setup_startup_logging(project_root: Optional[Path] = None) -> Path:
     # Log startup header
     logger = get_logger("startup")
     logger.info("=" * 60)
-    logger.info(f"Claude MPM Startup - {datetime.now().isoformat()}")
+    logger.info(f"Claude MPM Startup - {datetime.now(timezone.utc).isoformat()}")
     logger.info(f"Log file: {log_file}")
     logger.info("=" * 60)
 

claude_mpm/constants.py

@@ -140,6 +140,7 @@ class MCPCommands(str, Enum):
     TEST = "test"
     CONFIG = "config"
     SERVER = "server"
+    EXTERNAL = "external"
 
 
 class TicketCommands(str, Enum):

claude_mpm/core/unified_agent_registry.py

@@ -460,6 +460,13 @@ class UnifiedAgentRegistry:
             if agent_format == AgentFormat.JSON:
                 data = json.loads(content)
 
+                # Ensure data is a dictionary, not a list
+                if not isinstance(data, dict):
+                    logger.warning(
+                        f"Invalid JSON structure in {file_path}: expected object, got {type(data).__name__}"
+                    )
+                    return "", []
+
                 # Handle local agent JSON templates with metadata structure
                 if "metadata" in data:
                     metadata = data["metadata"]

claude_mpm/hooks/instruction_reinforcement.py

@@ -0,0 +1,295 @@
+"""
+Instruction Reinforcement Hook for PM Delegation Compliance
+
+This hook monitors PM behavior for delegation violations and provides
+escalating warnings when the PM attempts to implement instead of delegate.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class ViolationType(Enum):
+    """Types of PM delegation violations"""
+
+    EDIT_ATTEMPT = "Edit/Write/MultiEdit"
+    BASH_IMPLEMENTATION = "Bash for implementation"
+    FILE_CREATION = "Direct file creation"
+    TEST_EXECUTION = "Test execution"
+    DEPLOYMENT = "Deployment operation"
+    CODE_WRITING = "Code writing"
+
+
+@dataclass
+class Violation:
+    """Record of a delegation violation"""
+
+    violation_type: ViolationType
+    context: str
+    timestamp: float
+    severity_level: int
+
+
+class InstructionReinforcementHook:
+    """
+    Monitors PM messages for delegation violations and provides corrective feedback.
+
+    Circuit breaker pattern implementation to prevent PM from implementing
+    instead of delegating work to appropriate agents.
+    """
+
+    def __init__(self):
+        self.violation_count = 0
+        self.violations: List[Violation] = []
+
+        # Patterns that indicate PM is attempting forbidden actions
+        self.forbidden_patterns = [
+            # Direct implementation language - EXPANDED
+            (
+                r"I'll\s+(fix|create|write|implement|code|build|update|generate|modify|set\s+up|configure|optimize|rewrite|run|test|deploy|push|analyze|review|setup)",
+                ViolationType.CODE_WRITING,
+            ),
+            (
+                r"I'm\s+(fix|create|write|implement|code|build|update|generate|modify)",
+                ViolationType.CODE_WRITING,
+            ),
+            (
+                r"Let\s+me\s+(edit|write|modify|create|update|fix|run|execute|commit|refactor|configure|set\s+up|review)",
+                ViolationType.EDIT_ATTEMPT,
+            ),
+            (
+                r"I\s+will\s+(implement|code|build|create|write|update|fix)",
+                ViolationType.CODE_WRITING,
+            ),
+            (
+                r"I'm\s+(going\s+to|about\s+to)\s+(fix|create|write|implement|update|modify)",
+                ViolationType.CODE_WRITING,
+            ),
+            # Common honeypot phrases
+            (
+                r"Here's\s+(the|my|an?)\s+(implementation|code|SQL|query|solution|analysis|fix)",
+                ViolationType.CODE_WRITING,
+            ),
+            (
+                r"The\s+(query|code|implementation|solution)\s+(would\s+be|is)",
+                ViolationType.CODE_WRITING,
+            ),
+            (r"I\s+(found|identified)\s+(these\s+)?issues", ViolationType.CODE_WRITING),
+            # Deployment and setup patterns
+            (
+                r"Setting\s+up\s+(the\s+)?(authentication|containers|environment|docker)",
+                ViolationType.DEPLOYMENT,
+            ),
+            (r"Deploying\s+(to|the)", ViolationType.DEPLOYMENT),
+            (r"I'll\s+(deploy|push|host|launch)", ViolationType.DEPLOYMENT),
+            # Tool usage patterns - EXPANDED
+            (r"Using\s+(Edit|Write|MultiEdit)\s+tool", ViolationType.EDIT_ATTEMPT),
+            (r"<invoke\s+name=\"(Edit|Write|MultiEdit)\"", ViolationType.EDIT_ATTEMPT),
+            (
+                r"Running\s+(bash\s+command|git\s+commit|npm|yarn|python|node|go|tests|pytest)",
+                ViolationType.BASH_IMPLEMENTATION,
+            ),
+            (r"Executing\s+(tests|test\s+suite|pytest)", ViolationType.TEST_EXECUTION),
+            # Testing patterns - EXPANDED
+            (
+                r"(Testing|I'll\s+test|Let\s+me\s+test)\s+(the\s+)?(payment|API|endpoint)",
+                ViolationType.TEST_EXECUTION,
+            ),
+            (
+                r"I'll\s+(run|execute|verify)\s+(the\s+)?(tests|test\s+suite|endpoint)",
+                ViolationType.TEST_EXECUTION,
+            ),
+            (r"pytest|npm\s+test|yarn\s+test|go\s+test", ViolationType.TEST_EXECUTION),
+            # File operation patterns - EXPANDED
+            (
+                r"Creating\s+(new\s+|a\s+|the\s+)?(file|YAML|README|workflow)",
+                ViolationType.FILE_CREATION,
+            ),
+            (r"Writing\s+to\s+file", ViolationType.FILE_CREATION),
+            (
+                r"Updating\s+(the\s+)?(code|component|queries)",
+                ViolationType.CODE_WRITING,
+            ),
+            (
+                r"I'll\s+(update|modify)\s+(the\s+)?(component|code|React)",
+                ViolationType.CODE_WRITING,
+            ),
+        ]
+
+        # Patterns for correct delegation behavior - EXPANDED
+        self.delegation_patterns = [
+            r"delegat(e|ing)\s+(to|this)",
+            r"Task\s+tool",
+            r"(asking|request|have|use)\s+\w+\s+agent",
+            r"requesting\s+\w+\s+to",
+            r"will\s+(have|ask|request)\s+\w+\s+agent",
+            r"I'll\s+(have|ask|request|delegate)",
+            r"the\s+\w+\s+agent\s+(will|can|should)",
+        ]
+
+    def detect_violation_intent(
+        self, message: str
+    ) -> Optional[Tuple[ViolationType, str]]:
+        """
+        Check message for patterns indicating PM violation intent.
+
+        Args:
+            message: The PM's message to analyze
+
+        Returns:
+            Tuple of (ViolationType, matched_text) if violation detected, None otherwise
+        """
+        message_lower = message.lower()
+
+        # Check for forbidden patterns
+        for pattern, violation_type in self.forbidden_patterns:
+            match = re.search(pattern, message_lower, re.IGNORECASE)
+            if match:
+                # Check if this is actually a delegation (false positive check)
+                is_delegation = any(
+                    re.search(
+                        del_pattern,
+                        message_lower[max(0, match.start() - 50) : match.end() + 50],
+                    )
+                    for del_pattern in self.delegation_patterns
+                )
+
+                if not is_delegation:
+                    return (violation_type, match.group(0))
+
+        return None
+
+    def escalate_warning(self) -> str:
+        """
+        Generate escalating warning message based on violation count.
+
+        Returns:
+            Warning message with appropriate severity
+        """
+        if self.violation_count == 1:
+            return (
+                "⚠️ DELEGATION REMINDER: PM must delegate ALL implementation work.\n"
+                "Use the Task tool to delegate to the appropriate agent."
+            )
+        if self.violation_count == 2:
+            return (
+                "🚨 DELEGATION WARNING: Critical PM violation detected!\n"
+                "You MUST delegate implementation work. Do NOT use Edit/Write/Bash for implementation.\n"
+                "Next violation will result in session failure."
+            )
+        if self.violation_count == 3:
+            return (
+                "❌ CRITICAL DELEGATION FAILURE: Multiple PM violations detected.\n"
+                "PM has repeatedly attempted to implement instead of delegate.\n"
+                "Session integrity compromised. All work must be delegated to agents."
+            )
+        return (
+            f"❌❌❌ SEVERE VIOLATION (Count: {self.violation_count}): PM continues to violate delegation rules.\n"
+            "MANDATORY: Use Task tool to delegate ALL implementation to appropriate agents.\n"
+            "Current session may need to be terminated and restarted."
+        )
+
+    def check_message(self, message: str) -> Optional[Dict[str, any]]:
+        """
+        Check a PM message for violations and return feedback if needed.
+
+        Args:
+            message: The PM's message to check
+
+        Returns:
+            Dictionary with violation details and correction, or None if compliant
+        """
+        violation_result = self.detect_violation_intent(message)
+
+        if violation_result:
+            violation_type, context = violation_result
+            self.violation_count += 1
+
+            # Record the violation
+            import time
+
+            violation = Violation(
+                violation_type=violation_type,
+                context=context,
+                timestamp=time.time(),
+                severity_level=min(self.violation_count, 4),
+            )
+            self.violations.append(violation)
+
+            # Generate corrective feedback
+            warning = self.escalate_warning()
+
+            # Determine which agent should handle this
+            agent_mapping = {
+                ViolationType.EDIT_ATTEMPT: "Engineer",
+                ViolationType.CODE_WRITING: "Engineer",
+                ViolationType.BASH_IMPLEMENTATION: "Engineer or Ops",
+                ViolationType.FILE_CREATION: "Engineer or Documentation",
+                ViolationType.TEST_EXECUTION: "QA",
+                ViolationType.DEPLOYMENT: "Ops",
+            }
+
+            suggested_agent = agent_mapping.get(violation_type, "appropriate agent")
+
+            # Clean up context for task suggestion
+            clean_context = (
+                context.replace("I will ", "")
+                .replace("I'll ", "")
+                .replace("Let me ", "")
+            )
+
+            return {
+                "violation_detected": True,
+                "violation_count": self.violation_count,
+                "violation_type": violation_type.value,
+                "context": context,
+                "warning": warning,
+                "correction": f"MUST delegate to {suggested_agent} using Task tool",
+                "suggested_task": f"Task: Please {clean_context}",
+                "severity": min(self.violation_count, 4),
+            }
+
+        return None
+
+    def get_violation_summary(self) -> Dict[str, any]:
+        """
+        Get a summary of all violations in the session.
+
+        Returns:
+            Dictionary with violation statistics and details
+        """
+        if not self.violations:
+            return {
+                "total_violations": 0,
+                "status": "COMPLIANT",
+                "message": "No PM delegation violations detected",
+            }
+
+        violation_types = {}
+        for v in self.violations:
+            vtype = v.violation_type.value
+            violation_types[vtype] = violation_types.get(vtype, 0) + 1
+
+        status = "WARNING" if self.violation_count < 3 else "CRITICAL"
+
+        return {
+            "total_violations": self.violation_count,
+            "status": status,
+            "violation_types": violation_types,
+            "most_recent": self.violations[-1].context if self.violations else None,
+            "recommendation": (
+                "Review PM delegation training"
+                if self.violation_count > 2
+                else "Continue monitoring"
+            ),
+        }
+
+    def reset(self):
+        """Reset violation tracking for a new session"""
+        self.violation_count = 0
+        self.violations = []

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -776,16 +776,6 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                 agent_sources=agent_sources,
             )
 
-            # Log version upgrades and source changes
-            if comparison_results.get("version_upgrades"):
-                self.logger.info(
-                    f"Version upgrades available for {len(comparison_results['version_upgrades'])} agents"
-                )
-            if comparison_results.get("source_changes"):
-                self.logger.info(
-                    f"Source changes for {len(comparison_results['source_changes'])} agents"
-                )
-
             # Filter agents based on comparison results (unless force_rebuild is set)
             if not force_rebuild:
                 # Only deploy agents that need updates or are new
@@ -804,11 +794,36 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                     for name, path in agents_to_deploy.items()
                     if name in agents_needing_update
                 }
+
+                # Only log upgrade messages if we're actually going to deploy them
+                if filtered_agents and comparison_results.get("version_upgrades"):
+                    # Filter upgrades to only those actually being deployed
+                    deployed_upgrades = [
+                        upgrade for upgrade in comparison_results["version_upgrades"]
+                        if upgrade["name"] in filtered_agents
+                    ]
+
+                    if deployed_upgrades:
+                        self.logger.info(
+                            f"Deploying {len(deployed_upgrades)} agent upgrade(s):"
+                        )
+                        for upgrade in deployed_upgrades:
+                            self.logger.info(
+                                f"  Upgrading: {upgrade['name']} "
+                                f"{upgrade['deployed_version']} -> {upgrade['new_version']} "
+                                f"(from {upgrade['source']})"
+                            )
+
                 agents_to_deploy = filtered_agents
 
-                self.logger.info(
-                    f"Filtered to {len(agents_to_deploy)} agents needing deployment"
-                )
+                if agents_to_deploy:
+                    self.logger.info(
+                        f"Deploying {len(agents_to_deploy)} agents that need updates"
+                    )
+                else:
+                    self.logger.debug(
+                        f"All {len(comparison_results.get('up_to_date', []))} agents are up to date"
+                    )
 
         # Convert to list of Path objects
         template_files = list(agents_to_deploy.values())

claude_mpm/services/agents/deployment/agent_discovery_service.py

@@ -216,25 +216,35 @@ class AgentDiscoveryService:
             metadata = template_data.get("metadata", {})
             capabilities = template_data.get("capabilities", {})
 
+            # Handle capabilities as either dict or list
+            if isinstance(capabilities, list):
+                # If capabilities is a list (like in php-engineer.json), treat it as capabilities list
+                tools_list = template_data.get("tools", [])  # Look for tools at root level
+                model_value = template_data.get("model", "sonnet")
+            else:
+                # If capabilities is a dict, extract tools and model from it
+                tools_list = capabilities.get("tools", [])
+                model_value = capabilities.get("model", "sonnet")
+
             agent_info = {
                 "name": metadata.get("name", template_file.stem),
-                "description": metadata.get("description", "No description available"),
+                "description": metadata.get("description", template_data.get("description", "No description available")),
                 "type": template_data.get(
-                    "agent_type", metadata.get("category", "agent")
+                    "agent_type", metadata.get("category", template_data.get("category", "agent"))
                 ),  # Extract agent type
                 "version": template_data.get(
                     "agent_version",
                     template_data.get("version", metadata.get("version", "1.0.0")),
                 ),
-                "tools": capabilities.get("tools", []),
+                "tools": tools_list,
                 "specializations": metadata.get(
-                    "tags", []
-                ),  # Use tags as specializations
+                    "tags", template_data.get("tags", [])
+                ),  # Use tags as specializations, fallback to root-level tags
                 "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"),
+                "model": model_value,
                 "author": metadata.get("author", "unknown"),
             }
 

claude_mpm/services/agents/deployment/deployment_wrapper.py

@@ -69,3 +69,62 @@ 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 open(agent_path) 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:
+                                try:
+                                    metadata = yaml.safe_load(parts[1])
+                                except yaml.YAMLError:
+                                    pass
+
+                        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/multi_source_deployment_service.py

@@ -742,18 +742,20 @@ class MultiSourceAgentDeploymentService:
 
         self.logger.info(f"Version comparison complete: {', '.join(summary_parts)}")
 
+        # Don't log upgrades here - let the caller decide when to log
+        # This prevents repeated upgrade messages on every startup
         if comparison_results["version_upgrades"]:
             for upgrade in comparison_results["version_upgrades"]:
-                self.logger.info(
-                    f"  Upgrade: {upgrade['name']} "
+                self.logger.debug(
+                    f"  Upgrade available: {upgrade['name']} "
                     f"{upgrade['deployed_version']} -> {upgrade['new_version']} "
                     f"(from {upgrade['source']})"
                 )
 
         if comparison_results["source_changes"]:
             for change in comparison_results["source_changes"]:
-                self.logger.info(
-                    f"  Source change: {change['name']} "
+                self.logger.debug(
+                    f"  Source change available: {change['name']} "
                     f"from {change['from_source']} to {change['to_source']}"
                 )
 

claude_mpm/services/cli/agent_cleanup_service.py

@@ -138,6 +138,11 @@ class AgentCleanupService(IAgentCleanupService):
                 if not isinstance(result, dict):
                     result = {"success": bool(result)}
 
+                # Add success flag based on whether there were errors
+                if "success" not in result:
+                    # Consider it successful if no errors occurred
+                    result["success"] = not bool(result.get("errors"))
+
                 # Add cleaned_count for backward compatibility
                 if "cleaned_count" not in result:
                     removed_count = len(result.get("removed", []))