claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__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/api/__init__.py

@@ -0,0 +1,16 @@
+"""MPM Commander REST API.
+
+This package provides a FastAPI-based REST API for managing projects,
+sessions, and messages in the MPM Commander.
+
+Example:
+    Run the API server with uvicorn:
+
+    $ uvicorn claude_mpm.commander.api.app:app --host 127.0.0.1 --port 8000
+
+    Access the API documentation at http://127.0.0.1:8000/docs
+"""
+
+from .app import app
+
+__all__ = ["app"]

claude_mpm/commander/api/app.py

@@ -0,0 +1,105 @@
+"""FastAPI application for MPM Commander REST API.
+
+This module defines the main FastAPI application instance with CORS,
+lifecycle management, and route registration.
+"""
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import AsyncGenerator, Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from ..events.manager import EventManager
+from ..inbox import Inbox
+from ..registry import ProjectRegistry
+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]:
+    """Manage application lifecycle.
+
+    Initializes shared resources on startup and cleans up on shutdown.
+
+    Args:
+        app: FastAPI application instance
+
+    Yields:
+        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)
+
+    yield
+
+    # Shutdown
+    # No cleanup needed for Phase 1
+
+
+app = FastAPI(
+    title="MPM Commander API",
+    description="REST API for MPM Commander - Autonomous AI Orchestration",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# CORS for local development
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(projects.router, prefix="/api", tags=["projects"])
+app.include_router(sessions.router, prefix="/api", tags=["sessions"])
+app.include_router(messages.router, prefix="/api", tags=["messages"])
+app.include_router(inbox_routes.router, prefix="/api", tags=["inbox"])
+app.include_router(events.router, prefix="/api", tags=["events"])
+app.include_router(work.router, prefix="/api", tags=["work"])
+
+# Mount static files
+static_path = Path(__file__).parent.parent / "web" / "static"
+app.mount("/static", StaticFiles(directory=str(static_path)), name="static")
+
+
+@app.get("/api/health")
+async def health_check() -> dict:
+    """Health check endpoint.
+
+    Returns:
+        Status and version information
+    """
+    return {"status": "ok", "version": "1.0.0"}
+
+
+@app.get("/")
+async def root() -> FileResponse:
+    """Serve the web UI index page.
+
+    Returns:
+        HTML page for the web UI
+    """
+    return FileResponse(static_path / "index.html")

claude_mpm/commander/api/errors.py

@@ -0,0 +1,112 @@
+"""Error handling for MPM Commander API.
+
+This module defines custom exception classes that map to HTTP error responses
+with structured error codes and messages.
+"""
+
+from fastapi import HTTPException
+
+
+class CommanderAPIError(HTTPException):
+    """Base exception for all Commander API errors.
+
+    Provides consistent error response format with code and message.
+
+    Attributes:
+        code: Machine-readable error code
+        message: Human-readable error message
+        status_code: HTTP status code
+    """
+
+    def __init__(self, code: str, message: str, status_code: int = 400):
+        """Initialize API error.
+
+        Args:
+            code: Error code (e.g., "PROJECT_NOT_FOUND")
+            message: Descriptive error message
+            status_code: HTTP status code (default: 400)
+        """
+        super().__init__(
+            status_code=status_code,
+            detail={"error": {"code": code, "message": message}},
+        )
+
+
+class ProjectNotFoundError(CommanderAPIError):
+    """Project with given ID does not exist."""
+
+    def __init__(self, project_id: str):
+        """Initialize project not found error.
+
+        Args:
+            project_id: The project ID that was not found
+        """
+        super().__init__(
+            "PROJECT_NOT_FOUND",
+            f"Project not found: {project_id}",
+            404,
+        )
+
+
+class ProjectAlreadyExistsError(CommanderAPIError):
+    """Project already registered at given path."""
+
+    def __init__(self, path: str):
+        """Initialize project already exists error.
+
+        Args:
+            path: The path that is already registered
+        """
+        super().__init__(
+            "PROJECT_ALREADY_EXISTS",
+            f"Project already registered: {path}",
+            409,
+        )
+
+
+class InvalidPathError(CommanderAPIError):
+    """Path does not exist or is not a directory."""
+
+    def __init__(self, path: str):
+        """Initialize invalid path error.
+
+        Args:
+            path: The invalid path
+        """
+        super().__init__(
+            "INVALID_PATH",
+            f"Path does not exist or is not a directory: {path}",
+            400,
+        )
+
+
+class SessionNotFoundError(CommanderAPIError):
+    """Session with given ID does not exist."""
+
+    def __init__(self, session_id: str):
+        """Initialize session not found error.
+
+        Args:
+            session_id: The session ID that was not found
+        """
+        super().__init__(
+            "SESSION_NOT_FOUND",
+            f"Session not found: {session_id}",
+            404,
+        )
+
+
+class InvalidRuntimeError(CommanderAPIError):
+    """Invalid runtime adapter specified."""
+
+    def __init__(self, runtime: str):
+        """Initialize invalid runtime error.
+
+        Args:
+            runtime: The invalid runtime name
+        """
+        super().__init__(
+            "INVALID_RUNTIME",
+            f"Invalid runtime: {runtime}",
+            400,
+        )

claude_mpm/commander/api/routes/__init__.py

@@ -0,0 +1,8 @@
+"""API route modules for MPM Commander.
+
+This package exports all route modules for registration with the FastAPI app.
+"""
+
+from . import messages, projects, sessions, work
+
+__all__ = ["messages", "projects", "sessions", "work"]