claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

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/models/git_repository.py

@@ -0,0 +1,198 @@
+"""Git repository model for agent sources."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+
+@dataclass
+class GitRepository:
+    """Represents a Git repository configuration for agent sources.
+
+    This model tracks Git repositories that contain agent markdown files.
+    Repositories are cached locally and synced using ETag-based HTTP caching.
+
+    Attributes:
+        url: Full GitHub repository URL (e.g., https://github.com/owner/repo)
+        subdirectory: Optional subdirectory within repository (e.g., "agents/backend")
+        enabled: Whether this repository should be synced
+        priority: Priority for agent resolution (lower = higher precedence)
+        last_synced: Timestamp of last successful sync
+        etag: HTTP ETag from last sync for incremental updates
+    """
+
+    url: str
+    subdirectory: Optional[str] = None
+    enabled: bool = True
+    priority: int = 100
+    last_synced: Optional[datetime] = None
+    etag: Optional[str] = None
+
+    @property
+    def cache_path(self) -> Path:
+        """Return cache directory path for this repository.
+
+        Cache structure: ~/.claude-mpm/cache/agents/{owner}/{repo}/{subdirectory}/
+
+        Returns:
+            Absolute path to cache directory for this repository
+
+        Example:
+            >>> repo = GitRepository(
+            ...     url="https://github.com/bobmatnyc/claude-mpm-agents",
+            ...     subdirectory="agents"
+            ... )
+            >>> repo.cache_path
+            Path('/Users/user/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents')
+        """
+        home = Path.home()
+        base_cache = home / ".claude-mpm" / "cache" / "agents"
+
+        # Extract owner and repo from URL
+        owner, repo = self._parse_github_url(self.url)
+
+        # Build cache path: base/owner/repo/subdirectory
+        cache_path = base_cache / owner / repo
+
+        if self.subdirectory:
+            # Normalize subdirectory path (remove leading/trailing slashes)
+            normalized_subdir = self.subdirectory.strip("/")
+            cache_path = cache_path / normalized_subdir
+
+        return cache_path
+
+    @property
+    def identifier(self) -> str:
+        """Return unique identifier for this repository.
+
+        Format: {owner}/{repo}/{subdirectory} or {owner}/{repo}
+
+        Returns:
+            Unique identifier string
+
+        Example:
+            >>> repo = GitRepository(
+            ...     url="https://github.com/owner/repo",
+            ...     subdirectory="agents"
+            ... )
+            >>> repo.identifier
+            'owner/repo/agents'
+        """
+        owner, repo = self._parse_github_url(self.url)
+        base_id = f"{owner}/{repo}"
+
+        if self.subdirectory:
+            normalized_subdir = self.subdirectory.strip("/")
+            return f"{base_id}/{normalized_subdir}"
+
+        return base_id
+
+    def validate(self) -> list[str]:
+        """Validate repository configuration.
+
+        Returns:
+            List of validation error messages (empty if valid)
+
+        Validation checks:
+            - URL is not empty
+            - URL is valid HTTP/HTTPS format
+            - URL is a GitHub repository URL
+            - Priority is non-negative
+            - Priority is reasonable (<= 1000, warning only)
+            - Subdirectory is relative path (not absolute)
+        """
+        errors = []
+
+        # Validate URL
+        if not self.url or not self.url.strip():
+            errors.append("URL cannot be empty")
+            return errors  # Can't continue validation without URL
+
+        # Check URL format
+        try:
+            parsed = urlparse(self.url)
+
+            # Must be HTTP or HTTPS
+            if parsed.scheme not in ("http", "https"):
+                errors.append(
+                    f"URL must use http:// or https:// protocol, got: {parsed.scheme}"
+                )
+
+            # Must be GitHub (for now)
+            if not parsed.netloc.endswith("github.com"):
+                errors.append(f"URL must be a GitHub repository, got: {parsed.netloc}")
+
+            # Should have owner/repo path structure
+            path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+            if len(path_parts) < 2:
+                errors.append(f"URL must include owner/repo path, got: {parsed.path}")
+
+        except Exception as e:
+            errors.append(f"Invalid URL format: {e}")
+
+        # Validate priority
+        if self.priority < 0:
+            errors.append("Priority must be non-negative (0 or greater)")
+
+        if self.priority > 1000:
+            errors.append(
+                f"Priority {self.priority} is unusually high (recommended: 0-1000). "
+                "Lower priority numbers have higher precedence."
+            )
+
+        # Validate subdirectory
+        if self.subdirectory:
+            # Must be relative path
+            if Path(self.subdirectory).is_absolute():
+                errors.append(
+                    f"Subdirectory must be a relative path, got absolute: {self.subdirectory}"
+                )
+
+            # Should not start with slash
+            if self.subdirectory.startswith("/"):
+                errors.append(
+                    f"Subdirectory should not start with '/', got: {self.subdirectory}"
+                )
+
+        return errors
+
+    def _parse_github_url(self, url: str) -> tuple[str, str]:
+        """Parse GitHub URL to extract owner and repository name.
+
+        Args:
+            url: GitHub repository URL
+
+        Returns:
+            Tuple of (owner, repository_name)
+
+        Example:
+            >>> repo = GitRepository(url="https://github.com/owner/repo")
+            >>> repo._parse_github_url(repo.url)
+            ('owner', 'repo')
+        """
+        # Remove .git suffix if present
+        url = url.rstrip("/")
+        if url.endswith(".git"):
+            url = url[:-4]
+
+        # Parse URL
+        parsed = urlparse(url)
+        path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+
+        if len(path_parts) >= 2:
+            owner = path_parts[0]
+            repo = path_parts[1]
+            return owner, repo
+
+        # Fallback: Use URL as-is if parsing fails
+        # This will be caught by validation
+        return "unknown", "unknown"
+
+    def __repr__(self) -> str:
+        """Return string representation of repository."""
+        return (
+            f"GitRepository(identifier='{self.identifier}', "
+            f"priority={self.priority}, enabled={self.enabled})"
+        )

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
@@ -121,8 +132,8 @@ find_python_command() {
             return
         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"
@@ -152,7 +163,7 @@ if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
 elif [ -d "$CLAUDE_MPM_ROOT/src" ]; then
     # Development install - add src to PYTHONPATH
     export PYTHONPATH="$CLAUDE_MPM_ROOT/src:$PYTHONPATH"
-    
+
     if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
         echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Development environment detected" >> /tmp/claude-mpm-hook.log
     fi
@@ -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
-    # Return continue action to prevent blocking Claude Code
-    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
+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/scripts/start_activity_logging.py

@@ -51,7 +51,9 @@ if __name__ == "__main__":
 
     # Initialize aggregator
     aggregator = EventAggregator(
-        host="localhost", port=dashboard_port, save_dir=None  # Will use config value
+        host="localhost",
+        port=dashboard_port,
+        save_dir=None,  # Will use config value
     )
 
     # Set up signal handlers

claude_mpm/services/agents/agent_builder.py

@@ -8,12 +8,13 @@ This service provides comprehensive agent lifecycle management including:
 - Integration with deployment services
 """
 
-import json
 import re
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, ClassVar, Dict, List, Optional, Tuple
 
+import yaml
+
 from claude_mpm.core.exceptions import AgentDeploymentError
 from claude_mpm.core.logging_config import get_logger
 
@@ -205,8 +206,8 @@ class AgentBuilderService:
         """
         errors = []
 
-        # Required fields
-        required_fields = ["id", "name", "prompt", "model"]
+        # Required fields (model is optional - defaults to sonnet if not specified)
+        required_fields = ["id", "name", "prompt"]
         for field in required_fields:
             if field not in config:
                 errors.append(f"Missing required field: {field}")
@@ -218,7 +219,7 @@ class AgentBuilderService:
             except AgentDeploymentError as e:
                 errors.append(str(e))
 
-        # Validate model
+        # Validate model (only if present)
         if "model" in config:
             try:
                 self._validate_model(config["model"])
@@ -285,10 +286,15 @@ class AgentBuilderService:
         if not self.templates_dir.exists():
             return templates
 
-        for template_file in self.templates_dir.glob("*.json"):
+        # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
+        for template_file in self.templates_dir.glob("*.md"):
             try:
-                with template_file.open() as f:
-                    config = json.load(f)
+                # Read markdown content and extract YAML frontmatter
+                content = template_file.read_text()
+                config = self._extract_yaml_frontmatter(content)
+                if not config:
+                    self.logger.warning(f"No YAML frontmatter in {template_file.name}")
+                    continue
 
                 # Use filename stem as ID if not specified in config
                 template_id = config.get("id") or template_file.stem
@@ -308,6 +314,30 @@ class AgentBuilderService:
 
         return templates
 
+    def _extract_yaml_frontmatter(self, content: str) -> Optional[Dict[str, Any]]:
+        """
+        Extract and parse YAML frontmatter from markdown content.
+
+        Args:
+            content: File content to parse
+
+        Returns:
+            Parsed YAML frontmatter as dict, or None if not found/invalid
+        """
+        if not content.strip().startswith("---"):
+            return None
+
+        # Split on --- delimiters
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            return None
+
+        try:
+            return yaml.safe_load(parts[1])
+        except yaml.YAMLError as e:
+            self.logger.warning(f"Failed to parse YAML frontmatter: {e}")
+            return None
+
     def _validate_agent_id(self, agent_id: str) -> None:
         """Validate agent ID format.
 
@@ -371,16 +401,22 @@ class AgentBuilderService:
         if template_id in self._template_cache:
             return self._template_cache[template_id].copy()
 
-        template_file = self.templates_dir / f"{template_id}.json"
+        # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
+        template_file = self.templates_dir / f"{template_id}.md"
 
         if not template_file.exists():
             raise AgentDeploymentError(f"Template '{template_id}' not found")
 
         try:
-            with template_file.open() as f:
-                config = json.load(f)
-                self._template_cache[template_id] = config
-                return config.copy()
+            # Read markdown content and extract YAML frontmatter
+            content = template_file.read_text()
+            config = self._extract_yaml_frontmatter(content)
+            if not config:
+                raise AgentDeploymentError(
+                    f"No YAML frontmatter in template '{template_id}'"
+                )
+            self._template_cache[template_id] = config
+            return config.copy()
         except Exception as e:
             raise AgentDeploymentError(
                 f"Failed to load template '{template_id}': {e}"