claude-mpm 5.6.1__py3-none-any.whl → 5.6.76__py3-none-any.whl

claude_mpm/commander/adapters/mpm.py

@@ -0,0 +1,389 @@
+"""MPM (Multi-agent Project Manager) runtime adapter.
+
+This module implements the RuntimeAdapter interface for MPM,
+providing full support for agent delegation, hooks, skills, and monitoring.
+"""
+
+import json
+import logging
+import re
+import shlex
+from typing import List, Optional, Set
+
+from .base import (
+    Capability,
+    ParsedResponse,
+    RuntimeAdapter,
+    RuntimeCapability,
+    RuntimeInfo,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MPMAdapter(RuntimeAdapter):
+    """Adapter for MPM (Multi-agent Project Manager).
+
+    MPM extends Claude Code with multi-agent orchestration, lifecycle hooks,
+    skills, real-time monitoring, and advanced project management capabilities.
+
+    Features:
+        - Agent delegation and sub-agent spawning
+        - Lifecycle hooks (pre/post task, pre/post commit, etc.)
+        - Loadable skills for specialized tasks
+        - Real-time monitoring dashboard
+        - Custom instructions via CLAUDE.md
+        - MCP server integration
+        - Git workflow automation
+
+    Example:
+        >>> adapter = MPMAdapter()
+        >>> cmd = adapter.build_launch_command("/home/user/project")
+        >>> # Inject agent context
+        >>> ctx_cmd = adapter.inject_agent_context("eng-001", {"role": "Engineer"})
+        >>> # Check capabilities
+        >>> info = adapter.runtime_info
+        >>> if RuntimeCapability.AGENT_DELEGATION in info.capabilities:
+        ...     print("Supports agent delegation")
+    """
+
+    # Idle detection patterns (inherits from Claude Code)
+    IDLE_PATTERNS = [
+        r"^>\s*$",  # Simple prompt
+        r"claude>\s*$",  # Named prompt
+        r"╭─+╮",  # Box drawing
+        r"What would you like",
+        r"How can I help",
+    ]
+
+    # MPM-specific patterns
+    MPM_PATTERNS = [
+        r"\[MPM\]",  # MPM prefix
+        r"Agent spawned:",
+        r"Delegating to agent:",
+        r"Hook triggered:",
+        r"Skill loaded:",
+    ]
+
+    # Error patterns
+    ERROR_PATTERNS = [
+        r"Error:",
+        r"Failed:",
+        r"Exception:",
+        r"Permission denied",
+        r"not found",
+        r"Traceback \(most recent call last\)",
+        r"FATAL:",
+        r"✗",
+        r"command not found",
+        r"cannot access",
+        r"Agent error:",
+        r"Hook failed:",
+    ]
+
+    # Question patterns
+    QUESTION_PATTERNS = [
+        r"Which option",
+        r"Should I proceed",
+        r"Please choose",
+        r"\(y/n\)\?",
+        r"Are you sure",
+        r"Do you want",
+        r"\[Y/n\]",
+        r"\[yes/no\]",
+        r"Select an option",
+        r"Choose from",
+        r"Delegate to which agent",
+    ]
+
+    # ANSI escape code pattern
+    ANSI_ESCAPE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+    @property
+    def name(self) -> str:
+        """Return the runtime identifier."""
+        return "mpm"
+
+    @property
+    def capabilities(self) -> Set[Capability]:
+        """Return the set of capabilities supported by MPM."""
+        return {
+            Capability.TOOL_USE,
+            Capability.FILE_EDIT,
+            Capability.FILE_CREATE,
+            Capability.GIT_OPERATIONS,
+            Capability.SHELL_COMMANDS,
+            Capability.WEB_SEARCH,
+            Capability.COMPLEX_REASONING,
+        }
+
+    @property
+    def runtime_info(self) -> RuntimeInfo:
+        """Return detailed runtime information.
+
+        MPM has the most comprehensive capabilities of all runtimes.
+        """
+        return RuntimeInfo(
+            name="mpm",
+            version=None,  # Could parse from mpm --version
+            capabilities={
+                RuntimeCapability.FILE_READ,
+                RuntimeCapability.FILE_EDIT,
+                RuntimeCapability.FILE_CREATE,
+                RuntimeCapability.BASH_EXECUTION,
+                RuntimeCapability.GIT_OPERATIONS,
+                RuntimeCapability.TOOL_USE,
+                RuntimeCapability.AGENT_DELEGATION,  # Key MPM feature
+                RuntimeCapability.HOOKS,  # Lifecycle hooks
+                RuntimeCapability.INSTRUCTIONS,  # CLAUDE.md
+                RuntimeCapability.MCP_TOOLS,  # MCP integration
+                RuntimeCapability.SKILLS,  # Loadable skills
+                RuntimeCapability.MONITOR,  # Real-time monitoring
+                RuntimeCapability.WEB_SEARCH,
+                RuntimeCapability.COMPLEX_REASONING,
+            },
+            command="claude",  # MPM uses claude CLI with MPM config
+            supports_agents=True,  # Full agent support
+            instruction_file="CLAUDE.md",
+        )
+
+    def build_launch_command(
+        self, project_path: str, agent_prompt: Optional[str] = None
+    ) -> str:
+        """Generate shell command to start MPM.
+
+        Args:
+            project_path: Absolute path to the project directory
+            agent_prompt: Optional system prompt to configure agent
+
+        Returns:
+            Shell command string ready to execute
+
+        Example:
+            >>> adapter = MPMAdapter()
+            >>> adapter.build_launch_command("/home/user/project")
+            "cd '/home/user/project' && claude --dangerously-skip-permissions"
+        """
+        quoted_path = shlex.quote(project_path)
+        cmd = f"cd {quoted_path} && claude"
+
+        if agent_prompt:
+            quoted_prompt = shlex.quote(agent_prompt)
+            cmd += f" --system-prompt {quoted_prompt}"
+
+        # Skip permissions for automated operation
+        cmd += " --dangerously-skip-permissions"
+
+        logger.debug(f"Built MPM launch command: {cmd}")
+        return cmd
+
+    def format_input(self, message: str) -> str:
+        """Prepare message for MPM's input format."""
+        formatted = message.strip()
+        logger.debug(f"Formatted input: {formatted[:100]}...")
+        return formatted
+
+    def strip_ansi(self, text: str) -> str:
+        """Remove ANSI escape codes from text."""
+        return self.ANSI_ESCAPE.sub("", text)
+
+    def detect_idle(self, output: str) -> bool:
+        """Recognize when MPM is waiting for input."""
+        if not output:
+            return False
+
+        clean = self.strip_ansi(output)
+        lines = clean.strip().split("\n")
+
+        if not lines:
+            return False
+
+        last_line = lines[-1].strip()
+
+        for pattern in self.IDLE_PATTERNS:
+            if re.search(pattern, last_line):
+                logger.debug(f"Detected idle state with pattern: {pattern}")
+                return True
+
+        return False
+
+    def detect_error(self, output: str) -> Optional[str]:
+        """Recognize error states and extract error message."""
+        clean = self.strip_ansi(output)
+
+        for pattern in self.ERROR_PATTERNS:
+            match = re.search(pattern, clean, re.IGNORECASE)
+            if match:
+                for line in clean.split("\n"):
+                    if re.search(pattern, line, re.IGNORECASE):
+                        error_msg = line.strip()
+                        logger.warning(f"Detected error: {error_msg}")
+                        return error_msg
+
+        return None
+
+    def detect_question(
+        self, output: str
+    ) -> tuple[bool, Optional[str], Optional[List[str]]]:
+        """Detect if MPM is asking a question."""
+        clean = self.strip_ansi(output)
+
+        for pattern in self.QUESTION_PATTERNS:
+            if re.search(pattern, clean, re.IGNORECASE):
+                lines = clean.strip().split("\n")
+                question = None
+                options = []
+
+                for line in lines:
+                    if re.search(pattern, line, re.IGNORECASE):
+                        question = line.strip()
+
+                    # Look for numbered options
+                    opt_match = re.match(r"^\s*(\d+)[.):]\s*(.+)$", line)
+                    if opt_match:
+                        options.append(opt_match.group(2).strip())
+
+                logger.debug(
+                    f"Detected question: {question}, options: {options if options else 'none'}"
+                )
+                return True, question, options if options else None
+
+        return False, None, None
+
+    def parse_response(self, output: str) -> ParsedResponse:
+        """Extract meaningful content from MPM output."""
+        if not output:
+            return ParsedResponse(
+                content="",
+                is_complete=False,
+                is_error=False,
+                is_question=False,
+            )
+
+        clean = self.strip_ansi(output)
+        error_msg = self.detect_error(output)
+        is_question, question_text, options = self.detect_question(output)
+        is_complete = self.detect_idle(output)
+
+        response = ParsedResponse(
+            content=clean,
+            is_complete=is_complete,
+            is_error=error_msg is not None,
+            error_message=error_msg,
+            is_question=is_question,
+            question_text=question_text,
+            options=options,
+        )
+
+        logger.debug(
+            f"Parsed response: complete={is_complete}, error={error_msg is not None}, "
+            f"question={is_question}"
+        )
+
+        return response
+
+    def inject_instructions(self, instructions: str) -> Optional[str]:
+        """Return command to inject custom instructions.
+
+        MPM uses CLAUDE.md for custom instructions.
+
+        Args:
+            instructions: Instructions text to inject
+
+        Returns:
+            Command to write CLAUDE.md file
+
+        Example:
+            >>> adapter = MPMAdapter()
+            >>> cmd = adapter.inject_instructions("You are a Python expert")
+            >>> print(cmd)
+            echo '...' > CLAUDE.md
+        """
+        # Write to CLAUDE.md
+        escaped = instructions.replace("'", "'\\''")
+        return f"echo '{escaped}' > CLAUDE.md"
+
+    def inject_agent_context(self, agent_id: str, context: dict) -> Optional[str]:
+        """Return command to inject agent context.
+
+        MPM supports agent context injection via special command.
+
+        Args:
+            agent_id: Unique identifier for agent
+            context: Context dictionary with agent metadata
+
+        Returns:
+            Command to inject agent context
+
+        Example:
+            >>> adapter = MPMAdapter()
+            >>> cmd = adapter.inject_agent_context("eng-001", {"role": "Engineer"})
+            >>> # Command would set MPM_AGENT_ID and MPM_AGENT_CONTEXT env vars
+        """
+        # Serialize context to JSON
+        context_json = json.dumps(context)
+        escaped_json = context_json.replace("'", "'\\''")
+
+        # Set environment variables for MPM agent context
+        # MPM runtime can read these to understand agent identity
+        cmd = f"export MPM_AGENT_ID='{agent_id}' && export MPM_AGENT_CONTEXT='{escaped_json}'"
+
+        logger.debug(f"Built agent context injection command for {agent_id}")
+        return cmd
+
+    def detect_agent_spawn(self, output: str) -> Optional[dict]:
+        """Detect if MPM has spawned a new agent.
+
+        Args:
+            output: Raw output from MPM
+
+        Returns:
+            Dict with agent info if spawn detected, None otherwise
+
+        Example:
+            >>> adapter = MPMAdapter()
+            >>> info = adapter.detect_agent_spawn("[MPM] Agent spawned: eng-001 (Engineer)")
+            >>> if info:
+            ...     print(info['agent_id'])
+            'eng-001'
+        """
+        clean = self.strip_ansi(output)
+
+        # Pattern: [MPM] Agent spawned: <agent_id> (<role>)
+        match = re.search(r"\[MPM\] Agent spawned: (\S+) \(([^)]+)\)", clean)
+        if match:
+            agent_id = match.group(1)
+            role = match.group(2)
+
+            logger.info(f"Detected agent spawn: {agent_id} ({role})")
+            return {"agent_id": agent_id, "role": role}
+
+        return None
+
+    def detect_hook_trigger(self, output: str) -> Optional[dict]:
+        """Detect if a lifecycle hook was triggered.
+
+        Args:
+            output: Raw output from MPM
+
+        Returns:
+            Dict with hook info if trigger detected, None otherwise
+
+        Example:
+            >>> adapter = MPMAdapter()
+            >>> info = adapter.detect_hook_trigger("[MPM] Hook triggered: pre-commit")
+            >>> if info:
+            ...     print(info['hook_name'])
+            'pre-commit'
+        """
+        clean = self.strip_ansi(output)
+
+        # Pattern: [MPM] Hook triggered: <hook_name>
+        match = re.search(r"\[MPM\] Hook triggered: (\S+)", clean)
+        if match:
+            hook_name = match.group(1)
+
+            logger.info(f"Detected hook trigger: {hook_name}")
+            return {"hook_name": hook_name}
+
+        return None

claude_mpm/commander/adapters/registry.py

@@ -0,0 +1,204 @@
+"""Adapter registry for runtime detection and selection.
+
+This module provides a registry for managing runtime adapters, with
+automatic detection of available runtimes on the system.
+"""
+
+import logging
+import shutil
+from typing import Dict, List, Optional, Type
+
+from .base import RuntimeAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterRegistry:
+    """Registry for managing runtime adapters.
+
+    Provides centralized registration, retrieval, and auto-detection
+    of available runtime adapters.
+
+    Example:
+        >>> # Register adapter
+        >>> AdapterRegistry.register('claude-code', ClaudeCodeAdapter)
+        >>> # Get adapter instance
+        >>> adapter = AdapterRegistry.get('claude-code')
+        >>> # Detect available runtimes
+        >>> available = AdapterRegistry.detect_available()
+        >>> print(available)
+        ['claude-code', 'mpm']
+    """
+
+    _adapters: Dict[str, Type[RuntimeAdapter]] = {}
+    _runtime_commands: Dict[str, str] = {
+        "claude-code": "claude",
+        "auggie": "auggie",
+        "codex": "codex",
+        "mpm": "claude",  # MPM uses claude with extra config
+    }
+
+    @classmethod
+    def register(cls, name: str, adapter_class: Type[RuntimeAdapter]) -> None:
+        """Register a runtime adapter.
+
+        Args:
+            name: Unique identifier for the adapter
+            adapter_class: RuntimeAdapter subclass to register
+
+        Example:
+            >>> AdapterRegistry.register('my-runtime', MyAdapter)
+        """
+        cls._adapters[name] = adapter_class
+        logger.debug(f"Registered adapter: {name}")
+
+    @classmethod
+    def unregister(cls, name: str) -> None:
+        """Unregister a runtime adapter.
+
+        Args:
+            name: Identifier of adapter to unregister
+
+        Example:
+            >>> AdapterRegistry.unregister('my-runtime')
+        """
+        if name in cls._adapters:
+            del cls._adapters[name]
+            logger.debug(f"Unregistered adapter: {name}")
+
+    @classmethod
+    def get(cls, name: str) -> Optional[RuntimeAdapter]:
+        """Get adapter instance by name.
+
+        Args:
+            name: Identifier of adapter to retrieve
+
+        Returns:
+            RuntimeAdapter instance if found, None otherwise
+
+        Example:
+            >>> adapter = AdapterRegistry.get('claude-code')
+            >>> if adapter:
+            ...     print(adapter.name)
+            'claude-code'
+        """
+        if name in cls._adapters:
+            adapter = cls._adapters[name]()
+            logger.debug(f"Retrieved adapter: {name}")
+            return adapter
+        logger.warning(f"Adapter not found: {name}")
+        return None
+
+    @classmethod
+    def list_registered(cls) -> List[str]:
+        """List all registered adapter names.
+
+        Returns:
+            List of registered adapter identifiers
+
+        Example:
+            >>> registered = AdapterRegistry.list_registered()
+            >>> print(registered)
+            ['claude-code', 'auggie', 'codex', 'mpm']
+        """
+        return list(cls._adapters.keys())
+
+    @classmethod
+    def detect_available(cls) -> List[str]:
+        """Detect which runtimes are available on this system.
+
+        Checks for CLI commands in PATH to determine which runtimes
+        are installed and accessible.
+
+        Returns:
+            List of available runtime identifiers
+
+        Example:
+            >>> available = AdapterRegistry.detect_available()
+            >>> if 'claude-code' in available:
+            ...     print("Claude Code is available")
+        """
+        available = []
+
+        for name, command in cls._runtime_commands.items():
+            if name in cls._adapters and shutil.which(command):
+                available.append(name)
+                logger.debug(f"Detected available runtime: {name} (command: {command})")
+
+        logger.info(f"Available runtimes: {available}")
+        return available
+
+    @classmethod
+    def get_default(cls) -> Optional[RuntimeAdapter]:
+        """Get the best available adapter.
+
+        Selection priority: mpm > claude-code > auggie > codex
+
+        Returns:
+            RuntimeAdapter instance for best available runtime, or None
+
+        Example:
+            >>> adapter = AdapterRegistry.get_default()
+            >>> if adapter:
+            ...     print(f"Using {adapter.name}")
+        """
+        # Priority order: MPM has most features, then Claude Code, etc.
+        priority = ["mpm", "claude-code", "auggie", "codex"]
+
+        available = cls.detect_available()
+
+        for name in priority:
+            if name in available:
+                adapter = cls.get(name)
+                logger.info(f"Selected default adapter: {name}")
+                return adapter
+
+        logger.warning("No adapters available")
+        return None
+
+    @classmethod
+    def is_available(cls, name: str) -> bool:
+        """Check if a specific runtime is available.
+
+        Args:
+            name: Runtime identifier to check
+
+        Returns:
+            True if runtime is registered and command is in PATH
+
+        Example:
+            >>> if AdapterRegistry.is_available('claude-code'):
+            ...     adapter = AdapterRegistry.get('claude-code')
+        """
+        return name in cls.detect_available()
+
+    @classmethod
+    def get_command(cls, name: str) -> Optional[str]:
+        """Get CLI command for a runtime.
+
+        Args:
+            name: Runtime identifier
+
+        Returns:
+            CLI command string if found, None otherwise
+
+        Example:
+            >>> cmd = AdapterRegistry.get_command('claude-code')
+            >>> print(cmd)
+            'claude'
+        """
+        return cls._runtime_commands.get(name)
+
+    @classmethod
+    def register_command(cls, name: str, command: str) -> None:
+        """Register CLI command for a runtime.
+
+        Args:
+            name: Runtime identifier
+            command: CLI command to invoke runtime
+
+        Example:
+            >>> AdapterRegistry.register_command('my-runtime', 'my-cli')
+        """
+        cls._runtime_commands[name] = command
+        logger.debug(f"Registered command for {name}: {command}")

claude_mpm/commander/api/app.py

@@ -6,7 +6,7 @@ lifecycle management, and route registration.
 
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import AsyncGenerator, Optional
+from typing import AsyncGenerator
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -20,14 +20,6 @@ from ..tmux_orchestrator import TmuxOrchestrator
 from ..workflow import EventHandler
 from .routes import events, inbox as inbox_routes, messages, projects, sessions, work
 
-# Global instances (injected at startup via lifespan)
-registry: Optional[ProjectRegistry] = None
-tmux: Optional[TmuxOrchestrator] = None
-event_manager: Optional[EventManager] = None
-inbox: Optional[Inbox] = None
-event_handler: Optional[EventHandler] = None
-session_manager: dict = {}  # project_id -> ProjectSession
-
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
@@ -42,13 +34,37 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         None during application runtime
     """
     # Startup
-    global registry, tmux, event_manager, inbox, event_handler, session_manager
-    registry = ProjectRegistry()
-    tmux = TmuxOrchestrator()
-    event_manager = EventManager()
-    inbox = Inbox(event_manager, registry)
-    session_manager = {}  # Populated by daemon when sessions are created
-    event_handler = EventHandler(inbox, session_manager)
+    import logging
+
+    logger = logging.getLogger(__name__)
+    logger.info("Lifespan starting. Initializing app.state resources...")
+
+    # Initialize app.state resources (daemon will inject its instances later)
+    if not hasattr(app.state, "registry"):
+        app.state.registry = ProjectRegistry()
+    if not hasattr(app.state, "tmux"):
+        app.state.tmux = TmuxOrchestrator()
+    if not hasattr(app.state, "event_manager"):
+        app.state.event_manager = EventManager()
+    if not hasattr(app.state, "inbox"):
+        app.state.inbox = Inbox(app.state.event_manager, app.state.registry)
+    if not hasattr(app.state, "session_manager"):
+        app.state.session_manager = {}
+    if not hasattr(app.state, "work_queues"):
+        logger.info("work_queues not set, creating new dict")
+        app.state.work_queues = {}
+    else:
+        logger.info(
+            f"work_queues already set, preserving id: {id(app.state.work_queues)}"
+        )
+    if not hasattr(app.state, "daemon_instance"):
+        app.state.daemon_instance = None
+    if not hasattr(app.state, "event_handler"):
+        app.state.event_handler = EventHandler(
+            app.state.inbox, app.state.session_manager
+        )
+
+    logger.info(f"Lifespan complete. work_queues id: {id(app.state.work_queues)}")
 
     yield
 

claude_mpm/commander/api/errors.py

@@ -110,3 +110,24 @@ class InvalidRuntimeError(CommanderAPIError):
             f"Invalid runtime: {runtime}",
             400,
         )
+
+
+class TmuxNoSpaceError(CommanderAPIError):
+    """Raised when tmux has no space for a new pane."""
+
+    def __init__(self, message: str | None = None):
+        """Initialize tmux no space error.
+
+        Args:
+            message: Custom error message (optional)
+        """
+        default_msg = (
+            "Unable to create session: tmux has no space for new pane. "
+            "Try closing some sessions or resize your terminal window. "
+            "You can also create a new tmux window with `tmux new-window`."
+        )
+        super().__init__(
+            "TMUX_NO_SPACE",
+            message or default_msg,
+            409,
+        )