claude-mpm 5.1.8__py3-none-any.whl → 5.4.22__py3-none-any.whl

claude_mpm/hooks/memory_integration_hook.py

@@ -13,6 +13,7 @@ agent outputs because:
 """
 
 import re
+from datetime import datetime
 from typing import Dict, List
 
 from claude_mpm.core.config import Config
@@ -47,6 +48,16 @@ except ImportError as e:
     SOCKETIO_AVAILABLE = False
     get_socketio_server = None
 
+# Try to import event bus with fallback handling
+try:
+    from claude_mpm.services.event_bus.event_bus import EventBus
+
+    EVENT_BUS_AVAILABLE = True
+except ImportError as e:
+    logger.debug(f"EventBus not available: {e}")
+    EVENT_BUS_AVAILABLE = False
+    EventBus = None
+
 
 class MemoryPreDelegationHook(PreDelegationHook):
     """Inject agent memory into delegation context.
@@ -83,6 +94,16 @@ class MemoryPreDelegationHook(PreDelegationHook):
             logger.info("Memory manager not available - hook will be inactive")
             self.memory_manager = None
 
+        # Initialize event bus for observability
+        if EVENT_BUS_AVAILABLE and EventBus:
+            try:
+                self.event_bus = EventBus.get_instance()
+            except Exception as e:
+                logger.debug(f"Failed to get EventBus instance: {e}")
+                self.event_bus = None
+        else:
+            self.event_bus = None
+
     def execute(self, context: HookContext) -> HookResult:
         """Add agent memory to delegation context.
 
@@ -137,7 +158,31 @@ INSTRUCTIONS: Review your memory above before proceeding. Apply learned patterns
 
                     logger.info(f"Injected memory for agent '{agent_id}'")
 
-                    # Emit Socket.IO event for memory injected
+                    # Calculate memory size for observability
+                    memory_size = len(memory_content)
+
+                    # Emit event bus event for observability
+                    if self.event_bus:
+                        try:
+                            # Determine memory source (project or user level)
+                            # This is inferred from the memory manager's behavior
+                            memory_source = (
+                                "runtime"  # Runtime loading from memory manager
+                            )
+
+                            self.event_bus.publish(
+                                "agent.memory.loaded",
+                                {
+                                    "agent_id": agent_id,
+                                    "memory_source": memory_source,
+                                    "memory_size": memory_size,
+                                    "timestamp": datetime.now(datetime.UTC).isoformat(),
+                                },
+                            )
+                        except Exception as event_error:
+                            logger.debug(f"EventBus publish failed: {event_error}")
+
+                    # Emit Socket.IO event for memory injected (legacy compatibility)
                     try:
                         socketio_server = get_socketio_server()
                         # Calculate size of injected content

claude_mpm/init.py

@@ -141,25 +141,6 @@ class ProjectInitializer:
             if not gitignore.exists():
                 gitignore.write_text("logs/\n*.log\n*.pyc\n__pycache__/\n")
 
-            # Also ensure MCP directories are in main project .gitignore
-            try:
-                from claude_mpm.services.project.project_organizer import (
-                    ProjectOrganizer,
-                )
-
-                # Check if we're in a git repository
-                if (project_root / ".git").exists():
-                    organizer = ProjectOrganizer(project_root)
-                    # This will add MCP directories and other standard patterns
-                    organizer.update_gitignore()
-                    self.logger.debug(
-                        "Updated project .gitignore with MCP and standard patterns"
-                    )
-            except Exception as e:
-                self.logger.debug(
-                    f"Could not update project gitignore with MCP patterns: {e}"
-                )
-
             # Log successful creation with details
             self.logger.info(f"Initialized project directory at {self.project_dir}")
             self.logger.debug("Created directories: agents, config, responses, logs")

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/claude-hook-handler.sh

@@ -88,18 +88,21 @@ fi
 #
 # STRATEGY:
 # This function implements a fallback chain to find Python with claude-mpm dependencies:
-# 1. Project-specific virtual environments (venv, .venv)
-# 2. Currently active virtual environment ($VIRTUAL_ENV)
-# 3. System python3 (may lack dependencies)
-# 4. System python (last resort)
+# 1. UV-managed projects (uv.lock detected) - uses "uv run python"
+# 2. pipx installations - uses pipx venv Python
+# 3. Project-specific virtual environments (venv, .venv)
+# 4. Currently active virtual environment ($VIRTUAL_ENV)
+# 5. System python3 (may lack dependencies)
+# 6. System python (last resort)
 #
 # WHY THIS APPROACH:
 # - Claude MPM requires specific packages (socketio, eventlet) not in system Python
-# - Virtual environments ensure dependency isolation and availability
+# - UV and virtual environments ensure dependency isolation and availability
 # - Multiple naming conventions supported (venv vs .venv)
 # - Graceful degradation to system Python if no venv found
 #
 # ACTIVATION STRATEGY:
+# - UV projects: use "uv run python" to execute in UV-managed environment
 # - Sources activate script to set up environment variables
 # - Returns specific Python path for exec (not just 'python')
 # - Maintains environment in same shell process
@@ -110,10 +113,18 @@ fi
 # - Caches result in process environment
 #
 # RETURNS:
-# Absolute path to Python executable with claude-mpm dependencies
+# Absolute path to Python executable with claude-mpm dependencies, or "uv run python" for UV projects
 #
 find_python_command() {
-    # 1. Check if we're in a pipx installation first
+    # 1. Check for UV project first (uv.lock or pyproject.toml with uv)
+    if [ -f "$CLAUDE_MPM_ROOT/uv.lock" ]; then
+        if command -v uv &> /dev/null; then
+            echo "uv run python"
+            return
+        fi
+    fi
+
+    # 2. Check if we're in a pipx installation
     if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
         # pipx installation - use the pipx venv's Python directly
         if [ -f "$CLAUDE_MPM_ROOT/bin/python" ]; then
@@ -122,7 +133,7 @@ find_python_command() {
         fi
     fi
 
-    # 2. Check for project-local virtual environment (common in development)
+    # 3. Check for project-local virtual environment (common in development)
     if [ -f "$CLAUDE_MPM_ROOT/venv/bin/activate" ]; then
         source "$CLAUDE_MPM_ROOT/venv/bin/activate"
         echo "$CLAUDE_MPM_ROOT/venv/bin/python"
@@ -173,15 +184,44 @@ fi
 # Set Socket.IO configuration for hook events
 export CLAUDE_MPM_SOCKETIO_PORT="${CLAUDE_MPM_SOCKETIO_PORT:-8765}"
 
-# Run the Python hook handler with all input
-# Use exec to replace the shell process with Python
-if ! exec "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log; then
-    # If the Python handler fails, always return continue to not block Claude
+# Function for debug logging
+log_debug() {
     if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
-        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/claude-mpm-hook-error.log" >> /tmp/claude-mpm-hook.log
-        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] $1" >> /tmp/claude-mpm-hook.log
+    fi
+}
+
+# Test Python works and module exists
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run python" ]]; then
+    if ! uv run python -c "import claude_mpm" 2>/dev/null; then
+        log_debug "claude_mpm module not available, continuing without hook"
+        echo '{"action": "continue"}'
+        exit 0
+    fi
+else
+    if ! $PYTHON_CMD -c "import claude_mpm" 2>/dev/null; then
+        log_debug "claude_mpm module not available, continuing without hook"
+        echo '{"action": "continue"}'
+        exit 0
     fi
-    # Return continue action to prevent blocking Claude Code
-    echo '{"action": "continue"}'
-    exit 0
-fi
+fi
+
+# Run the Python hook handler with all input
+# Use exec to replace the shell process with Python
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run python" ]]; then
+    exec uv run python -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+else
+    exec "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+fi
+
+# Note: exec replaces the shell process, so code below only runs if exec fails
+# If we reach here, the Python handler failed
+if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/claude-mpm-hook-error.log" >> /tmp/claude-mpm-hook.log
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
+fi
+# Return continue action to prevent blocking Claude Code
+echo '{"action": "continue"}'
+exit 0

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,278 @@
+"""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): engineer, qa-agent, memory-manager-agent, local-ops-agent,
+  research-agent, documentation-agent, security-agent
+- 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 = {
+        "engineer",
+        "qa-agent",
+        "memory-manager-agent",
+        "local-ops-agent",
+        "research-agent",
+        "documentation-agent",
+        "security-agent",
+    }
+
+    # 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",
+            }