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

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/__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,121 @@
+"""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
+
+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
+
+
+@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
+    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
+
+    # 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,133 @@
+"""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,
+        )
+
+
+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,
+        )

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"]

claude_mpm/commander/api/routes/events.py

@@ -0,0 +1,184 @@
+"""REST API routes for event resolution.
+
+Provides HTTP endpoints for resolving events and managing event responses.
+"""
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+
+from ...events.manager import EventManager
+
+router = APIRouter()
+
+
+def get_event_manager() -> EventManager:
+    """Dependency to get the global event manager instance.
+
+    Returns:
+        The global event manager instance
+
+    Raises:
+        RuntimeError: If event manager is not initialized
+    """
+    from ..app import event_manager
+
+    if event_manager is None:
+        raise RuntimeError("Event manager not initialized")
+    return event_manager
+
+
+def get_event_handler():
+    """Dependency to get the global event handler instance.
+
+    Returns:
+        The global event handler instance
+
+    Raises:
+        RuntimeError: If event handler is not initialized
+    """
+    from ..app import event_handler
+
+    if event_handler is None:
+        raise RuntimeError("Event handler not initialized")
+    return event_handler
+
+
+class EventResponse(BaseModel):
+    """Request model for event resolution.
+
+    Attributes:
+        response: User's response to the event
+    """
+
+    response: str
+
+
+class EventResolutionResponse(BaseModel):
+    """Response model for event resolution.
+
+    Attributes:
+        event_id: ID of resolved event
+        status: Resolution status
+        session_resumed: Whether project session was resumed
+    """
+
+    event_id: str
+    status: str
+    session_resumed: bool
+
+
+class PendingEventResponse(BaseModel):
+    """Response model for pending event.
+
+    Attributes:
+        event_id: Unique event identifier
+        project_id: Project that raised this event
+        event_type: Type of event
+        priority: Urgency level
+        status: Current lifecycle status
+        title: Short event summary
+        content: Detailed event message
+        options: For DECISION_NEEDED events, list of choices
+        is_blocking: Whether event blocks progress
+    """
+
+    event_id: str
+    project_id: str
+    event_type: str
+    priority: str
+    status: str
+    title: str
+    content: str
+    options: Optional[List[str]]
+    is_blocking: bool
+
+
+@router.post("/events/{event_id}/resolve", response_model=EventResolutionResponse)
+async def resolve_event(
+    event_id: str,
+    response: EventResponse,
+    event_handler=Depends(get_event_handler),
+) -> EventResolutionResponse:
+    """Resolve an event with user response.
+
+    Marks the event as resolved and resumes the project session if it was
+    paused for this event.
+
+    Args:
+        event_id: ID of event to resolve
+        response: User's response to the event
+
+    Returns:
+        Resolution status and whether session was resumed
+
+    Raises:
+        HTTPException: If event not found (404) or resolution fails (500)
+
+    Example:
+        POST /api/events/evt_123/resolve
+        {
+            "response": "Use authlib for OAuth2"
+        }
+
+        Response:
+        {
+            "event_id": "evt_123",
+            "status": "resolved",
+            "session_resumed": true
+        }
+    """
+    try:
+        session_resumed = await event_handler.resolve_event(event_id, response.response)
+        return EventResolutionResponse(
+            event_id=event_id,
+            status="resolved",
+            session_resumed=session_resumed,
+        )
+    except KeyError as e:
+        raise HTTPException(
+            status_code=404, detail=f"Event not found: {event_id}"
+        ) from e
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to resolve event: {e!s}"
+        ) from e
+
+
+@router.get("/events/pending", response_model=List[PendingEventResponse])
+async def get_pending_events(
+    project_id: Optional[str] = Query(None, description="Filter by project ID"),
+    event_handler=Depends(get_event_handler),
+) -> List[PendingEventResponse]:
+    """Get pending events requiring resolution.
+
+    Returns all unresolved events, optionally filtered by project.
+    Events are sorted by priority (high to low) then created time (old to new).
+
+    Args:
+        project_id: If provided, only return events for this project
+
+    Returns:
+        List of pending events
+
+    Example:
+        GET /api/events/pending
+        GET /api/events/pending?project_id=proj_123
+    """
+    events = await event_handler.get_pending_events(project_id)
+
+    return [
+        PendingEventResponse(
+            event_id=event.id,
+            project_id=event.project_id,
+            event_type=event.type.value,
+            priority=event.priority.value,
+            status=event.status.value,
+            title=event.title,
+            content=event.content,
+            options=event.options,
+            is_blocking=event_handler.is_blocking(event),
+        )
+        for event in events
+    ]