claude-mpm 5.4.22__py3-none-any.whl → 5.6.34__py3-none-any.whl

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__)

claude_mpm/commander/api/routes/messages.py

@@ -0,0 +1,148 @@
+"""Message and thread management endpoints for MPM Commander API.
+
+This module implements REST endpoints for sending messages and retrieving
+conversation threads for projects.
+"""
+
+import uuid
+from typing import List
+
+from fastapi import APIRouter, Request
+
+from ...models import ThreadMessage
+from ..errors import ProjectNotFoundError
+from ..schemas import MessageResponse, SendMessageRequest
+
+router = APIRouter()
+
+
+def _get_registry(request: Request):
+    """Get registry instance from app.state."""
+    if not hasattr(request.app.state, "registry") or request.app.state.registry is None:
+        raise RuntimeError("Registry not initialized")
+    return request.app.state.registry
+
+
+def _message_to_response(message: ThreadMessage) -> MessageResponse:
+    """Convert ThreadMessage model to MessageResponse schema.
+
+    Args:
+        message: ThreadMessage instance
+
+    Returns:
+        MessageResponse with message data
+    """
+    return MessageResponse(
+        id=message.id,
+        role=message.role,
+        content=message.content,
+        session_id=message.session_id,
+        timestamp=message.timestamp,
+    )
+
+
+@router.get("/projects/{project_id}/thread", response_model=List[MessageResponse])
+async def get_thread(request: Request, project_id: str) -> List[MessageResponse]:
+    """Get conversation thread for a project.
+
+    Returns all messages in chronological order.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        List of messages in thread (may be empty)
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        GET /api/projects/abc-123/thread
+        Response: [
+            {
+                "id": "msg-1",
+                "role": "user",
+                "content": "Fix the login bug",
+                "session_id": null,
+                "timestamp": "2025-01-12T10:00:00Z"
+            },
+            {
+                "id": "msg-2",
+                "role": "assistant",
+                "content": "I'll investigate the login issue",
+                "session_id": "sess-456",
+                "timestamp": "2025-01-12T10:00:30Z"
+            }
+        ]
+    """
+    registry = _get_registry(request)
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    # Convert thread messages to responses
+    return [_message_to_response(m) for m in project.thread]
+
+
+@router.post(
+    "/projects/{project_id}/messages", response_model=MessageResponse, status_code=201
+)
+async def send_message(
+    request: Request, project_id: str, req: SendMessageRequest
+) -> MessageResponse:
+    """Send a message to a project's active session.
+
+    Adds message to conversation thread and sends to specified or active session.
+
+    Args:
+        project_id: Unique project identifier
+        req: Message request with content and optional session_id
+
+    Returns:
+        Created message information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        POST /api/projects/abc-123/messages
+        Body: {
+            "content": "Fix the login bug",
+            "session_id": "sess-456"
+        }
+        Response: {
+            "id": "msg-1",
+            "role": "user",
+            "content": "Fix the login bug",
+            "session_id": "sess-456",
+            "timestamp": "2025-01-12T10:00:00Z"
+        }
+    """
+    registry = _get_registry(request)
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    # Generate message ID
+    message_id = str(uuid.uuid4())
+
+    # Create message object
+    message = ThreadMessage(
+        id=message_id,
+        role="user",
+        content=req.content,
+        session_id=req.session_id,
+    )
+
+    # Add to project thread
+    project.thread.append(message)
+
+    # Update last activity
+    registry.touch(project_id)
+
+    # TODO: Send to session/runtime adapter (Phase 2)
+    # For Phase 1, message is just stored in thread
+
+    return _message_to_response(message)

claude_mpm/commander/api/routes/projects.py

@@ -0,0 +1,271 @@
+"""Project management endpoints for MPM Commander API.
+
+This module implements REST endpoints for registering, listing, and managing
+projects in the MPM Commander.
+"""
+
+from pathlib import Path
+from typing import List
+
+from fastapi import APIRouter, Request, Response
+
+from ...models import ProjectState
+from ..errors import InvalidPathError, ProjectAlreadyExistsError, ProjectNotFoundError
+from ..schemas import ProjectResponse, RegisterProjectRequest, SessionResponse
+
+router = APIRouter()
+
+
+def _get_registry(request: Request):
+    """Get registry instance from app.state."""
+    if not hasattr(request.app.state, "registry") or request.app.state.registry is None:
+        raise RuntimeError("Registry not initialized")
+    return request.app.state.registry
+
+
+def _project_to_response(project) -> ProjectResponse:
+    """Convert Project model to ProjectResponse schema.
+
+    Args:
+        project: Project instance
+
+    Returns:
+        ProjectResponse with all project data
+    """
+    # Convert sessions dict to list of SessionResponse
+    session_responses = [
+        SessionResponse(
+            id=session.id,
+            project_id=session.project_id,
+            runtime=session.runtime,
+            tmux_target=session.tmux_target,
+            status=session.status,
+            created_at=session.created_at,
+        )
+        for session in project.sessions.values()
+    ]
+
+    return ProjectResponse(
+        id=project.id,
+        path=project.path,
+        name=project.name,
+        state=project.state.value,
+        state_reason=project.state_reason,
+        sessions=session_responses,
+        pending_events_count=len(project.pending_events),
+        last_activity=project.last_activity,
+        created_at=project.created_at,
+    )
+
+
+@router.get("/projects", response_model=List[ProjectResponse])
+async def list_projects(request: Request) -> List[ProjectResponse]:
+    """List all registered projects.
+
+    Returns:
+        List of project information (may be empty)
+
+    Example:
+        GET /api/projects
+        Response: [
+            {
+                "id": "abc-123",
+                "path": "/Users/user/projects/my-app",
+                "name": "my-app",
+                "state": "idle",
+                "state_reason": null,
+                "sessions": [],
+                "pending_events_count": 0,
+                "last_activity": "2025-01-12T10:00:00Z",
+                "created_at": "2025-01-12T09:00:00Z"
+            }
+        ]
+    """
+    registry = _get_registry(request)
+    projects = registry.list_all()
+    return [_project_to_response(p) for p in projects]
+
+
+@router.get("/projects/{project_id}", response_model=ProjectResponse)
+async def get_project(request: Request, project_id: str) -> ProjectResponse:
+    """Get project details by ID.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Project information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        GET /api/projects/abc-123
+        Response: {
+            "id": "abc-123",
+            "path": "/Users/user/projects/my-app",
+            "name": "my-app",
+            "state": "idle",
+            ...
+        }
+    """
+    registry = _get_registry(request)
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    return _project_to_response(project)
+
+
+@router.post("/projects", response_model=ProjectResponse, status_code=201)
+async def register_project(
+    request: Request, req: RegisterProjectRequest
+) -> ProjectResponse:
+    """Register a new project.
+
+    Args:
+        req: Registration request with path and optional name
+
+    Returns:
+        Newly registered project information
+
+    Raises:
+        InvalidPathError: If path doesn't exist or isn't a directory
+        ProjectAlreadyExistsError: If path already registered
+
+    Example:
+        POST /api/projects
+        Body: {
+            "path": "/Users/user/projects/my-app",
+            "name": "My App"
+        }
+        Response: {
+            "id": "abc-123",
+            "path": "/Users/user/projects/my-app",
+            "name": "My App",
+            "state": "idle",
+            ...
+        }
+    """
+    registry = _get_registry(request)
+
+    # Validate path exists and is directory
+    path_obj = Path(req.path)
+    if not path_obj.exists() or not path_obj.is_dir():
+        raise InvalidPathError(req.path)
+
+    try:
+        project = registry.register(req.path, req.name, req.project_id)
+        return _project_to_response(project)
+    except ValueError as e:
+        # Registry raises ValueError for duplicate registration
+        error_msg = str(e)
+        if "already registered" in error_msg.lower():
+            raise ProjectAlreadyExistsError(req.path) from e
+        # Re-raise as InvalidPathError for other validation errors
+        raise InvalidPathError(req.path) from e
+
+
+@router.delete("/projects/{project_id}", status_code=204)
+async def unregister_project(request: Request, project_id: str) -> Response:
+    """Unregister a project.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Empty response with 204 status
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        DELETE /api/projects/abc-123
+        Response: 204 No Content
+    """
+    registry = _get_registry(request)
+
+    try:
+        registry.unregister(project_id)
+        return Response(status_code=204)
+    except KeyError as e:
+        raise ProjectNotFoundError(project_id) from e
+
+
+@router.post("/projects/{project_id}/pause", response_model=ProjectResponse)
+async def pause_project(request: Request, project_id: str) -> ProjectResponse:
+    """Pause a project.
+
+    Sets project state to PAUSED to prevent automatic work processing.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Updated project information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        POST /api/projects/abc-123/pause
+        Response: {
+            "id": "abc-123",
+            "state": "paused",
+            "state_reason": "Manually paused via API",
+            ...
+        }
+    """
+    registry = _get_registry(request)
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    registry.update_state(
+        project_id,
+        ProjectState.PAUSED,
+        reason="Manually paused via API",
+    )
+
+    return _project_to_response(project)
+
+
+@router.post("/projects/{project_id}/resume", response_model=ProjectResponse)
+async def resume_project(request: Request, project_id: str) -> ProjectResponse:
+    """Resume a paused project.
+
+    Sets project state back to IDLE to allow work processing.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Updated project information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        POST /api/projects/abc-123/resume
+        Response: {
+            "id": "abc-123",
+            "state": "idle",
+            "state_reason": "Resumed via API",
+            ...
+        }
+    """
+    registry = _get_registry(request)
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    registry.update_state(
+        project_id,
+        ProjectState.IDLE,
+        reason="Resumed via API",
+    )
+
+    return _project_to_response(project)