claude-mpm 5.4.96__py3-none-any.whl → 5.6.10__py3-none-any.whl

claude_mpm/commander/api/routes/work.py

@@ -0,0 +1,260 @@
+"""Work queue management endpoints for MPM Commander API.
+
+This module implements REST endpoints for managing work items
+in project work queues.
+"""
+
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+
+from ...models.work import WorkPriority, WorkState
+from ...work import WorkQueue
+from ..errors import ProjectNotFoundError
+from ..schemas import CreateWorkRequest, WorkItemResponse
+
+router = APIRouter()
+
+
+def _get_registry():
+    """Get registry instance from app global."""
+    from ..app import registry
+
+    if registry is None:
+        raise RuntimeError("Registry not initialized")
+    return registry
+
+
+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(project_id: str, work: CreateWorkRequest) -> WorkItemResponse:
+    """Add work item to project queue.
+
+    Args:
+        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()
+
+    # Get project
+    try:
+        project = registry.get(project_id)
+    except ProjectNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+
+    # Get or create work queue for project
+    # Note: In full implementation, this would be managed by ProjectSession
+    # For now, we'll need to integrate with project's work queue
+    # Access or create work queue
+    if not hasattr(project, "_work_queue"):
+        project._work_queue = WorkQueue(project_id)
+
+    queue = project._work_queue
+
+    # 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
+    )
+
+    return _work_item_to_response(work_item)
+
+
+@router.get("/projects/{project_id}/work", response_model=List[WorkItemResponse])
+async def list_work(
+    project_id: str, state: Optional[str] = Query(None, description="Filter by state")
+) -> List[WorkItemResponse]:
+    """List work items for project.
+
+    Args:
+        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()
+
+    # Get project
+    try:
+        project = registry.get(project_id)
+    except ProjectNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+
+    # Get work queue
+    if not hasattr(project, "_work_queue"):
+        project._work_queue = WorkQueue(project_id)
+
+    queue = project._work_queue
+
+    # 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(project_id: str, work_id: str) -> WorkItemResponse:
+    """Get work item details.
+
+    Args:
+        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()
+
+    # Get project
+    try:
+        project = registry.get(project_id)
+    except ProjectNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+
+    # Get work queue
+    if not hasattr(project, "_work_queue"):
+        raise HTTPException(status_code=404, detail="Work queue not found")
+
+    queue = project._work_queue
+
+    # 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(project_id: str, work_id: str) -> dict:
+    """Cancel pending work item.
+
+    Args:
+        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()
+
+    # Get project
+    try:
+        project = registry.get(project_id)
+    except ProjectNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+
+    # Get work queue
+    if not hasattr(project, "_work_queue"):
+        raise HTTPException(status_code=404, detail="Work queue not found")
+
+    queue = project._work_queue
+
+    # 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,182 @@
+"""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
+        name: Optional display name (derived from path if omitted)
+    """
+
+    path: str = Field(..., description="Filesystem path to project")
+    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"]

claude_mpm/commander/chat/cli.py

@@ -0,0 +1,107 @@
+"""Commander CLI entry point."""
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.commander.instance_manager import InstanceManager
+from claude_mpm.commander.llm.openrouter_client import (
+    OpenRouterClient,
+    OpenRouterConfig,
+)
+from claude_mpm.commander.llm.summarizer import OutputSummarizer
+from claude_mpm.commander.proxy.formatter import OutputFormatter
+from claude_mpm.commander.proxy.output_handler import OutputHandler
+from claude_mpm.commander.proxy.relay import OutputRelay
+from claude_mpm.commander.session.manager import SessionManager
+from claude_mpm.commander.tmux_orchestrator import TmuxOrchestrator
+
+from .repl import CommanderREPL
+
+logger = logging.getLogger(__name__)
+
+
+async def run_commander(
+    port: int = 8765,
+    state_dir: Optional[Path] = None,
+) -> None:
+    """Run Commander in interactive mode.
+
+    Args:
+        port: Port for internal services (unused currently).
+        state_dir: Directory for state persistence (optional).
+
+    Example:
+        >>> asyncio.run(run_commander())
+        # Starts interactive Commander REPL
+    """
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    # Initialize components
+    logger.info("Initializing Commander...")
+
+    # Create tmux orchestrator
+    orchestrator = TmuxOrchestrator()
+
+    # Create instance manager
+    instance_manager = InstanceManager(orchestrator)
+
+    # Create session manager
+    session_manager = SessionManager()
+
+    # Try to initialize LLM client (optional)
+    llm_client: Optional[OpenRouterClient] = None
+    try:
+        config = OpenRouterConfig()
+        llm_client = OpenRouterClient(config)
+        logger.info("LLM client initialized")
+    except ValueError as e:
+        logger.warning(f"LLM client not available: {e}")
+        logger.warning("Output summarization will be disabled")
+
+    # Create output relay (optional)
+    output_relay: Optional[OutputRelay] = None
+    if llm_client:
+        try:
+            summarizer = OutputSummarizer(llm_client)
+            handler = OutputHandler(orchestrator, summarizer)
+            formatter = OutputFormatter()
+            output_relay = OutputRelay(handler, formatter)
+            logger.info("Output relay initialized")
+        except Exception as e:
+            logger.warning(f"Output relay setup failed: {e}")
+
+    # Create REPL
+    repl = CommanderREPL(
+        instance_manager=instance_manager,
+        session_manager=session_manager,
+        output_relay=output_relay,
+        llm_client=llm_client,
+    )
+
+    # Run REPL
+    try:
+        await repl.run()
+    except KeyboardInterrupt:
+        logger.info("Commander interrupted by user")
+    except Exception as e:
+        logger.error(f"Commander error: {e}", exc_info=True)
+    finally:
+        # Cleanup
+        logger.info("Shutting down Commander...")
+        if output_relay:
+            await output_relay.stop_all()
+
+
+def main() -> None:
+    """Entry point for command-line execution."""
+    asyncio.run(run_commander())
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/commander/chat/commands.py

@@ -0,0 +1,96 @@
+"""Built-in Commander chat commands."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class CommandType(Enum):
+    """Built-in command types."""
+
+    LIST = "list"
+    START = "start"
+    STOP = "stop"
+    CONNECT = "connect"
+    DISCONNECT = "disconnect"
+    STATUS = "status"
+    HELP = "help"
+    EXIT = "exit"
+    INSTANCES = "instances"  # alias for list
+
+
+@dataclass
+class Command:
+    """Parsed command with args."""
+
+    type: CommandType
+    args: list[str]
+    raw: str
+
+
+class CommandParser:
+    """Parses user input into commands."""
+
+    ALIASES = {
+        "ls": CommandType.LIST,
+        "instances": CommandType.LIST,
+        "quit": CommandType.EXIT,
+        "q": CommandType.EXIT,
+    }
+
+    def parse(self, input_text: str) -> Optional[Command]:
+        """Parse input into a Command.
+
+        Returns None if input is not a built-in command (natural language).
+
+        Args:
+            input_text: Raw user input.
+
+        Returns:
+            Command if input is a built-in command, None otherwise.
+
+        Example:
+            >>> parser = CommandParser()
+            >>> cmd = parser.parse("list")
+            >>> cmd.type
+            <CommandType.LIST: 'list'>
+            >>> parser.parse("tell me about the code")
+            None
+        """
+        if not input_text:
+            return None
+
+        parts = input_text.split()
+        command_str = parts[0].lower()
+        args = parts[1:] if len(parts) > 1 else []
+
+        # Check if it's an alias
+        if command_str in self.ALIASES:
+            cmd_type = self.ALIASES[command_str]
+            return Command(type=cmd_type, args=args, raw=input_text)
+
+        # Check if it's a direct command
+        try:
+            cmd_type = CommandType(command_str)
+            return Command(type=cmd_type, args=args, raw=input_text)
+        except ValueError:
+            # Not a built-in command
+            return None
+
+    def is_command(self, input_text: str) -> bool:
+        """Check if input is a built-in command.
+
+        Args:
+            input_text: Raw user input.
+
+        Returns:
+            True if input is a built-in command, False otherwise.
+
+        Example:
+            >>> parser = CommandParser()
+            >>> parser.is_command("list")
+            True
+            >>> parser.is_command("tell me about the code")
+            False
+        """
+        return self.parse(input_text) is not None