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

claude_mpm/commander/adapters/base.py

@@ -0,0 +1,288 @@
+"""Base runtime adapter interface for MPM Commander.
+
+This module defines the abstract interface for runtime adapters that bridge
+between the TmuxOrchestrator and various AI coding tools (Claude Code, Cursor, etc.).
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import List, Optional, Set
+
+
+class Capability(Enum):
+    """Capabilities that a runtime adapter can provide."""
+
+    TOOL_USE = "tool_use"
+    FILE_EDIT = "file_edit"
+    FILE_CREATE = "file_create"
+    GIT_OPERATIONS = "git_operations"
+    SHELL_COMMANDS = "shell_commands"
+    WEB_SEARCH = "web_search"
+    COMPLEX_REASONING = "complex_reasoning"
+
+
+class RuntimeCapability(Enum):
+    """Extended capabilities a runtime may support (MPM-specific features)."""
+
+    FILE_READ = auto()
+    FILE_EDIT = auto()
+    FILE_CREATE = auto()
+    BASH_EXECUTION = auto()
+    GIT_OPERATIONS = auto()
+    TOOL_USE = auto()
+    AGENT_DELEGATION = auto()  # Sub-agent spawning
+    HOOKS = auto()  # Lifecycle hooks
+    INSTRUCTIONS = auto()  # Custom instructions file
+    MCP_TOOLS = auto()  # MCP server integration
+    SKILLS = auto()  # Loadable skills
+    MONITOR = auto()  # Real-time monitoring
+    WEB_SEARCH = auto()
+    COMPLEX_REASONING = auto()
+
+
+@dataclass
+class RuntimeInfo:
+    """Information about a runtime environment.
+
+    Attributes:
+        name: Runtime identifier (e.g., "claude-code", "auggie")
+        version: Optional version string
+        capabilities: Set of RuntimeCapability enums
+        command: CLI command to invoke runtime
+        supports_agents: Whether runtime supports agent delegation
+        instruction_file: Path to instructions file (e.g., "CLAUDE.md")
+
+    Example:
+        >>> info = RuntimeInfo(
+        ...     name="claude-code",
+        ...     version="1.0.0",
+        ...     capabilities={RuntimeCapability.FILE_EDIT, RuntimeCapability.TOOL_USE},
+        ...     command="claude",
+        ...     supports_agents=False,
+        ...     instruction_file="CLAUDE.md"
+        ... )
+    """
+
+    name: str
+    version: Optional[str]
+    capabilities: Set[RuntimeCapability]
+    command: str
+    supports_agents: bool = False
+    instruction_file: Optional[str] = None
+
+
+@dataclass
+class ParsedResponse:
+    """Parsed output from a runtime tool.
+
+    Attributes:
+        content: The extracted text content, with ANSI codes removed
+        is_complete: True if tool is waiting for input (idle state)
+        is_error: True if an error was detected in the output
+        error_message: The error message if is_error is True
+        is_question: True if tool is asking a question
+        question_text: The question text if is_question is True
+        options: List of options if presenting a choice
+
+    Example:
+        >>> response = ParsedResponse(
+        ...     content="File created successfully",
+        ...     is_complete=True,
+        ...     is_error=False,
+        ...     error_message=None,
+        ...     is_question=False,
+        ...     question_text=None,
+        ...     options=None
+        ... )
+    """
+
+    content: str
+    is_complete: bool
+    is_error: bool
+    error_message: Optional[str] = None
+    is_question: bool = False
+    question_text: Optional[str] = None
+    options: Optional[List[str]] = None
+
+
+class RuntimeAdapter(ABC):
+    """Abstract base class for runtime adapters.
+
+    A runtime adapter provides the interface between the TmuxOrchestrator
+    and a specific AI coding tool. It handles:
+    - Launching the tool with appropriate settings
+    - Formatting input messages
+    - Detecting tool states (idle, error, questioning)
+    - Parsing tool output into structured responses
+
+    Example:
+        >>> class MyAdapter(RuntimeAdapter):
+        ...     @property
+        ...     def name(self) -> str:
+        ...         return "my-tool"
+        ...
+        ...     def build_launch_command(self, project_path: str) -> str:
+        ...         return f"cd {project_path} && my-tool --interactive"
+    """
+
+    @abstractmethod
+    def build_launch_command(
+        self, project_path: str, agent_prompt: Optional[str] = None
+    ) -> str:
+        """Generate shell command to start the tool.
+
+        Args:
+            project_path: Absolute path to the project directory
+            agent_prompt: Optional system prompt to configure the agent
+
+        Returns:
+            Shell command string ready to execute
+
+        Example:
+            >>> adapter.build_launch_command("/home/user/project", "You are a Python expert")
+            'cd /home/user/project && claude --system-prompt "You are a Python expert"'
+        """
+
+    @abstractmethod
+    def format_input(self, message: str) -> str:
+        """Prepare message for tool's input format.
+
+        Args:
+            message: The user message to send
+
+        Returns:
+            Formatted message ready to send to the tool
+
+        Example:
+            >>> adapter.format_input("Fix the bug in main.py")
+            'Fix the bug in main.py'
+        """
+
+    @abstractmethod
+    def detect_idle(self, output: str) -> bool:
+        """Recognize when tool is waiting for input.
+
+        Args:
+            output: Raw output from the tool (may contain ANSI codes)
+
+        Returns:
+            True if the tool is in an idle state awaiting input
+
+        Example:
+            >>> adapter.detect_idle("Done editing file.\\n> ")
+            True
+            >>> adapter.detect_idle("Processing request...")
+            False
+        """
+
+    @abstractmethod
+    def detect_error(self, output: str) -> Optional[str]:
+        """Recognize error states, return error message if found.
+
+        Args:
+            output: Raw output from the tool
+
+        Returns:
+            Error message string if error detected, None otherwise
+
+        Example:
+            >>> adapter.detect_error("Error: File not found: config.py")
+            'Error: File not found: config.py'
+            >>> adapter.detect_error("File edited successfully")
+            None
+        """
+
+    @abstractmethod
+    def parse_response(self, output: str) -> ParsedResponse:
+        """Extract meaningful content from output.
+
+        This method combines all detection logic (idle, error, questions)
+        into a single structured response.
+
+        Args:
+            output: Raw output from the tool
+
+        Returns:
+            ParsedResponse with all detected states and content
+
+        Example:
+            >>> response = adapter.parse_response("Error: Invalid input\\n> ")
+            >>> response.is_error
+            True
+            >>> response.is_complete
+            True
+        """
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> Set[Capability]:
+        """What this tool can do.
+
+        Returns:
+            Set of Capability enums indicating supported features
+
+        Example:
+            >>> adapter.capabilities
+            {Capability.FILE_EDIT, Capability.TOOL_USE}
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Runtime identifier.
+
+        Returns:
+            Unique name for this runtime adapter
+
+        Example:
+            >>> adapter.name
+            'claude-code'
+        """
+
+    @property
+    def runtime_info(self) -> Optional[RuntimeInfo]:
+        """Return detailed runtime information.
+
+        Returns:
+            RuntimeInfo with capabilities and configuration, or None if not implemented
+
+        Example:
+            >>> info = adapter.runtime_info
+            >>> if info and RuntimeCapability.AGENT_DELEGATION in info.capabilities:
+            ...     print("Supports agent delegation")
+        """
+        return None
+
+    def inject_instructions(self, instructions: str) -> Optional[str]:
+        """Return command/method to inject custom instructions.
+
+        Args:
+            instructions: Instructions text to inject
+
+        Returns:
+            Command string to inject instructions, or None if not supported
+
+        Example:
+            >>> cmd = adapter.inject_instructions("You are a Python expert")
+            >>> if cmd:
+            ...     # Execute command to inject instructions
+        """
+        return None
+
+    def inject_agent_context(self, agent_id: str, context: dict) -> Optional[str]:
+        """Return command to inject agent context.
+
+        Args:
+            agent_id: Unique identifier for agent
+            context: Context dictionary with agent metadata
+
+        Returns:
+            Command string to inject context, or None if not supported
+
+        Example:
+            >>> cmd = adapter.inject_agent_context("eng-001", {"role": "Engineer"})
+            >>> if cmd:
+            ...     # Execute command to inject context
+        """
+        return None

claude_mpm/commander/adapters/claude_code.py

@@ -0,0 +1,392 @@
+"""Claude Code CLI runtime adapter.
+
+This module implements the RuntimeAdapter interface for the Claude Code CLI tool.
+It handles launching Claude Code, detecting its various states, and parsing its output.
+"""
+
+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 ClaudeCodeAdapter(RuntimeAdapter):
+    """Adapter for Claude Code CLI.
+
+    This adapter provides integration with the Claude Code command-line interface,
+    handling its unique prompt formats, error messages, and interactive behaviors.
+
+    Example:
+        >>> adapter = ClaudeCodeAdapter()
+        >>> cmd = adapter.build_launch_command("/home/user/project")
+        >>> print(cmd)
+        cd '/home/user/project' && claude --dangerously-skip-permissions
+    """
+
+    # Idle detection patterns (Claude Code prompt indicators)
+    IDLE_PATTERNS = [
+        r"^>\s*$",  # Simple prompt
+        r"claude>\s*$",  # Named prompt
+        r"╭─+╮",  # Box drawing (Claude's UI)
+        r"What would you like",  # Claude asking for input
+        r"How can I help",  # Alternative greeting
+    ]
+
+    # Error patterns - detect various error conditions
+    ERROR_PATTERNS = [
+        r"Error:",
+        r"Failed:",
+        r"Exception:",
+        r"Permission denied",
+        r"not found",
+        r"Traceback \(most recent call last\)",
+        r"FATAL:",
+        r"✗",  # Claude's error indicator
+        r"command not found",
+        r"cannot access",
+    ]
+
+    # Question patterns - detect when Claude is asking for confirmation
+    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",
+    ]
+
+    # ANSI escape code pattern for stripping color/formatting codes
+    ANSI_ESCAPE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+    @property
+    def name(self) -> str:
+        """Return the runtime identifier.
+
+        Returns:
+            The string "claude-code"
+        """
+        return "claude-code"
+
+    @property
+    def capabilities(self) -> Set[Capability]:
+        """Return the set of capabilities supported by Claude Code.
+
+        Claude Code is a full-featured AI coding assistant with comprehensive
+        tool use, file operations, git integration, and reasoning capabilities.
+
+        Returns:
+            Set of all supported Capability enums
+        """
+        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."""
+        return RuntimeInfo(
+            name="claude-code",
+            version=None,  # Version detection could be added
+            capabilities={
+                RuntimeCapability.FILE_READ,
+                RuntimeCapability.FILE_EDIT,
+                RuntimeCapability.FILE_CREATE,
+                RuntimeCapability.BASH_EXECUTION,
+                RuntimeCapability.GIT_OPERATIONS,
+                RuntimeCapability.TOOL_USE,
+                RuntimeCapability.WEB_SEARCH,
+                RuntimeCapability.COMPLEX_REASONING,
+                RuntimeCapability.AGENT_DELEGATION,  # Claude Code supports Task tool
+                RuntimeCapability.HOOKS,  # Claude Code supports hooks
+                RuntimeCapability.SKILLS,  # Claude Code can load skills
+                RuntimeCapability.MONITOR,  # Can be monitored
+            },
+            command="claude",
+            supports_agents=True,  # Claude Code supports agent delegation
+            instruction_file="CLAUDE.md",
+        )
+
+    def build_launch_command(
+        self, project_path: str, agent_prompt: Optional[str] = None
+    ) -> str:
+        """Generate shell command to start Claude Code.
+
+        Args:
+            project_path: Absolute path to the project directory
+            agent_prompt: Optional system prompt to configure Claude's behavior
+
+        Returns:
+            Shell command string ready to execute in bash
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> adapter.build_launch_command("/home/user/project")
+            "cd '/home/user/project' && claude --dangerously-skip-permissions"
+            >>> adapter.build_launch_command("/home/user/project", "You are a Python expert")
+            "cd '/home/user/project' && claude --system-prompt 'You are a Python expert' --dangerously-skip-permissions"
+
+        Note:
+            Uses --dangerously-skip-permissions for automated operation.
+            This is appropriate for MPM Commander's controlled environment.
+        """
+        # shlex.quote prevents shell injection
+        quoted_path = shlex.quote(project_path)  # nosec B604
+        cmd = f"cd {quoted_path} && claude"
+
+        if agent_prompt:
+            quoted_prompt = shlex.quote(agent_prompt)  # nosec B604
+            cmd += f" --system-prompt {quoted_prompt}"
+
+        # Skip permissions for automated operation
+        cmd += " --dangerously-skip-permissions"
+
+        logger.debug(f"Built launch command: {cmd}")
+        return cmd
+
+    def format_input(self, message: str) -> str:
+        """Prepare message for Claude Code's input format.
+
+        Claude Code accepts plain text input, so this method simply
+        strips leading/trailing whitespace.
+
+        Args:
+            message: The user message to send
+
+        Returns:
+            Formatted message (whitespace-trimmed)
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> adapter.format_input("  Fix the bug in main.py  ")
+            'Fix the bug in main.py'
+        """
+        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.
+
+        Args:
+            text: Text potentially containing ANSI escape sequences
+
+        Returns:
+            Clean text with ANSI codes removed
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> adapter.strip_ansi("\\x1b[32mSuccess\\x1b[0m")
+            'Success'
+        """
+        return self.ANSI_ESCAPE.sub("", text)
+
+    def detect_idle(self, output: str) -> bool:
+        """Recognize when Claude Code is waiting for input.
+
+        Checks the last line of output against known idle patterns
+        such as the prompt indicator or greeting messages.
+
+        Args:
+            output: Raw output from Claude Code (may contain ANSI codes)
+
+        Returns:
+            True if Claude is in an idle state awaiting input
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> adapter.detect_idle("Done editing file.\\n> ")
+            True
+            >>> adapter.detect_idle("Processing request...")
+            False
+            >>> adapter.detect_idle("╭─────────────────╮\\nWhat would you like me to help with?")
+            True
+        """
+        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()
+
+        # Check against all idle patterns
+        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.
+
+        Searches the output for known error patterns and returns
+        the line containing the error for context.
+
+        Args:
+            output: Raw output from Claude Code
+
+        Returns:
+            Error message string if error detected, None otherwise
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> adapter.detect_error("Error: File not found: config.py")
+            'Error: File not found: config.py'
+            >>> adapter.detect_error("File edited successfully")
+            None
+            >>> adapter.detect_error("Traceback (most recent call last):\\n  File...")
+            'Traceback (most recent call last):'
+        """
+        clean = self.strip_ansi(output)
+
+        for pattern in self.ERROR_PATTERNS:
+            match = re.search(pattern, clean, re.IGNORECASE)
+            if match:
+                # Extract the line containing the error for context
+                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 Claude is asking a question and extract options.
+
+        Searches for question patterns and attempts to extract the question
+        text along with any numbered options presented.
+
+        Args:
+            output: Raw output from Claude Code
+
+        Returns:
+            Tuple of (is_question, question_text, options)
+            - is_question: True if a question was detected
+            - question_text: The question text if found
+            - options: List of option strings if numbered options found
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> is_q, text, opts = adapter.detect_question("Should I proceed? (y/n)?")
+            >>> is_q
+            True
+            >>> text
+            'Should I proceed? (y/n)?'
+            >>> is_q, text, opts = adapter.detect_question(
+            ...     "Which option:\\n1. Create new file\\n2. Edit existing"
+            ... )
+            >>> opts
+            ['Create new file', 'Edit existing']
+        """
+        clean = self.strip_ansi(output)
+
+        for pattern in self.QUESTION_PATTERNS:
+            if re.search(pattern, clean, re.IGNORECASE):
+                # Try to extract question and options
+                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 (1., 2., 1), 2), etc.)
+                    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 Claude Code output.
+
+        Combines all detection logic (idle, error, questions) into a
+        single structured response object.
+
+        Args:
+            output: Raw output from Claude Code
+
+        Returns:
+            ParsedResponse with all detected states and content
+
+        Example:
+            >>> adapter = ClaudeCodeAdapter()
+            >>> response = adapter.parse_response("Error: Invalid input\\n> ")
+            >>> response.is_error
+            True
+            >>> response.is_complete
+            True
+            >>> response.error_message
+            'Error: Invalid input'
+
+            >>> response = adapter.parse_response("File created: test.py\\n> ")
+            >>> response.content
+            'File created: test.py\\n> '
+            >>> response.is_complete
+            True
+            >>> response.is_error
+            False
+        """
+        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