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

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

claude_mpm/commander/chat/cli.py

@@ -0,0 +1,149 @@
+"""Commander CLI entry point."""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.commander.env_loader import load_env
+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
+
+# Load environment variables at module import
+load_env()
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CommanderCLIConfig:
+    """Configuration for Commander CLI mode.
+
+    Attributes:
+        summarize_responses: Whether to use LLM to summarize instance responses
+        port: Port for internal services (reserved for future use)
+        state_dir: Directory for state persistence (optional)
+
+    Example:
+        >>> config = CommanderCLIConfig(summarize_responses=False)
+    """
+
+    summarize_responses: bool = True
+    port: int = 8765
+    state_dir: Optional[Path] = None
+
+
+async def run_commander(
+    port: int = 8765,
+    state_dir: Optional[Path] = None,
+    config: Optional[CommanderCLIConfig] = None,
+) -> None:
+    """Run Commander in interactive mode.
+
+    Args:
+        port: Port for internal services (unused currently).
+        state_dir: Directory for state persistence (optional).
+        config: Commander CLI configuration (optional, uses defaults if None).
+
+    Example:
+        >>> asyncio.run(run_commander())
+        # Starts interactive Commander REPL
+        >>> config = CommanderCLIConfig(summarize_responses=False)
+        >>> asyncio.run(run_commander(config=config))
+        # Starts Commander without response summarization
+    """
+    # Use default config if not provided
+    if config is None:
+        config = CommanderCLIConfig(port=port, state_dir=state_dir)
+
+    # Setup logging - suppress noisy libraries
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+    # Suppress httpx request logging (very verbose)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+    # 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:
+        llm_config = OpenRouterConfig()
+        llm_client = OpenRouterClient(llm_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:
+            # Only create summarizer if summarize_responses is enabled
+            summarizer = None
+            if config.summarize_responses:
+                summarizer = OutputSummarizer(llm_client)
+                logger.info("Response summarization enabled")
+            else:
+                logger.info("Response summarization disabled")
+
+            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()