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

claude_mpm/commander/api/routes/sessions.py

@@ -0,0 +1,226 @@
+"""Session management endpoints for MPM Commander API.
+
+This module implements REST endpoints for creating and managing tool sessions
+(Claude Code, Aider, etc.) within projects.
+"""
+
+import logging
+import subprocess  # nosec B404 - needed for tmux error handling
+import uuid
+from typing import List
+
+from fastapi import APIRouter, Request, Response
+
+from ...models import ToolSession
+from ..errors import (
+    InvalidRuntimeError,
+    ProjectNotFoundError,
+    SessionNotFoundError,
+    TmuxNoSpaceError,
+)
+from ..schemas import CreateSessionRequest, SessionResponse
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+# Valid runtime adapters (Phase 1: claude-code only)
+VALID_RUNTIMES = {"claude-code"}
+
+
+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 _get_tmux(request: Request):
+    """Get tmux orchestrator instance from app.state."""
+    if not hasattr(request.app.state, "tmux") or request.app.state.tmux is None:
+        raise RuntimeError("Tmux orchestrator not initialized")
+    return request.app.state.tmux
+
+
+def _session_to_response(session: ToolSession) -> SessionResponse:
+    """Convert ToolSession model to SessionResponse schema.
+
+    Args:
+        session: ToolSession instance
+
+    Returns:
+        SessionResponse with session data
+    """
+    return 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,
+    )
+
+
+@router.get("/projects/{project_id}/sessions", response_model=List[SessionResponse])
+async def list_sessions(request: Request, project_id: str) -> List[SessionResponse]:
+    """List all sessions for a project.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        List of session information (may be empty)
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        GET /api/projects/abc-123/sessions
+        Response: [
+            {
+                "id": "sess-456",
+                "project_id": "abc-123",
+                "runtime": "claude-code",
+                "tmux_target": "%1",
+                "status": "running",
+                "created_at": "2025-01-12T10:00:00Z"
+            }
+        ]
+    """
+    registry = _get_registry(request)
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    # Convert sessions dict to list of responses
+    return [_session_to_response(s) for s in project.sessions.values()]
+
+
+@router.post(
+    "/projects/{project_id}/sessions", response_model=SessionResponse, status_code=201
+)
+async def create_session(
+    request: Request, project_id: str, req: CreateSessionRequest
+) -> SessionResponse:
+    """Create a new session for a project.
+
+    Creates a new tmux pane and initializes the specified runtime adapter.
+
+    Args:
+        project_id: Unique project identifier
+        req: Session creation request
+
+    Returns:
+        Newly created session information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+        InvalidRuntimeError: If runtime is not supported
+        TmuxNoSpaceError: If tmux has no space for new pane
+
+    Example:
+        POST /api/projects/abc-123/sessions
+        Body: {
+            "runtime": "claude-code",
+            "agent_prompt": "You are a helpful coding assistant"
+        }
+        Response: {
+            "id": "sess-456",
+            "project_id": "abc-123",
+            "runtime": "claude-code",
+            "tmux_target": "%1",
+            "status": "initializing",
+            "created_at": "2025-01-12T10:00:00Z"
+        }
+    """
+    registry = _get_registry(request)
+    tmux_orch = _get_tmux(request)
+
+    # Validate project exists
+    project = registry.get(project_id)
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    # Validate runtime
+    if req.runtime not in VALID_RUNTIMES:
+        raise InvalidRuntimeError(req.runtime)
+
+    # Generate session ID
+    session_id = str(uuid.uuid4())
+
+    # Create tmux pane for session
+    try:
+        tmux_target = tmux_orch.create_pane(
+            pane_id=f"{project.name}-{req.runtime}",
+            working_dir=project.path,
+        )
+    except subprocess.CalledProcessError as e:
+        stderr = e.stderr.decode() if e.stderr else ""
+        if "no space for new pane" in stderr.lower():
+            raise TmuxNoSpaceError() from None
+        raise  # Re-raise other subprocess errors
+
+    # Create session object
+    session = ToolSession(
+        id=session_id,
+        project_id=project_id,
+        runtime=req.runtime,
+        tmux_target=tmux_target,
+        status="initializing",
+    )
+
+    # Add session to project
+    registry.add_session(project_id, session)
+
+    # TODO: Start runtime adapter in pane (Phase 2)
+    # For Phase 1, session stays in "initializing" state
+
+    return _session_to_response(session)
+
+
+@router.delete("/sessions/{session_id}", status_code=204)
+async def stop_session(request: Request, session_id: str) -> Response:
+    """Stop and remove a session.
+
+    Kills the tmux pane and removes the session from its project.
+
+    Args:
+        session_id: Unique session identifier
+
+    Returns:
+        Empty response with 204 status
+
+    Raises:
+        SessionNotFoundError: If session_id doesn't exist
+
+    Example:
+        DELETE /api/sessions/sess-456
+        Response: 204 No Content
+    """
+    registry = _get_registry(request)
+    tmux_orch = _get_tmux(request)
+
+    # Find session across all projects
+    session = None
+    parent_project_id = None
+
+    for project in registry.list_all():
+        if session_id in project.sessions:
+            session = project.sessions[session_id]
+            parent_project_id = project.id
+            break
+
+    if session is None or parent_project_id is None:
+        raise SessionNotFoundError(session_id)
+
+    # Kill tmux pane
+    try:
+        tmux_orch.kill_pane(session.tmux_target)
+    except Exception as e:
+        # Pane may already be dead, continue with cleanup
+        logger.debug("Failed to kill pane (may already be dead): %s", e)
+
+    # Remove session from project
+    registry.remove_session(parent_project_id, session_id)
+
+    return Response(status_code=204)

claude_mpm/commander/api/routes/work.py

@@ -0,0 +1,296 @@
+"""Work queue management endpoints for MPM Commander API.
+
+This module implements REST endpoints for managing work items
+in project work queues.
+"""
+
+from typing import Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+from ...models.work import WorkPriority, WorkState
+from ...work import WorkQueue
+from ..schemas import CreateWorkRequest, WorkItemResponse
+
+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 _get_work_queues(request: Request) -> Dict:
+    """Get work queues dict from app.state (shared with daemon)."""
+    if (
+        not hasattr(request.app.state, "work_queues")
+        or request.app.state.work_queues is None
+    ):
+        raise RuntimeError("Work queues not initialized")
+    return request.app.state.work_queues
+
+
+def _get_daemon(request: Request):
+    """Get daemon instance from app.state."""
+    if not hasattr(request.app.state, "daemon_instance"):
+        return None
+    return request.app.state.daemon_instance
+
+
+def _work_item_to_response(work_item) -> WorkItemResponse:
+    """Convert WorkItem model to WorkItemResponse schema.
+
+    Args:
+        work_item: WorkItem instance
+
+    Returns:
+        WorkItemResponse with all work item data
+    """
+    return WorkItemResponse(
+        id=work_item.id,
+        project_id=work_item.project_id,
+        content=work_item.content,
+        state=work_item.state.value,
+        priority=work_item.priority.value,
+        created_at=work_item.created_at,
+        started_at=work_item.started_at,
+        completed_at=work_item.completed_at,
+        result=work_item.result,
+        error=work_item.error,
+        depends_on=work_item.depends_on,
+        metadata=work_item.metadata,
+    )
+
+
+@router.post("/projects/{project_id}/work", response_model=WorkItemResponse)
+async def add_work(
+    request: Request, project_id: str, work: CreateWorkRequest
+) -> WorkItemResponse:
+    """Add work item to project queue.
+
+    Args:
+        request: FastAPI request (for accessing app.state)
+        project_id: Project identifier
+        work: Work item creation request
+
+    Returns:
+        Created work item
+
+    Raises:
+        HTTPException: 404 if project not found
+
+    Example:
+        POST /api/projects/proj-123/work
+        Request: {
+            "content": "Implement OAuth2 authentication",
+            "priority": 3,
+            "depends_on": ["work-abc"]
+        }
+        Response: {
+            "id": "work-xyz",
+            "project_id": "proj-123",
+            "content": "Implement OAuth2 authentication",
+            "state": "queued",
+            "priority": 3,
+            ...
+        }
+    """
+    registry = _get_registry(request)
+    work_queues = _get_work_queues(request)
+    daemon = _get_daemon(request)
+
+    # Get project
+    project = registry.get(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+
+    # Get or create work queue (shared with daemon)
+    import logging
+
+    logger = logging.getLogger(__name__)
+    logger.info(
+        f"work_queues dict id: {id(work_queues)}, keys: {list(work_queues.keys())}"
+    )
+
+    if project_id not in work_queues:
+        logger.info(f"Creating new work queue for {project_id}")
+        work_queues[project_id] = WorkQueue(project_id)
+        logger.info(f"After creation, work_queues keys: {list(work_queues.keys())}")
+
+    queue = work_queues[project_id]
+
+    # Convert priority int to enum
+    priority = WorkPriority(work.priority)
+
+    # Add work item
+    work_item = queue.add(
+        content=work.content, priority=priority, depends_on=work.depends_on
+    )
+
+    # Ensure daemon has a session for this project (creates if needed)
+    if daemon and not daemon.sessions.get(project_id):
+        # Session creation will be handled by daemon's main loop
+        # when it detects work in the queue
+        pass
+
+    return _work_item_to_response(work_item)
+
+
+@router.get("/projects/{project_id}/work", response_model=List[WorkItemResponse])
+async def list_work(
+    request: Request,
+    project_id: str,
+    state: Optional[str] = Query(None, description="Filter by state"),
+) -> List[WorkItemResponse]:
+    """List work items for project.
+
+    Args:
+        request: FastAPI request (for accessing app.state)
+        project_id: Project identifier
+        state: Optional state filter (pending, queued, in_progress, etc.)
+
+    Returns:
+        List of work items (may be empty)
+
+    Raises:
+        HTTPException: 404 if project not found, 400 if invalid state
+
+    Example:
+        GET /api/projects/proj-123/work
+        Response: [
+            {"id": "work-1", "state": "queued", ...},
+            {"id": "work-2", "state": "in_progress", ...}
+        ]
+
+        GET /api/projects/proj-123/work?state=queued
+        Response: [
+            {"id": "work-1", "state": "queued", ...}
+        ]
+    """
+    registry = _get_registry(request)
+    work_queues = _get_work_queues(request)
+
+    # Get project
+    project = registry.get(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+
+    # Get work queue (shared with daemon)
+    if project_id not in work_queues:
+        # Return empty list if no work queue exists yet
+        return []
+
+    queue = work_queues[project_id]
+
+    # Parse state filter
+    state_filter = None
+    if state:
+        try:
+            state_filter = WorkState(state)
+        except ValueError as e:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid state: {state}. "
+                f"Valid states: {[s.value for s in WorkState]}",
+            ) from e
+
+    # List work items
+    items = queue.list(state=state_filter)
+
+    return [_work_item_to_response(item) for item in items]
+
+
+@router.get("/projects/{project_id}/work/{work_id}", response_model=WorkItemResponse)
+async def get_work(request: Request, project_id: str, work_id: str) -> WorkItemResponse:
+    """Get work item details.
+
+    Args:
+        request: FastAPI request (for accessing app.state)
+        project_id: Project identifier
+        work_id: Work item identifier
+
+    Returns:
+        Work item details
+
+    Raises:
+        HTTPException: 404 if project or work item not found
+
+    Example:
+        GET /api/projects/proj-123/work/work-xyz
+        Response: {
+            "id": "work-xyz",
+            "project_id": "proj-123",
+            "state": "in_progress",
+            ...
+        }
+    """
+    registry = _get_registry(request)
+    work_queues = _get_work_queues(request)
+
+    # Get project
+    project = registry.get(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+
+    # Get work queue (shared with daemon)
+    if project_id not in work_queues:
+        raise HTTPException(status_code=404, detail="Work queue not found")
+
+    queue = work_queues[project_id]
+
+    # Get work item
+    work_item = queue.get(work_id)
+    if not work_item:
+        raise HTTPException(status_code=404, detail=f"Work item {work_id} not found")
+
+    return _work_item_to_response(work_item)
+
+
+@router.post("/projects/{project_id}/work/{work_id}/cancel")
+async def cancel_work(request: Request, project_id: str, work_id: str) -> dict:
+    """Cancel pending work item.
+
+    Args:
+        request: FastAPI request (for accessing app.state)
+        project_id: Project identifier
+        work_id: Work item identifier
+
+    Returns:
+        Success message
+
+    Raises:
+        HTTPException: 404 if project/work not found, 400 if invalid state
+
+    Example:
+        POST /api/projects/proj-123/work/work-xyz/cancel
+        Response: {"status": "cancelled", "id": "work-xyz"}
+    """
+    registry = _get_registry(request)
+    work_queues = _get_work_queues(request)
+
+    # Get project
+    project = registry.get(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+
+    # Get work queue (shared with daemon)
+    if project_id not in work_queues:
+        raise HTTPException(status_code=404, detail="Work queue not found")
+
+    queue = work_queues[project_id]
+
+    # Cancel work item
+    if not queue.cancel(work_id):
+        work_item = queue.get(work_id)
+        if not work_item:
+            raise HTTPException(
+                status_code=404, detail=f"Work item {work_id} not found"
+            )
+        raise HTTPException(
+            status_code=400,
+            detail=f"Cannot cancel work item in state {work_item.state.value}",
+        )
+
+    return {"status": "cancelled", "id": work_id}

claude_mpm/commander/api/schemas.py

@@ -0,0 +1,186 @@
+"""Pydantic request/response schemas for MPM Commander API.
+
+This module defines all request and response models for the REST API,
+providing type safety and automatic validation.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+# Request Models
+
+
+class RegisterProjectRequest(BaseModel):
+    """Request to register a new project.
+
+    Attributes:
+        path: Filesystem path to project directory
+        project_id: Optional project identifier (UUID generated if omitted)
+        name: Optional display name (derived from path if omitted)
+    """
+
+    path: str = Field(..., description="Filesystem path to project")
+    project_id: Optional[str] = Field(
+        None, description="Project identifier (UUID generated if omitted)"
+    )
+    name: Optional[str] = Field(
+        None, description="Display name (derived from path if omitted)"
+    )
+
+
+class CreateSessionRequest(BaseModel):
+    """Request to create a new tool session.
+
+    Attributes:
+        runtime: Runtime adapter to use (e.g., "claude-code")
+        agent_prompt: Optional custom system prompt for the agent
+    """
+
+    runtime: str = Field("claude-code", description="Runtime adapter to use")
+    agent_prompt: Optional[str] = Field(None, description="Custom system prompt")
+
+
+class SendMessageRequest(BaseModel):
+    """Request to send a message to a project.
+
+    Attributes:
+        content: Message content
+        session_id: Target session ID (uses active session if omitted)
+    """
+
+    content: str = Field(..., description="Message content")
+    session_id: Optional[str] = Field(
+        None, description="Target session (uses active if omitted)"
+    )
+
+
+# Response Models
+
+
+class SessionResponse(BaseModel):
+    """Session information response.
+
+    Attributes:
+        id: Unique session identifier
+        project_id: Parent project ID
+        runtime: Runtime adapter name
+        tmux_target: Tmux pane target identifier
+        status: Current session status
+        created_at: Session creation timestamp
+    """
+
+    id: str
+    project_id: str
+    runtime: str
+    tmux_target: str
+    status: str
+    created_at: datetime
+
+
+class ProjectResponse(BaseModel):
+    """Project information response.
+
+    Attributes:
+        id: Unique project identifier
+        path: Absolute filesystem path
+        name: Display name
+        state: Current project state
+        state_reason: Optional state reason (e.g., error message)
+        sessions: List of active sessions
+        pending_events_count: Number of pending events
+        last_activity: Last activity timestamp
+        created_at: Project registration timestamp
+    """
+
+    id: str
+    path: str
+    name: str
+    state: str
+    state_reason: Optional[str]
+    sessions: List[SessionResponse]
+    pending_events_count: int
+    last_activity: datetime
+    created_at: datetime
+
+
+class MessageResponse(BaseModel):
+    """Conversation message response.
+
+    Attributes:
+        id: Unique message identifier
+        role: Message sender role (user, assistant, system, tool)
+        content: Message content
+        session_id: Associated session ID (if from tool)
+        timestamp: Message creation timestamp
+    """
+
+    id: str
+    role: str
+    content: str
+    session_id: Optional[str]
+    timestamp: datetime
+
+
+class CreateWorkRequest(BaseModel):
+    """Request to create a work item.
+
+    Attributes:
+        content: Task/message to execute
+        priority: Priority level (1-4, where 4 is CRITICAL)
+        depends_on: Optional list of work item IDs that must complete first
+    """
+
+    content: str = Field(..., description="Task/message to execute")
+    priority: int = Field(
+        2,
+        description="Priority level (1=LOW, 2=MEDIUM, 3=HIGH, 4=CRITICAL)",
+        ge=1,
+        le=4,
+    )
+    depends_on: Optional[List[str]] = Field(
+        None, description="Work item IDs that must complete first"
+    )
+
+
+class WorkItemResponse(BaseModel):
+    """Work item information response.
+
+    Attributes:
+        id: Unique work item identifier
+        project_id: Parent project ID
+        content: Task/message content
+        state: Current state (pending, queued, in_progress, blocked, completed, failed, cancelled)
+        priority: Priority level (1-4)
+        created_at: Creation timestamp
+        started_at: Execution start timestamp (if started)
+        completed_at: Completion timestamp (if completed/failed)
+        result: Result message (if completed)
+        error: Error message (if failed)
+        depends_on: List of dependency work item IDs
+        metadata: Additional structured data
+    """
+
+    id: str
+    project_id: str
+    content: str
+    state: str
+    priority: int
+    created_at: datetime
+    started_at: Optional[datetime]
+    completed_at: Optional[datetime]
+    result: Optional[str]
+    error: Optional[str]
+    depends_on: List[str]
+    metadata: dict
+
+
+class ErrorResponse(BaseModel):
+    """Error response with structured error information.
+
+    Attributes:
+        error: Error details with code and message
+    """
+
+    error: dict  # {code: str, message: str}

claude_mpm/commander/chat/__init__.py

@@ -0,0 +1,7 @@
+"""Commander chat interface."""
+
+from .cli import run_commander
+from .commands import Command, CommandParser, CommandType
+from .repl import CommanderREPL
+
+__all__ = ["Command", "CommandParser", "CommandType", "CommanderREPL", "run_commander"]