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

claude_mpm/commander/adapters/communication.py

@@ -0,0 +1,366 @@
+"""Communication adapters for managing async I/O with AI coding assistants.
+
+This module provides the async communication layer that sits between
+InstanceManager and TmuxOrchestrator, using RuntimeAdapter for parsing.
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, AsyncIterator, Optional
+
+from claude_mpm.commander.tmux_orchestrator import TmuxOrchestrator
+
+from .base import RuntimeAdapter
+
+if TYPE_CHECKING:
+    from .base import ParsedResponse
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterState(Enum):
+    """States that a communication adapter can be in."""
+
+    IDLE = "idle"  # Ready for input
+    PROCESSING = "processing"  # Working on request
+    WAITING = "waiting"  # Waiting for user input (e.g., permission)
+    ERROR = "error"  # Error state
+
+
+@dataclass
+class AdapterResponse:
+    """Response from a communication adapter.
+
+    Attributes:
+        content: The response content
+        state: Current adapter state
+        tool_uses: List of tools used in response
+        files_modified: List of files edited
+        is_complete: True if response is complete (prompt returned)
+
+    Example:
+        >>> response = AdapterResponse(
+        ...     content="File created: test.py",
+        ...     state=AdapterState.IDLE,
+        ...     tool_uses=["Write"],
+        ...     files_modified=["test.py"],
+        ...     is_complete=True
+        ... )
+    """
+
+    content: str
+    state: AdapterState
+    tool_uses: Optional[list[str]] = None
+    files_modified: Optional[list[str]] = None
+    is_complete: bool = False
+
+
+class BaseCommunicationAdapter(ABC):
+    """Abstract base class for communication adapters.
+
+    A communication adapter manages the async I/O with an AI coding assistant
+    via TmuxOrchestrator, maintaining state and handling streaming responses.
+
+    Example:
+        >>> orchestrator = TmuxOrchestrator()
+        >>> adapter = ClaudeCodeCommunicationAdapter(orchestrator, "%0")
+        >>> await adapter.send("Fix the bug in main.py")
+        >>> response = await adapter.receive()
+        >>> print(response.content)
+    """
+
+    @abstractmethod
+    async def send(self, message: str) -> None:
+        """Send a message to the assistant.
+
+        Args:
+            message: The message to send
+
+        Example:
+            >>> await adapter.send("Fix the bug in main.py")
+        """
+
+    @abstractmethod
+    async def receive(self, timeout: float = 30.0) -> AdapterResponse:
+        """Wait for and return response.
+
+        Args:
+            timeout: Maximum time to wait for response
+
+        Returns:
+            AdapterResponse with parsed content and state
+
+        Example:
+            >>> response = await adapter.receive(timeout=60.0)
+            >>> print(response.content)
+        """
+
+    @abstractmethod
+    async def interrupt(self) -> bool:
+        """Send interrupt signal (Ctrl+C).
+
+        Returns:
+            True if interrupt was successful
+
+        Example:
+            >>> success = await adapter.interrupt()
+        """
+
+    @abstractmethod
+    def is_ready(self) -> bool:
+        """Check if adapter is ready for input.
+
+        Returns:
+            True if adapter is in IDLE state
+
+        Example:
+            >>> if adapter.is_ready():
+            ...     await adapter.send("Next task")
+        """
+
+    @abstractmethod
+    async def stream_response(self) -> AsyncIterator[str]:
+        """Stream response chunks as they arrive.
+
+        Yields:
+            Response chunks as they become available
+
+        Example:
+            >>> async for chunk in adapter.stream_response():
+            ...     print(chunk, end='')
+        """
+
+
+class ClaudeCodeCommunicationAdapter(BaseCommunicationAdapter):
+    """Communication adapter for Claude Code CLI.
+
+    This adapter manages async I/O with Claude Code via TmuxOrchestrator,
+    using ClaudeCodeAdapter (RuntimeAdapter) for output parsing.
+
+    Attributes:
+        orchestrator: TmuxOrchestrator for tmux operations
+        pane_target: Tmux pane target (e.g., "%0")
+        poll_interval: Polling interval for output capture (seconds)
+
+    Example:
+        >>> orchestrator = TmuxOrchestrator()
+        >>> adapter = ClaudeCodeCommunicationAdapter(orchestrator, "%0")
+        >>> await adapter.send("Create a new Python file")
+        >>> response = await adapter.receive()
+        >>> print(response.files_modified)
+        ['new_file.py']
+    """
+
+    def __init__(
+        self,
+        orchestrator: TmuxOrchestrator,
+        pane_target: str,
+        runtime_adapter: RuntimeAdapter,
+        poll_interval: float = 0.2,
+    ):
+        """Initialize the communication adapter.
+
+        Args:
+            orchestrator: TmuxOrchestrator for tmux operations
+            pane_target: Tmux pane target (e.g., "%0")
+            runtime_adapter: RuntimeAdapter for parsing output
+            poll_interval: Polling interval for output capture (seconds)
+        """
+        self.orchestrator = orchestrator
+        self.pane_target = pane_target
+        self.runtime_adapter = runtime_adapter
+        self.poll_interval = poll_interval
+        self._state = AdapterState.IDLE
+        self._last_output = ""
+        self._output_buffer = ""
+
+    async def send(self, message: str) -> None:
+        """Send message to Claude Code.
+
+        Args:
+            message: The message to send
+
+        Example:
+            >>> await adapter.send("Fix the bug in main.py")
+        """
+        logger.debug(f"Sending message to {self.pane_target}: {message[:50]}...")
+        self._state = AdapterState.PROCESSING
+        self._output_buffer = ""
+
+        # Format message using RuntimeAdapter
+        formatted = self.runtime_adapter.format_input(message)
+
+        # Send via tmux
+        self.orchestrator.send_keys(self.pane_target, formatted, enter=True)
+
+    async def receive(self, timeout: float = 30.0) -> AdapterResponse:
+        """Wait for complete response from Claude Code.
+
+        Args:
+            timeout: Maximum time to wait for response
+
+        Returns:
+            AdapterResponse with parsed content and state
+
+        Example:
+            >>> response = await adapter.receive(timeout=60.0)
+            >>> if response.is_complete:
+            ...     print("Task complete!")
+        """
+        start = asyncio.get_event_loop().time()
+
+        while asyncio.get_event_loop().time() - start < timeout:
+            # Capture output from tmux pane
+            output = self.orchestrator.capture_output(self.pane_target, lines=100)
+
+            # Get only new output
+            new_output = self._get_new_output(output)
+            if new_output:
+                self._output_buffer += new_output
+
+            # Parse response using RuntimeAdapter
+            parsed = self.runtime_adapter.parse_response(output)
+
+            # Check if error occurred (prioritize error state)
+            if parsed.is_error:
+                self._state = AdapterState.ERROR
+                logger.warning(f"Error detected: {parsed.error_message}")
+                return self._build_response(parsed, is_complete=True)
+
+            # Check if waiting for user input (question)
+            if parsed.is_question:
+                self._state = AdapterState.WAITING
+                logger.debug(f"Question detected: {parsed.question_text}")
+                return self._build_response(parsed, is_complete=False)
+
+            # Check if response is complete (idle state)
+            if parsed.is_complete:
+                self._state = AdapterState.IDLE
+                logger.debug("Response complete (idle detected)")
+                return self._build_response(parsed, is_complete=True)
+
+            # Continue polling
+            await asyncio.sleep(self.poll_interval)
+
+        # Timeout - return partial response
+        logger.warning(f"Timeout after {timeout}s")
+        parsed = self.runtime_adapter.parse_response(self._output_buffer)
+        return self._build_response(parsed, is_complete=False)
+
+    async def interrupt(self) -> bool:
+        """Send Ctrl+C to interrupt Claude Code.
+
+        Returns:
+            True if interrupt was successful
+
+        Example:
+            >>> success = await adapter.interrupt()
+            >>> if success:
+            ...     print("Interrupted successfully")
+        """
+        try:
+            logger.info(f"Sending interrupt to {self.pane_target}")
+            self.orchestrator.send_keys(self.pane_target, "C-c", enter=False)
+            self._state = AdapterState.IDLE
+            return True
+        except Exception as e:
+            logger.error(f"Failed to interrupt: {e}")
+            return False
+
+    def is_ready(self) -> bool:
+        """Check if adapter is ready for input.
+
+        Returns:
+            True if adapter is in IDLE state
+
+        Example:
+            >>> if adapter.is_ready():
+            ...     await adapter.send("Next task")
+        """
+        return self._state == AdapterState.IDLE
+
+    async def stream_response(self) -> AsyncIterator[str]:
+        """Stream response chunks from Claude Code.
+
+        Yields:
+            Response chunks as they become available
+
+        Example:
+            >>> async for chunk in adapter.stream_response():
+            ...     print(chunk, end='', flush=True)
+        """
+        last_len = 0
+
+        while self._state == AdapterState.PROCESSING:
+            # Capture current output
+            output = self.orchestrator.capture_output(self.pane_target, lines=100)
+
+            # Get new output since last check and add to buffer
+            new_output = self._get_new_output(output)
+            if new_output:
+                self._output_buffer += new_output
+
+            # Yield new chunk if buffer grew
+            if len(self._output_buffer) > last_len:
+                chunk = self._output_buffer[last_len:]
+                last_len = len(self._output_buffer)
+                yield chunk
+
+            # Check if complete using RuntimeAdapter
+            parsed = self.runtime_adapter.parse_response(output)
+            if parsed.is_complete:
+                self._state = AdapterState.IDLE
+                logger.debug("Streaming complete (idle detected)")
+                break
+
+            await asyncio.sleep(self.poll_interval)
+
+    def _get_new_output(self, current: str) -> str:
+        """Get only new output since last capture.
+
+        Args:
+            current: Current output from tmux pane
+
+        Returns:
+            New output that hasn't been seen before
+        """
+        if current == self._last_output:
+            return ""
+
+        # Find where new content starts
+        if self._last_output and current.startswith(self._last_output):
+            new = current[len(self._last_output) :]
+        else:
+            new = current
+
+        self._last_output = current
+        return new
+
+    def _build_response(
+        self,
+        parsed: "ParsedResponse",
+        is_complete: bool,
+    ) -> AdapterResponse:
+        """Build AdapterResponse from ParsedResponse.
+
+        Args:
+            parsed: ParsedResponse from RuntimeAdapter
+            is_complete: Whether response is complete
+
+        Returns:
+            AdapterResponse with metadata
+        """
+        # TODO: Extract tool uses and files modified from content
+        # This would require additional parsing patterns in RuntimeAdapter
+        # For now, return basic response
+
+        return AdapterResponse(
+            content=parsed.content,
+            state=self._state,
+            tool_uses=None,  # Future: extract from content
+            files_modified=None,  # Future: extract from content
+            is_complete=is_complete,
+        )

claude_mpm/commander/adapters/example_usage.py

@@ -0,0 +1,310 @@
+"""Example usage of multi-runtime adapter architecture.
+
+This module demonstrates how to use the adapter registry and
+individual adapters for different AI coding runtimes.
+"""
+
+import logging
+from typing import Optional
+
+from claude_mpm.commander.adapters import (
+    AdapterRegistry,
+    AuggieAdapter,
+    ClaudeCodeAdapter,
+    CodexAdapter,
+    MPMAdapter,
+    RuntimeAdapter,
+    RuntimeCapability,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+def example_registry_usage() -> None:
+    """Demonstrate adapter registry usage."""
+    print("\n" + "=" * 60)
+    print("ADAPTER REGISTRY USAGE")
+    print("=" * 60 + "\n")
+
+    # List all registered adapters
+    registered = AdapterRegistry.list_registered()
+    print(f"Registered adapters: {registered}")
+
+    # Detect available runtimes on system
+    available = AdapterRegistry.detect_available()
+    print(f"Available runtimes: {available}")
+
+    # Get default adapter (best available)
+    default_adapter = AdapterRegistry.get_default()
+    if default_adapter:
+        print(f"\nDefault adapter: {default_adapter.name}")
+        print(f"Capabilities: {default_adapter.capabilities}")
+    else:
+        print("\nNo adapters available on this system")
+
+    # Get specific adapter
+    mpm_adapter = AdapterRegistry.get("mpm")
+    if mpm_adapter:
+        print(f"\nMPM adapter available: {mpm_adapter.name}")
+    else:
+        print("\nMPM adapter not available")
+
+    # Check if specific runtime is available
+    if AdapterRegistry.is_available("claude-code"):
+        print("\nClaude Code is available")
+    else:
+        print("\nClaude Code is NOT available")
+
+
+def example_adapter_capabilities() -> None:
+    """Demonstrate checking adapter capabilities."""
+    print("\n" + "=" * 60)
+    print("ADAPTER CAPABILITIES")
+    print("=" * 60 + "\n")
+
+    adapters = [
+        ClaudeCodeAdapter(),
+        AuggieAdapter(),
+        CodexAdapter(),
+        MPMAdapter(),
+    ]
+
+    for adapter in adapters:
+        print(f"\n{adapter.name.upper()} Adapter:")
+        print(
+            f"  Command: {adapter.runtime_info.command if adapter.runtime_info else 'N/A'}"
+        )
+
+        # Check for specific capabilities
+        info = adapter.runtime_info
+        if info:
+            print(f"  Supports agents: {info.supports_agents}")
+            print(f"  Instruction file: {info.instruction_file or 'None'}")
+
+            # Check for advanced features
+            if RuntimeCapability.AGENT_DELEGATION in info.capabilities:
+                print("  ✓ Agent delegation supported")
+            else:
+                print("  ✗ Agent delegation NOT supported")
+
+            if RuntimeCapability.HOOKS in info.capabilities:
+                print("  ✓ Lifecycle hooks supported")
+            else:
+                print("  ✗ Lifecycle hooks NOT supported")
+
+            if RuntimeCapability.MCP_TOOLS in info.capabilities:
+                print("  ✓ MCP tools supported")
+            else:
+                print("  ✗ MCP tools NOT supported")
+
+            if RuntimeCapability.SKILLS in info.capabilities:
+                print("  ✓ Skills supported")
+            else:
+                print("  ✗ Skills NOT supported")
+
+            if RuntimeCapability.MONITOR in info.capabilities:
+                print("  ✓ Real-time monitoring supported")
+            else:
+                print("  ✗ Real-time monitoring NOT supported")
+
+
+def example_build_commands() -> None:
+    """Demonstrate building launch commands."""
+    print("\n" + "=" * 60)
+    print("BUILD LAUNCH COMMANDS")
+    print("=" * 60 + "\n")
+
+    project_path = "/home/user/my-project"
+    agent_prompt = "You are a Python expert specializing in FastAPI and async code."
+
+    adapters = [
+        ClaudeCodeAdapter(),
+        AuggieAdapter(),
+        CodexAdapter(),
+        MPMAdapter(),
+    ]
+
+    for adapter in adapters:
+        print(f"\n{adapter.name.upper()}:")
+
+        # Basic launch command
+        cmd = adapter.build_launch_command(project_path)
+        print(f"  Basic: {cmd}")
+
+        # With agent prompt
+        cmd_with_prompt = adapter.build_launch_command(project_path, agent_prompt)
+        print(f"  With prompt: {cmd_with_prompt}")
+
+
+def example_inject_instructions() -> None:
+    """Demonstrate injecting custom instructions."""
+    print("\n" + "=" * 60)
+    print("INJECT CUSTOM INSTRUCTIONS")
+    print("=" * 60 + "\n")
+
+    instructions = """You are a senior Python engineer.
+Follow PEP 8 strictly.
+Write comprehensive tests for all code.
+Use type hints everywhere."""
+
+    adapters = [
+        ClaudeCodeAdapter(),
+        AuggieAdapter(),
+        CodexAdapter(),
+        MPMAdapter(),
+    ]
+
+    for adapter in adapters:
+        print(f"\n{adapter.name.upper()}:")
+
+        cmd = adapter.inject_instructions(instructions)
+        if cmd:
+            print(f"  Command: {cmd}")
+        else:
+            print("  Not supported")
+
+
+def example_inject_agent_context() -> None:
+    """Demonstrate injecting agent context."""
+    print("\n" + "=" * 60)
+    print("INJECT AGENT CONTEXT")
+    print("=" * 60 + "\n")
+
+    agent_id = "eng-001"
+    context = {
+        "role": "Engineer",
+        "specialty": "Backend Python",
+        "task": "Implement API endpoints",
+    }
+
+    adapters = [
+        ClaudeCodeAdapter(),
+        AuggieAdapter(),
+        CodexAdapter(),
+        MPMAdapter(),
+    ]
+
+    for adapter in adapters:
+        print(f"\n{adapter.name.upper()}:")
+
+        cmd = adapter.inject_agent_context(agent_id, context)
+        if cmd:
+            print(f"  Command: {cmd[:100]}...")
+        else:
+            print("  Not supported")
+
+
+def example_parse_response() -> None:
+    """Demonstrate parsing runtime output."""
+    print("\n" + "=" * 60)
+    print("PARSE RUNTIME OUTPUT")
+    print("=" * 60 + "\n")
+
+    # Simulate different output scenarios
+    outputs = {
+        "idle": "File created successfully.\n> ",
+        "error": "Error: File not found: config.py\n> ",
+        "question": "Should I proceed with the changes? (y/n)?",
+        "processing": "Processing your request...",
+    }
+
+    adapter = ClaudeCodeAdapter()
+
+    for scenario, output in outputs.items():
+        print(f"\n{scenario.upper()}:")
+        parsed = adapter.parse_response(output)
+        print(f"  Content: {parsed.content[:50]}...")
+        print(f"  Is complete: {parsed.is_complete}")
+        print(f"  Is error: {parsed.is_error}")
+        print(f"  Is question: {parsed.is_question}")
+        if parsed.error_message:
+            print(f"  Error message: {parsed.error_message}")
+        if parsed.question_text:
+            print(f"  Question: {parsed.question_text}")
+
+
+def example_runtime_selection() -> None:
+    """Demonstrate selecting runtime based on requirements."""
+    print("\n" + "=" * 60)
+    print("RUNTIME SELECTION LOGIC")
+    print("=" * 60 + "\n")
+
+    def select_runtime(
+        needs_agents: bool = False, needs_mcp: bool = False
+    ) -> Optional[RuntimeAdapter]:
+        """Select appropriate runtime based on requirements."""
+        # Get all available adapters
+        available = AdapterRegistry.detect_available()
+
+        # Filter by requirements
+        for name in available:
+            adapter = AdapterRegistry.get(name)
+            if not adapter or not adapter.runtime_info:
+                continue
+
+            info = adapter.runtime_info
+
+            # Check agent requirement
+            if needs_agents and not info.supports_agents:
+                continue
+
+            # Check MCP requirement
+            if needs_mcp and RuntimeCapability.MCP_TOOLS not in info.capabilities:
+                continue
+
+            # Found suitable runtime
+            return adapter
+
+        return None
+
+    # Example 1: Need agent delegation
+    print("Requirement: Agent delegation")
+    adapter = select_runtime(needs_agents=True)
+    if adapter:
+        print(f"  Selected: {adapter.name}")
+    else:
+        print("  No suitable runtime found")
+
+    # Example 2: Need MCP tools
+    print("\nRequirement: MCP tools")
+    adapter = select_runtime(needs_mcp=True)
+    if adapter:
+        print(f"  Selected: {adapter.name}")
+    else:
+        print("  No suitable runtime found")
+
+    # Example 3: Need both
+    print("\nRequirement: Agent delegation + MCP tools")
+    adapter = select_runtime(needs_agents=True, needs_mcp=True)
+    if adapter:
+        print(f"  Selected: {adapter.name}")
+    else:
+        print("  No suitable runtime found")
+
+
+def main() -> None:
+    """Run all examples."""
+    print("\n" + "#" * 60)
+    print("# MULTI-RUNTIME ADAPTER ARCHITECTURE EXAMPLES")
+    print("#" * 60)
+
+    # Run all examples
+    example_registry_usage()
+    example_adapter_capabilities()
+    example_build_commands()
+    example_inject_instructions()
+    example_inject_agent_context()
+    example_parse_response()
+    example_runtime_selection()
+
+    print("\n" + "#" * 60)
+    print("# EXAMPLES COMPLETE")
+    print("#" * 60 + "\n")
+
+
+if __name__ == "__main__":
+    main()