claude-task-master 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

claude_task_master/__init__.py

@@ -3,5 +3,5 @@
 Uses Claude Agent SDK to keep Claude working until a goal is achieved.
 """
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"
 __all__ = ["__version__"]

claude_task_master/api/models.py

@@ -9,6 +9,9 @@ Request Models:
 - ResumeRequest: Resume a paused/blocked task
 - ConfigUpdateRequest: Update task configuration
 - TaskInitRequest: Initialize a new task
+- CloneRepoRequest: Clone a git repository to the workspace
+- SetupRepoRequest: Set up a cloned repository for development
+- PlanRepoRequest: Create a plan for a repository (read-only)
 
 Response Models:
 - TaskStatusResponse: Full task status information
@@ -19,17 +22,26 @@ Response Models:
 - ContextResponse: Accumulated context/learnings
 - HealthResponse: Server health status
 - ErrorResponse: Standard error response
+- CloneRepoResponse: Result of cloning a repository
+- SetupRepoResponse: Result of setting up a repository
+- PlanRepoResponse: Result of planning for a repository
 
 Usage:
     from claude_task_master.api.models import (
         PauseRequest,
         TaskStatusResponse,
         ErrorResponse,
+        CloneRepoRequest,
+        CloneRepoResponse,
     )
 
     @app.post("/control/pause", response_model=ControlResponse)
     async def pause_task(request: PauseRequest):
         ...
+
+    @app.post("/repo/clone", response_model=CloneRepoResponse)
+    async def clone_repo(request: CloneRepoRequest):
+        ...
 """
 
 from __future__ import annotations
@@ -246,6 +258,120 @@ class TaskInitRequest(BaseModel):
     )
 
 
+# =============================================================================
+# Repo Setup Request Models
+# =============================================================================
+
+
+class CloneRepoRequest(BaseModel):
+    """Request model for cloning a git repository.
+
+    Clones a repository to the workspace for AI developer environments.
+    Default target is ~/workspace/claude-task-master/{repo-name}.
+
+    Attributes:
+        url: Git repository URL (HTTPS or SSH format).
+        target_dir: Optional custom target directory path.
+            If not provided, defaults to ~/workspace/claude-task-master/{repo-name}.
+        branch: Optional branch to checkout after cloning.
+    """
+
+    url: str = Field(
+        ...,
+        min_length=1,
+        max_length=2048,
+        description="Git repository URL (HTTPS or SSH format)",
+        examples=[
+            "https://github.com/user/repo.git",
+            "git@github.com:user/repo.git",
+        ],
+    )
+    target_dir: str | None = Field(
+        default=None,
+        max_length=4096,
+        description="Optional custom target directory path. "
+        "Defaults to ~/workspace/claude-task-master/{repo-name}",
+        examples=[
+            "~/workspace/claude-task-master/my-project",
+            "/home/user/projects/my-app",
+        ],
+    )
+    branch: str | None = Field(
+        default=None,
+        max_length=256,
+        description="Optional branch to checkout after cloning",
+        examples=["main", "develop", "feature/new-feature"],
+    )
+
+
+class SetupRepoRequest(BaseModel):
+    """Request model for setting up a cloned repository for development.
+
+    Detects the project type and performs appropriate setup:
+    - Creates virtual environment (for Python projects)
+    - Installs dependencies (pip, npm, pnpm, yarn, bun)
+    - Runs setup scripts (setup-hooks.sh, setup.sh, etc.)
+
+    Attributes:
+        work_dir: Path to the cloned repository directory.
+    """
+
+    work_dir: str = Field(
+        ...,
+        min_length=1,
+        max_length=4096,
+        description="Path to the cloned repository directory to set up",
+        examples=[
+            "~/workspace/claude-task-master/my-project",
+            "/home/user/projects/my-app",
+        ],
+    )
+
+
+class PlanRepoRequest(BaseModel):
+    """Request model for creating a plan for a repository.
+
+    Creates a plan without executing any work. Uses read-only tools
+    (Read, Glob, Grep) to analyze the codebase and outputs a structured
+    plan with tasks and success criteria.
+
+    Use this after cloning and setting up a repo to plan work before
+    execution, or to get a plan for a new goal in an existing repository.
+
+    Attributes:
+        work_dir: Path to the repository directory to plan for.
+        goal: The goal/task description to plan for.
+        model: Model to use for planning (default: opus for best quality).
+    """
+
+    work_dir: str = Field(
+        ...,
+        min_length=1,
+        max_length=4096,
+        description="Path to the repository directory to plan for",
+        examples=[
+            "~/workspace/claude-task-master/my-project",
+            "/home/user/projects/my-app",
+        ],
+    )
+    goal: str = Field(
+        ...,
+        min_length=1,
+        max_length=10000,
+        description="The goal/task description to plan for",
+        examples=[
+            "Implement user authentication with JWT",
+            "Add dark mode support to the UI",
+            "Fix the database connection pooling issue",
+        ],
+    )
+    model: str = Field(
+        default="opus",
+        pattern="^(opus|sonnet|haiku)$",
+        description="Model to use for planning (opus, sonnet, haiku)",
+    )
+
+
 # =============================================================================
 # Response Models - Nested Components
 # =============================================================================
@@ -551,3 +677,186 @@ class APIInfo(BaseModel):
     version: str
     description: str = "REST API for Claude Task Master task orchestration"
     docs_url: str | None = "/docs"
+
+
+# =============================================================================
+# Mailbox Request/Response Models
+# =============================================================================
+
+
+class SendMailboxMessageRequest(BaseModel):
+    """Request model for sending a message to the mailbox.
+
+    Attributes:
+        content: The message content describing the change request.
+        sender: Identifier of the sender (default: "anonymous").
+        priority: Message priority (0=low, 1=normal, 2=high, 3=urgent).
+        metadata: Optional additional metadata.
+    """
+
+    content: str = Field(
+        ...,
+        min_length=1,
+        max_length=100000,
+        description="The message content describing the change request",
+        examples=["Please also add tests for the new feature", "Prioritize the bug fix"],
+    )
+    sender: str = Field(
+        default="anonymous",
+        max_length=256,
+        description="Identifier of the sender",
+        examples=["supervisor-agent", "user@example.com", "monitoring-system"],
+    )
+    priority: int = Field(
+        default=1,
+        ge=0,
+        le=3,
+        description="Message priority (0=low, 1=normal, 2=high, 3=urgent)",
+    )
+    metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="Optional additional metadata",
+    )
+
+
+class SendMailboxMessageResponse(BaseModel):
+    """Response model for sending a message to the mailbox.
+
+    Attributes:
+        success: Whether the message was sent successfully.
+        message_id: The ID of the created message.
+        message: Human-readable result message.
+        error: Error message if request failed.
+    """
+
+    success: bool
+    message_id: str | None = None
+    message: str | None = None
+    error: str | None = None
+
+
+class MailboxMessagePreview(BaseModel):
+    """Preview of a mailbox message for status responses.
+
+    Attributes:
+        id: Message ID.
+        sender: Message sender.
+        content_preview: Truncated message content.
+        priority: Message priority level.
+        timestamp: When the message was created.
+    """
+
+    id: str
+    sender: str
+    content_preview: str
+    priority: int
+    timestamp: datetime
+
+
+class MailboxStatusResponse(BaseModel):
+    """Response model for mailbox status check.
+
+    Attributes:
+        success: Whether the request succeeded.
+        count: Number of pending messages.
+        messages: List of message previews.
+        last_checked: When the mailbox was last checked.
+        total_messages_received: Total count of messages ever received.
+        error: Error message if request failed.
+    """
+
+    success: bool
+    count: int = 0
+    messages: list[MailboxMessagePreview] = []
+    last_checked: datetime | None = None
+    total_messages_received: int = 0
+    error: str | None = None
+
+
+class ClearMailboxResponse(BaseModel):
+    """Response model for clearing the mailbox.
+
+    Attributes:
+        success: Whether the operation succeeded.
+        messages_cleared: Number of messages that were cleared.
+        message: Human-readable result message.
+        error: Error message if operation failed.
+    """
+
+    success: bool
+    messages_cleared: int = 0
+    message: str | None = None
+    error: str | None = None
+
+
+# =============================================================================
+# Repo Setup Response Models
+# =============================================================================
+
+
+class CloneRepoResponse(BaseModel):
+    """Response model for cloning a git repository.
+
+    Attributes:
+        success: Whether the clone operation succeeded.
+        message: Human-readable result message.
+        repo_url: The repository URL that was cloned.
+        target_dir: The directory where the repo was cloned to.
+        branch: The branch that was checked out (if specified).
+        error: Error message if clone failed.
+    """
+
+    success: bool
+    message: str
+    repo_url: str | None = None
+    target_dir: str | None = None
+    branch: str | None = None
+    error: str | None = None
+
+
+class SetupRepoResponse(BaseModel):
+    """Response model for setting up a repository for development.
+
+    Attributes:
+        success: Whether the setup operation succeeded.
+        message: Human-readable result message.
+        work_dir: The directory that was set up.
+        steps_completed: List of setup steps that were completed.
+        venv_path: Path to the virtual environment (if created).
+        dependencies_installed: Whether dependencies were successfully installed.
+        setup_scripts_run: List of setup scripts that were executed.
+        error: Error message if setup failed.
+    """
+
+    success: bool
+    message: str
+    work_dir: str | None = None
+    steps_completed: list[str] = []
+    venv_path: str | None = None
+    dependencies_installed: bool = False
+    setup_scripts_run: list[str] = []
+    error: str | None = None
+
+
+class PlanRepoResponse(BaseModel):
+    """Response model for creating a plan for a repository.
+
+    Attributes:
+        success: Whether the planning operation succeeded.
+        message: Human-readable result message.
+        work_dir: The repository directory that was analyzed.
+        goal: The goal that was planned for.
+        plan: The generated plan (markdown with task checkboxes).
+        criteria: The success criteria for the plan.
+        run_id: The run ID for the created task state.
+        error: Error message if planning failed.
+    """
+
+    success: bool
+    message: str
+    work_dir: str | None = None
+    goal: str | None = None
+    plan: str | None = None
+    criteria: str | None = None
+    run_id: str | None = None
+    error: str | None = None

claude_task_master/api/routes.py

@@ -15,6 +15,9 @@ Endpoints:
 - POST /control/stop: Stop a running task with optional cleanup
 - POST /control/resume: Resume a paused or blocked task
 - PATCH /config: Update runtime configuration options
+- POST /repo/clone: Clone a git repository to workspace
+- POST /repo/setup: Set up a cloned repository for development
+- POST /repo/plan: Create a plan for a repository (read-only)
 
 Usage:
     from claude_task_master.api.routes import (
@@ -44,15 +47,20 @@ from typing import TYPE_CHECKING, Any
 
 from claude_task_master import __version__
 from claude_task_master.api.models import (
+    ClearMailboxResponse,
     ConfigUpdateRequest,
     ContextResponse,
     ControlResponse,
     ErrorResponse,
     HealthResponse,
     LogsResponse,
+    MailboxMessagePreview,
+    MailboxStatusResponse,
     PlanResponse,
     ProgressResponse,
     ResumeRequest,
+    SendMailboxMessageRequest,
+    SendMailboxMessageResponse,
     StopRequest,
     TaskDeleteResponse,
     TaskInitRequest,
@@ -64,6 +72,7 @@ from claude_task_master.api.models import (
     WebhookStatusInfo,
     WorkflowStage,
 )
+from claude_task_master.api.routes_repo import create_repo_router
 from claude_task_master.api.routes_webhooks import create_webhooks_router
 from claude_task_master.core.agent import ModelType
 from claude_task_master.core.control import ControlManager
@@ -1099,6 +1108,216 @@ def create_task_router() -> APIRouter:
     return router
 
 
+# =============================================================================
+# Mailbox Router (Send, Status, Clear)
+# =============================================================================
+
+
+def create_mailbox_router() -> APIRouter:
+    """Create router for mailbox endpoints.
+
+    These endpoints allow external systems to send messages to the mailbox
+    which will be processed after the current task completes.
+
+    Returns:
+        APIRouter configured with mailbox endpoints.
+
+    Raises:
+        ImportError: If FastAPI is not installed.
+    """
+    if not FASTAPI_AVAILABLE:
+        raise ImportError(
+            "FastAPI not installed. Install with: pip install claude-task-master[api]"
+        )
+
+    router = APIRouter(tags=["Mailbox"])
+
+    @router.post(
+        "/send",
+        response_model=SendMailboxMessageResponse,
+        responses={
+            400: {"model": ErrorResponse, "description": "Invalid request"},
+            500: {"model": ErrorResponse, "description": "Internal server error"},
+        },
+        summary="Send Message to Mailbox",
+        description="Send a message to the claudetm mailbox for processing after the current task.",
+    )
+    async def send_message(
+        request: Request, message_request: SendMailboxMessageRequest
+    ) -> SendMailboxMessageResponse | JSONResponse:
+        """Send a message to the mailbox.
+
+        Messages in the mailbox will be processed after the current task completes.
+        Multiple messages are merged into a single change request that updates
+        the plan before continuing work.
+
+        Args:
+            message_request: The message to send with content, sender, and priority.
+
+        Returns:
+            SendMailboxMessageResponse with message_id on success.
+
+        Raises:
+            400: If the request is invalid.
+            500: If an error occurs sending the message.
+        """
+        from claude_task_master.mailbox import MailboxStorage
+
+        working_dir: Path = getattr(request.app.state, "working_dir", Path.cwd())
+        state_dir = working_dir / ".claude-task-master"
+
+        # Validate content is not empty/whitespace only
+        if not message_request.content.strip():
+            return JSONResponse(
+                status_code=400,
+                content=ErrorResponse(
+                    error="invalid_request",
+                    message="Message content cannot be empty or whitespace only",
+                    suggestion="Provide a non-empty message content",
+                ).model_dump(),
+            )
+
+        try:
+            mailbox = MailboxStorage(state_dir=state_dir)
+            message_id = mailbox.add_message(
+                content=message_request.content.strip(),
+                sender=message_request.sender,
+                priority=message_request.priority,
+                metadata=message_request.metadata or {},
+            )
+
+            return SendMailboxMessageResponse(
+                success=True,
+                message_id=message_id,
+                message=f"Message sent successfully (id: {message_id})",
+            )
+
+        except Exception as e:
+            logger.exception("Error sending message to mailbox")
+            return JSONResponse(
+                status_code=500,
+                content=ErrorResponse(
+                    error="internal_error",
+                    message="Failed to send message to mailbox",
+                    detail=str(e),
+                ).model_dump(),
+            )
+
+    @router.get(
+        "",
+        response_model=MailboxStatusResponse,
+        responses={
+            500: {"model": ErrorResponse, "description": "Internal server error"},
+        },
+        summary="Get Mailbox Status",
+        description="Check the status of the mailbox including message count and previews.",
+    )
+    async def get_mailbox_status(request: Request) -> MailboxStatusResponse | JSONResponse:
+        """Get mailbox status.
+
+        Returns the number of pending messages and previews of each.
+
+        Returns:
+            MailboxStatusResponse with message count and previews.
+
+        Raises:
+            500: If an error occurs checking the mailbox.
+        """
+        from datetime import datetime as dt
+
+        from claude_task_master.mailbox import MailboxStorage
+
+        working_dir: Path = getattr(request.app.state, "working_dir", Path.cwd())
+        state_dir = working_dir / ".claude-task-master"
+
+        try:
+            mailbox = MailboxStorage(state_dir=state_dir)
+            status = mailbox.get_status()
+
+            # Convert preview dicts to MailboxMessagePreview models
+            previews = []
+            for preview_data in status["previews"]:
+                previews.append(
+                    MailboxMessagePreview(
+                        id=preview_data["id"],
+                        sender=preview_data["sender"],
+                        content_preview=preview_data["content_preview"],
+                        priority=preview_data["priority"],
+                        timestamp=dt.fromisoformat(preview_data["timestamp"]),
+                    )
+                )
+
+            # Parse last_checked if present
+            last_checked = None
+            if status["last_checked"]:
+                last_checked = dt.fromisoformat(status["last_checked"])
+
+            return MailboxStatusResponse(
+                success=True,
+                count=status["count"],
+                messages=previews,
+                last_checked=last_checked,
+                total_messages_received=status["total_messages_received"],
+            )
+
+        except Exception as e:
+            logger.exception("Error checking mailbox status")
+            return JSONResponse(
+                status_code=500,
+                content=ErrorResponse(
+                    error="internal_error",
+                    message="Failed to check mailbox status",
+                    detail=str(e),
+                ).model_dump(),
+            )
+
+    @router.delete(
+        "",
+        response_model=ClearMailboxResponse,
+        responses={
+            500: {"model": ErrorResponse, "description": "Internal server error"},
+        },
+        summary="Clear Mailbox",
+        description="Clear all messages from the mailbox.",
+    )
+    async def clear_mailbox(request: Request) -> ClearMailboxResponse | JSONResponse:
+        """Clear all messages from the mailbox.
+
+        Returns:
+            ClearMailboxResponse with number of messages cleared.
+
+        Raises:
+            500: If an error occurs clearing the mailbox.
+        """
+        from claude_task_master.mailbox import MailboxStorage
+
+        working_dir: Path = getattr(request.app.state, "working_dir", Path.cwd())
+        state_dir = working_dir / ".claude-task-master"
+
+        try:
+            mailbox = MailboxStorage(state_dir=state_dir)
+            count = mailbox.clear()
+
+            return ClearMailboxResponse(
+                success=True,
+                messages_cleared=count,
+                message=f"Cleared {count} message(s) from mailbox",
+            )
+
+        except Exception as e:
+            logger.exception("Error clearing mailbox")
+            return JSONResponse(
+                status_code=500,
+                content=ErrorResponse(
+                    error="internal_error",
+                    message="Failed to clear mailbox",
+                    detail=str(e),
+                ).model_dump(),
+            )
+
+    return router
+
+
 # =============================================================================
 # Router Registration
 # =============================================================================
@@ -1129,7 +1348,17 @@ def register_routes(app: FastAPI) -> None:
     webhooks_router = create_webhooks_router()
     app.include_router(webhooks_router, prefix="/webhooks")
 
+    # Create and register mailbox router
+    mailbox_router = create_mailbox_router()
+    app.include_router(mailbox_router, prefix="/mailbox")
+
+    # Create and register repo setup router
+    repo_router = create_repo_router()
+    app.include_router(repo_router, prefix="/repo")
+
     logger.debug("Registered info routes: /status, /plan, /logs, /progress, /context, /health")
     logger.debug("Registered control routes: /control/stop, /control/resume, /config")
     logger.debug("Registered task routes: /task/init, /task")
     logger.debug("Registered webhook routes: /webhooks, /webhooks/{id}, /webhooks/test")
+    logger.debug("Registered mailbox routes: /mailbox/send, /mailbox")
+    logger.debug("Registered repo routes: /repo/clone, /repo/setup, /repo/plan")