claude-mpm 5.0.2__py3-none-any.whl → 5.4.3__py3-none-any.whl

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -115,6 +115,9 @@ class ConnectionManagerService:
         - Fallback: HTTP POST for reliability when direct connection fails
         - Eliminates duplicate events from multiple emission paths
         """
+        # Extract tool_call_id from data if present for correlation
+        tool_call_id = data.get("tool_call_id")
+
         # Create event data for normalization
         raw_event = {
             "type": "hook",
@@ -123,6 +126,7 @@ class ConnectionManagerService:
             "data": data,
             "source": "claude_hooks",  # Identify the source
             "session_id": data.get("sessionId"),  # Include session if available
+            "correlation_id": tool_call_id,  # Set from tool_call_id for event correlation
         }
 
         # Normalize the event using EventNormalizer for consistent schema

claude_mpm/models/agent_definition.py

@@ -103,6 +103,10 @@ class AgentMetadata:
     author: Optional[str] = None
     tags: List[str] = field(default_factory=list)
     specializations: List[str] = field(default_factory=list)
+    # NEW: Collection metadata for enhanced agent matching
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repository
+    canonical_id: Optional[str] = None  # Format: collection_id:agent_id
 
     def increment_serial_version(self) -> None:
         """Increment the patch version number.
@@ -181,6 +185,9 @@ class AgentDefinition:
                 "author": self.metadata.author,
                 "tags": self.metadata.tags,
                 "specializations": self.metadata.specializations,
+                "collection_id": self.metadata.collection_id,
+                "source_path": self.metadata.source_path,
+                "canonical_id": self.metadata.canonical_id,
             },
             "primary_role": self.primary_role,
             "when_to_use": self.when_to_use,

claude_mpm/scripts/launch_monitor.py

@@ -7,6 +7,12 @@ dashboard, which includes both the Socket.IO server and web interface.
 
 WHY: Provides a simple command to start the monitoring dashboard that tracks
 Claude MPM events and agent activity in real-time.
+
+SINGLE INSTANCE ENFORCEMENT:
+- Only ONE monitor instance runs at a time on port 8765 (default)
+- If monitor already running on default port: reuse existing, open browser
+- If user specifies --port explicitly: use that port, fail if busy
+- No auto-increment port selection (prevents multiple instances)
 """
 
 import argparse
@@ -15,12 +21,36 @@ import webbrowser
 
 from claude_mpm.core.logging_config import get_logger
 from claude_mpm.services.monitor.daemon import UnifiedMonitorDaemon
-from claude_mpm.services.port_manager import PortManager
+from claude_mpm.services.monitor.daemon_manager import DaemonManager
 
 DEFAULT_PORT = 8765
 logger = get_logger(__name__)
 
 
+def check_existing_monitor(host: str, port: int) -> bool:
+    """Check if monitor is already running on the specified port.
+
+    Args:
+        host: Host to check
+        port: Port to check
+
+    Returns:
+        True if monitor is running, False otherwise
+    """
+    try:
+        import requests
+
+        response = requests.get(f"http://{host}:{port}/health", timeout=2)
+        if response.status_code == 200:
+            data = response.json()
+            # Check if it's our claude-mpm-monitor service
+            if data.get("service") == "claude-mpm-monitor":
+                return True
+    except Exception:
+        pass
+    return False
+
+
 def main():
     """Main entry point for monitor launcher."""
     parser = argparse.ArgumentParser(
@@ -30,8 +60,8 @@ def main():
     parser.add_argument(
         "--port",
         type=int,
-        default=DEFAULT_PORT,
-        help=f"Port to run on (default: {DEFAULT_PORT})",
+        default=None,  # Changed: None means use DEFAULT_PORT with single-instance check
+        help=f"Port to run on (default: {DEFAULT_PORT}). If specified, fails if port is busy.",
     )
 
     parser.add_argument(
@@ -46,20 +76,70 @@ def main():
         "--background", action="store_true", help="Run in background daemon mode"
     )
 
+    parser.add_argument(
+        "--dev",
+        action="store_true",
+        help="Enable development mode with hot reload for Svelte changes",
+    )
+
     args = parser.parse_args()
 
-    # Find available port
-    port_manager = PortManager()
-    actual_port = port_manager.find_available_port(preferred_port=args.port)
+    # Determine target port
+    user_specified_port = args.port is not None
+    target_port = args.port if user_specified_port else DEFAULT_PORT
+
+    # SINGLE INSTANCE ENFORCEMENT:
+    # Check if monitor already running on target port
+    if check_existing_monitor(args.host, target_port):
+        logger.info(f"Monitor already running at http://{args.host}:{target_port}")
 
-    if actual_port != args.port:
-        logger.info(f"Port {args.port} is in use, using port {actual_port} instead")
+        # Open browser to existing instance if requested
+        if not args.no_browser:
+            url = f"http://{args.host}:{target_port}"
+            logger.info(f"Opening browser to existing instance: {url}")
+            webbrowser.open(url)
+
+        # Success - reusing existing instance
+        return
+
+    # Port selection logic:
+    # - If user specified --port: Use that exact port, fail if busy
+    # - If no --port: Use DEFAULT_PORT (8765), fail if busy
+    # - Never auto-increment to find free port
+
+    # Create daemon manager for port checking
+    daemon_manager = DaemonManager(port=target_port, host=args.host)
+
+    if not daemon_manager._is_port_available():
+        if user_specified_port:
+            # User explicitly requested a port - fail with clear message
+            logger.error(
+                f"Port {target_port} is already in use by another service. "
+                f"Please stop the existing service or choose a different port."
+            )
+            sys.exit(1)
+        else:
+            # Default port is busy - fail with helpful message
+            logger.error(
+                f"Default port {DEFAULT_PORT} is already in use by another service. "
+                f"Please stop the existing service with 'claude-mpm monitor stop' "
+                f"or specify a different port with --port."
+            )
+            sys.exit(1)
 
     # Start the monitor daemon
-    logger.info(f"Starting Claude MPM monitor on {args.host}:{actual_port}")
+    if args.dev:
+        logger.info(
+            f"Starting Claude MPM monitor on {args.host}:{target_port} (DEV MODE - hot reload enabled)"
+        )
+    else:
+        logger.info(f"Starting Claude MPM monitor on {args.host}:{target_port}")
 
     daemon = UnifiedMonitorDaemon(
-        host=args.host, port=actual_port, daemon_mode=args.background
+        host=args.host,
+        port=target_port,
+        daemon_mode=args.background,
+        enable_hot_reload=args.dev,
     )
 
     success = daemon.start()
@@ -67,14 +147,14 @@ def main():
     if success:
         # Open browser if requested
         if not args.no_browser:
-            url = f"http://{args.host}:{actual_port}"
+            url = f"http://{args.host}:{target_port}"
             logger.info(f"Opening browser to {url}")
             webbrowser.open(url)
 
         if args.background:
-            logger.info(f"Monitor daemon started in background on port {actual_port}")
+            logger.info(f"Monitor daemon started in background on port {target_port}")
         else:
-            logger.info(f"Monitor running on port {actual_port}")
+            logger.info(f"Monitor running on port {target_port}")
             logger.info("Press Ctrl+C to stop")
     else:
         logger.error("Failed to start monitor")

claude_mpm/services/agents/agent_recommendation_service.py

@@ -0,0 +1,279 @@
+"""Agent Recommendation Service
+
+WHY: Provides intelligent agent recommendations based on toolchain detection
+and always-recommended core agents. Helps users discover and install the
+most relevant agents for their project without manual selection.
+
+DESIGN DECISION: Uses toolchain analysis to map detected languages/frameworks
+to specific engineer agents, plus always includes core agents.
+
+Architecture:
+- Toolchain-based recommendations: Python → python-engineer, etc.
+- Core agents (always recommended): qa-agent, research-agent, documentation-agent,
+  ticketing, local-ops-agent, version-control, security
+- Confidence-based filtering: Only recommend high-confidence detections
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from ...services.project.toolchain_analyzer import ToolchainAnalyzerService
+
+
+class AgentRecommendationService:
+    """Service for recommending agents based on project toolchain.
+
+    WHY: Users shouldn't have to manually figure out which agents to install.
+    This service provides intelligent recommendations based on detected stack.
+
+    DESIGN DECISION: Separated from configure.py for reusability and testability.
+    Can be used by CLI, API, or future auto-configuration features.
+    """
+
+    # Core agents always included - matches ToolchainDetector.CORE_AGENTS
+    # Uses exact agent IDs from repository for consistency
+    CORE_AGENTS = {
+        "qa-agent",
+        "research-agent",
+        "documentation-agent",
+        "ticketing",
+        "local-ops-agent",
+        # Keep version-control and security as universal recommended agents
+        "version-control",
+        "security",
+    }
+
+    # Map detected languages to recommended engineer agents
+    LANGUAGE_TO_AGENTS: Dict[str, List[str]] = {
+        "python": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "javascript": [
+            "engineer/backend/javascript-engineer",
+            "engineer/data/typescript-engineer",
+        ],
+        "typescript": [
+            "engineer/data/typescript-engineer",
+            "engineer/backend/javascript-engineer",
+        ],
+        "rust": [
+            "engineer/backend/rust-engineer",
+        ],
+        "go": [
+            "engineer/backend/golang-engineer",
+        ],
+        "java": [
+            "engineer/backend/java-engineer",
+        ],
+        "dart": [
+            "engineer/mobile/dart-engineer",
+        ],
+        "php": [
+            "engineer/backend/php-engineer",
+        ],
+        "ruby": [
+            "engineer/backend/ruby-engineer",
+        ],
+        "swift": [
+            "engineer/mobile/swift-engineer",
+        ],
+        "kotlin": [
+            "engineer/mobile/kotlin-engineer",
+        ],
+    }
+
+    # Map detected frameworks to recommended agents
+    FRAMEWORK_TO_AGENTS: Dict[str, List[str]] = {
+        # Frontend frameworks
+        "react": [
+            "engineer/frontend/react-engineer",
+            "qa/web-qa",
+        ],
+        "nextjs": [
+            "engineer/frontend/nextjs-engineer",
+            "engineer/frontend/react-engineer",
+            "ops/platform/vercel-ops",
+        ],
+        "vue": [
+            "engineer/frontend/vue-engineer",
+        ],
+        "angular": [
+            "engineer/frontend/angular-engineer",
+        ],
+        # Backend frameworks
+        "fastapi": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "django": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "flask": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "express": [
+            "engineer/backend/javascript-engineer",
+            "qa/api-qa",
+        ],
+        "nest": [
+            "engineer/backend/javascript-engineer",
+            "qa/api-qa",
+        ],
+        # Mobile frameworks
+        "flutter": [
+            "engineer/mobile/dart-engineer",
+        ],
+        "react-native": [
+            "engineer/frontend/react-engineer",
+            "engineer/mobile/react-native-engineer",
+        ],
+        # Desktop frameworks
+        "tauri": [
+            "engineer/mobile/tauri-engineer",
+            "engineer/backend/rust-engineer",
+        ],
+        "electron": [
+            "engineer/backend/javascript-engineer",
+        ],
+    }
+
+    def __init__(self, toolchain_analyzer: Optional[ToolchainAnalyzerService] = None):
+        """Initialize agent recommendation service.
+
+        Args:
+            toolchain_analyzer: Optional pre-initialized toolchain analyzer.
+                               If None, creates a new instance.
+        """
+        self.toolchain_analyzer = toolchain_analyzer or ToolchainAnalyzerService()
+
+    def get_recommended_agents(
+        self,
+        project_path: Optional[str] = None,
+        confidence_threshold: float = 0.5,
+    ) -> Set[str]:
+        """Get recommended agents for a project.
+
+        Args:
+            project_path: Path to project directory. Defaults to cwd.
+            confidence_threshold: Minimum confidence for recommendations (0.0-1.0).
+                                 Only include detected components above this threshold.
+
+        Returns:
+            Set of recommended agent IDs (e.g., {"qa-agent", "research-agent", ...})
+
+        Example:
+            >>> service = AgentRecommendationService()
+            >>> recommended = service.get_recommended_agents()
+            >>> "qa-agent" in recommended
+            True
+            >>> # For Python project:
+            >>> "engineer/backend/python-engineer" in recommended
+            True
+        """
+        # Start with core agents (always recommended)
+        recommended = self.CORE_AGENTS.copy()
+
+        # Analyze project toolchain
+        if project_path is None:
+            project_path = str(Path.cwd())
+
+        try:
+            # ToolchainAnalyzerService.analyze_toolchain takes Path, not str
+            analysis = self.toolchain_analyzer.analyze_toolchain(Path(project_path))
+        except Exception as e:
+            # If analysis fails, just return core agents
+            print(f"Warning: Toolchain analysis failed: {e}")
+            return recommended
+
+        # Add language-specific agents
+        # ToolchainAnalysis has a single LanguageDetection object, not a list
+        if analysis.language_detection:
+            # Check primary language
+            primary_lang = analysis.language_detection.primary_language.lower()
+            if primary_lang in self.LANGUAGE_TO_AGENTS:
+                recommended.update(self.LANGUAGE_TO_AGENTS[primary_lang])
+
+            # Check secondary languages
+            for lang_component in analysis.language_detection.secondary_languages:
+                lang = lang_component.name.lower()
+                if lang in self.LANGUAGE_TO_AGENTS:
+                    recommended.update(self.LANGUAGE_TO_AGENTS[lang])
+
+        # Add framework-specific agents
+        for framework in analysis.frameworks:
+            fw_name = framework.name.lower()
+            if fw_name in self.FRAMEWORK_TO_AGENTS:
+                recommended.update(self.FRAMEWORK_TO_AGENTS[fw_name])
+
+        return recommended
+
+    def get_detection_summary(self, project_path: Optional[str] = None) -> Dict:
+        """Get human-readable summary of detected toolchain.
+
+        Args:
+            project_path: Path to project directory. Defaults to cwd.
+
+        Returns:
+            Dict with keys:
+            - detected_languages: List of detected language names
+            - detected_frameworks: List of detected framework names
+            - recommended_count: Number of recommended agents
+            - detection_quality: "high", "medium", "low", or "none"
+
+        Example:
+            >>> summary = service.get_detection_summary()
+            >>> summary['detected_languages']
+            ['Python', 'JavaScript']
+            >>> summary['recommended_count']
+            15
+        """
+        if project_path is None:
+            project_path = str(Path.cwd())
+
+        try:
+            analysis = self.toolchain_analyzer.analyze_toolchain(Path(project_path))
+
+            # Extract languages from LanguageDetection object
+            languages = []
+            if analysis.language_detection:
+                languages.append(analysis.language_detection.primary_language)
+                languages.extend(
+                    comp.name
+                    for comp in analysis.language_detection.secondary_languages
+                )
+
+            # Extract frameworks
+            frameworks = [fw.name for fw in analysis.frameworks]
+
+            # Get recommended agents
+            recommended = self.get_recommended_agents(project_path)
+
+            # Determine detection quality from overall_confidence
+            confidence_map = {
+                "high": "high",
+                "medium": "medium",
+                "low": "low",
+                "very_low": "low",
+            }
+            quality = confidence_map.get(
+                str(analysis.overall_confidence).lower(), "unknown"
+            )
+
+            return {
+                "detected_languages": languages,
+                "detected_frameworks": frameworks,
+                "recommended_count": len(recommended),
+                "detection_quality": quality,
+            }
+        except Exception as e:
+            # Log the error for debugging
+            print(f"Warning: Toolchain analysis failed: {e}")
+            return {
+                "detected_languages": [],
+                "detected_frameworks": [],
+                "recommended_count": len(self.CORE_AGENTS),
+                "detection_quality": "none",
+            }