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

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

claude_mpm/commander/api/routes/inbox.py

@@ -0,0 +1,171 @@
+"""REST API routes for inbox system.
+
+Provides HTTP endpoints for querying and managing the event inbox.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+
+from ...inbox import Inbox
+from ...models.events import EventPriority, EventType
+
+router = APIRouter()
+
+
+def get_inbox() -> Inbox:
+    """Dependency to get the global inbox instance.
+
+    Returns:
+        The global inbox instance
+
+    Raises:
+        RuntimeError: If inbox is not initialized
+    """
+    from ..app import inbox
+
+    if inbox is None:
+        raise RuntimeError("Inbox not initialized")
+    return inbox
+
+
+class InboxItemResponse(BaseModel):
+    """Response model for inbox item.
+
+    Attributes:
+        event_id: Unique event identifier
+        project_id: Project that raised this event
+        project_name: Human-readable project name
+        project_path: Filesystem path to project
+        event_type: Type of event (decision, error, status, etc.)
+        priority: Urgency level (critical, high, normal, low, info)
+        status: Current lifecycle status
+        title: Short event summary
+        content: Detailed event message
+        options: For DECISION_NEEDED events, list of choices
+        age_display: Human-readable age (e.g., "5m ago")
+        created_at: When event was created
+        session_runtime: Optional session runtime identifier
+    """
+
+    event_id: str
+    project_id: str
+    project_name: str
+    project_path: str
+    event_type: str
+    priority: str
+    status: str
+    title: str
+    content: str
+    options: Optional[List[str]]
+    age_display: str
+    created_at: datetime
+    session_runtime: Optional[str]
+
+
+class InboxCountsResponse(BaseModel):
+    """Response model for inbox counts.
+
+    Attributes:
+        critical: Count of CRITICAL priority events
+        high: Count of HIGH priority events
+        normal: Count of NORMAL priority events
+        low: Count of LOW priority events
+        info: Count of INFO priority events
+        total: Total count of all pending events
+    """
+
+    critical: int
+    high: int
+    normal: int
+    low: int
+    info: int
+    total: int
+
+
+@router.get("/inbox", response_model=List[InboxItemResponse])
+async def get_inbox_items(
+    limit: int = Query(50, ge=1, le=100, description="Maximum items to return"),
+    offset: int = Query(0, ge=0, description="Number of items to skip"),
+    priority: Optional[str] = Query(None, description="Filter by priority level"),
+    project_id: Optional[str] = Query(None, description="Filter by project ID"),
+    event_type: Optional[str] = Query(None, description="Filter by event type"),
+    inbox: Inbox = Depends(get_inbox),
+) -> List[InboxItemResponse]:
+    """Get inbox items with optional filtering and pagination.
+
+    Returns a list of inbox items sorted by priority (high to low) then
+    created time (old to new). Supports filtering by priority, project,
+    and event type.
+
+    Args:
+        limit: Maximum number of items to return (1-100, default: 50)
+        offset: Number of items to skip for pagination (default: 0)
+        priority: Filter by priority (critical, high, normal, low, info)
+        project_id: Filter by project ID
+        event_type: Filter by event type (decision_needed, error, etc.)
+
+    Returns:
+        List of inbox items matching the filters
+
+    Example:
+        GET /api/inbox?limit=20&priority=critical
+        GET /api/inbox?project_id=proj_123&event_type=error
+        GET /api/inbox?offset=50&limit=50  # Pagination
+    """
+    # Parse enum values if provided
+    pri = EventPriority(priority) if priority else None
+    evt = EventType(event_type) if event_type else None
+
+    items = inbox.get_items(
+        limit=limit,
+        offset=offset,
+        priority=pri,
+        project_id=project_id,
+        event_type=evt,
+    )
+
+    return [
+        InboxItemResponse(
+            event_id=item.event.id,
+            project_id=item.event.project_id,
+            project_name=item.project_name,
+            project_path=item.project_path,
+            event_type=item.event.type.value,
+            priority=item.event.priority.value,
+            status=item.event.status.value,
+            title=item.event.title,
+            content=item.event.content,
+            options=item.event.options,
+            age_display=item.age_display,
+            created_at=item.event.created_at,
+            session_runtime=item.session_runtime,
+        )
+        for item in items
+    ]
+
+
+@router.get("/inbox/counts", response_model=InboxCountsResponse)
+async def get_inbox_counts(
+    project_id: Optional[str] = Query(None, description="Filter by project ID"),
+    inbox: Inbox = Depends(get_inbox),
+) -> InboxCountsResponse:
+    """Get count of pending events by priority.
+
+    Returns summary statistics showing how many events exist at each
+    priority level. Optionally filtered to a specific project.
+
+    Args:
+        project_id: If provided, only count events for this project
+
+    Returns:
+        Breakdown of event counts by priority
+
+    Example:
+        GET /api/inbox/counts
+        GET /api/inbox/counts?project_id=proj_123
+    """
+    counts = inbox.get_counts(project_id)
+    return InboxCountsResponse(**counts.__dict__)