claude-task-master 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

claude_task_master/mailbox/merger.py

@@ -0,0 +1,163 @@
+"""Message merger for combining multiple mailbox messages.
+
+This module provides the MessageMerger class that consolidates multiple
+messages into a single coherent change request for plan updates.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import MailboxMessage
+
+
+class MessageMerger:
+    """Merges multiple mailbox messages into a single change request.
+
+    The merger consolidates messages by:
+    1. Sorting by priority (highest first)
+    2. Grouping by sender (optional)
+    3. Formatting into a structured change request
+
+    This is deterministic (no AI) to ensure consistent behavior.
+    """
+
+    def merge(self, messages: list[MailboxMessage]) -> str:
+        """Merge multiple messages into a single change request.
+
+        Args:
+            messages: List of MailboxMessage objects to merge.
+
+        Returns:
+            A formatted string suitable for plan update prompts.
+
+        Raises:
+            ValueError: If messages list is empty.
+        """
+        if not messages:
+            raise ValueError("Cannot merge empty message list")
+
+        if len(messages) == 1:
+            return self._format_single_message(messages[0])
+
+        return self._format_multiple_messages(messages)
+
+    def _format_single_message(self, message: MailboxMessage) -> str:
+        """Format a single message as a change request.
+
+        Args:
+            message: The message to format.
+
+        Returns:
+            Formatted change request string.
+        """
+        parts = [message.content]
+
+        # Add sender attribution if not anonymous
+        if message.sender != "anonymous":
+            parts.append(f"\n\n---\n*From: {message.sender}*")
+
+        return "".join(parts)
+
+    def _format_multiple_messages(self, messages: list[MailboxMessage]) -> str:
+        """Format multiple messages as a consolidated change request.
+
+        Args:
+            messages: List of messages to format (already sorted by priority).
+
+        Returns:
+            Formatted change request with all messages.
+        """
+        header = self._build_header(messages)
+        body = self._build_body(messages)
+        footer = self._build_footer(len(messages))
+
+        return f"{header}\n\n{body}\n\n{footer}"
+
+    def _build_header(self, messages: list[MailboxMessage]) -> str:
+        """Build the header section for merged messages.
+
+        Args:
+            messages: List of messages.
+
+        Returns:
+            Header string with count and timestamp.
+        """
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            f"**Consolidated Change Requests ({len(messages)} messages)**\n"
+            f"*Processed at: {timestamp}*"
+        )
+
+    def _build_body(self, messages: list[MailboxMessage]) -> str:
+        """Build the body section with all message contents.
+
+        Args:
+            messages: List of messages to include.
+
+        Returns:
+            Formatted body with numbered messages.
+        """
+        parts = []
+
+        for i, msg in enumerate(messages, 1):
+            priority_label = self._get_priority_label(msg.priority)
+            sender_info = f" (from {msg.sender})" if msg.sender != "anonymous" else ""
+
+            parts.append(f"### Request {i}{priority_label}{sender_info}\n\n{msg.content}")
+
+        return "\n\n---\n\n".join(parts)
+
+    def _get_priority_label(self, priority: int) -> str:
+        """Get a human-readable priority label.
+
+        Args:
+            priority: Priority value (0-3).
+
+        Returns:
+            Priority label string or empty string for normal priority.
+        """
+        labels = {
+            0: " [LOW]",
+            1: "",  # Normal - no label
+            2: " [HIGH]",
+            3: " [URGENT]",
+        }
+        return labels.get(priority, "")
+
+    def _build_footer(self, count: int) -> str:
+        """Build the footer with instructions.
+
+        Args:
+            count: Number of messages.
+
+        Returns:
+            Footer string with instructions.
+        """
+        return (
+            f"**Please address ALL {count} change requests above in the plan update.**\n"
+            f"Prioritize URGENT requests first, then HIGH, then others.\n"
+            f"If requests conflict, prefer higher-priority requests."
+        )
+
+    def merge_to_single_content(self, messages: list[MailboxMessage]) -> str:
+        """Merge messages to just the content strings combined.
+
+        A simpler alternative to merge() that just concatenates content.
+
+        Args:
+            messages: List of messages.
+
+        Returns:
+            Combined content string.
+        """
+        if not messages:
+            raise ValueError("Cannot merge empty message list")
+
+        if len(messages) == 1:
+            return messages[0].content
+
+        contents = [msg.content for msg in messages]
+        return "\n\n---\n\n".join(contents)

claude_task_master/mailbox/models.py

@@ -0,0 +1,95 @@
+"""Pydantic models for the mailbox system.
+
+This module defines the data models used by the mailbox:
+- MailboxMessage: A single message with metadata
+- MailboxState: The overall mailbox state for persistence
+- MessagePreview: A shortened version for status display
+"""
+
+from datetime import datetime
+from enum import IntEnum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class Priority(IntEnum):
+    """Message priority levels.
+
+    Higher values indicate higher priority.
+    Messages with higher priority are processed first.
+    """
+
+    LOW = 0
+    NORMAL = 1
+    HIGH = 2
+    URGENT = 3
+
+
+class MailboxMessage(BaseModel):
+    """A message in the mailbox.
+
+    Attributes:
+        id: Unique message identifier (auto-generated UUID).
+        sender: Identifier of the message sender.
+        content: The message content/body.
+        priority: Message priority level (higher = more important).
+        timestamp: When the message was created.
+        metadata: Optional additional metadata.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    sender: str = "anonymous"
+    content: str
+    priority: Priority = Priority.NORMAL
+    timestamp: datetime = Field(default_factory=datetime.now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_preview(self, max_length: int = 100) -> "MessagePreview":
+        """Convert to a preview for status display.
+
+        Args:
+            max_length: Maximum length of the content preview.
+
+        Returns:
+            MessagePreview with truncated content.
+        """
+        preview_content = self.content
+        if len(preview_content) > max_length:
+            preview_content = preview_content[: max_length - 3] + "..."
+
+        return MessagePreview(
+            id=self.id,
+            sender=self.sender,
+            content_preview=preview_content,
+            priority=self.priority,
+            timestamp=self.timestamp,
+        )
+
+
+class MessagePreview(BaseModel):
+    """A shortened preview of a message.
+
+    Used in status responses to avoid sending full message content.
+    """
+
+    id: str
+    sender: str
+    content_preview: str
+    priority: Priority
+    timestamp: datetime
+
+
+class MailboxState(BaseModel):
+    """Persistent state of the mailbox.
+
+    Attributes:
+        messages: List of messages currently in the mailbox.
+        last_checked: When the mailbox was last checked/processed.
+        total_messages_received: Total count of messages ever received.
+    """
+
+    messages: list[MailboxMessage] = Field(default_factory=list)
+    last_checked: datetime | None = None
+    total_messages_received: int = 0

claude_task_master/mailbox/storage.py

@@ -0,0 +1,209 @@
+"""Mailbox storage for persistent message storage.
+
+This module provides the MailboxStorage class that handles:
+- Adding messages to the mailbox
+- Retrieving messages (with optional clearing)
+- Atomic file operations for safe concurrent access
+- Persistence to .claude-task-master/mailbox.json
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+
+from .models import MailboxMessage, MailboxState, Priority
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class MailboxStorageError(Exception):
+    """Base exception for mailbox storage errors."""
+
+    pass
+
+
+class MailboxStorage:
+    """Manages mailbox message storage.
+
+    Persists messages to a JSON file with atomic writes for safety.
+    Supports concurrent access through file-based locking.
+
+    Attributes:
+        storage_path: Path to the mailbox.json file.
+    """
+
+    def __init__(self, state_dir: Path | None = None):
+        """Initialize mailbox storage.
+
+        Args:
+            state_dir: Directory for state files. Defaults to .claude-task-master.
+        """
+        self.state_dir = state_dir or Path(".claude-task-master")
+        self.storage_path = self.state_dir / "mailbox.json"
+
+    def _ensure_dir(self) -> None:
+        """Ensure the state directory exists."""
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+    def _load_state(self) -> MailboxState:
+        """Load the current mailbox state from disk.
+
+        Returns:
+            MailboxState with current messages, or empty state if file doesn't exist.
+        """
+        if not self.storage_path.exists():
+            return MailboxState()
+
+        try:
+            with open(self.storage_path) as f:
+                data = json.load(f)
+            return MailboxState(**data)
+        except (json.JSONDecodeError, ValidationError):
+            # Corrupted file - return empty state
+            return MailboxState()
+
+    def _save_state(self, state: MailboxState) -> None:
+        """Save mailbox state atomically.
+
+        Uses temp file + rename for atomic writes.
+
+        Args:
+            state: The MailboxState to save.
+        """
+        self._ensure_dir()
+
+        # Write to temp file, then rename for atomicity
+        fd, temp_path = tempfile.mkstemp(dir=self.state_dir, prefix=".mailbox_", suffix=".json")
+        try:
+            with open(fd, "w") as f:
+                # Use model_dump with mode='json' for proper datetime serialization
+                json.dump(state.model_dump(mode="json"), f, indent=2)
+            shutil.move(temp_path, self.storage_path)
+        except Exception:
+            # Clean up temp file on error
+            try:
+                Path(temp_path).unlink()
+            except Exception:
+                pass
+            raise
+
+    def add_message(
+        self,
+        content: str,
+        sender: str = "anonymous",
+        priority: int | Priority = Priority.NORMAL,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Add a message to the mailbox.
+
+        Args:
+            content: The message content.
+            sender: Identifier of the sender (default: "anonymous").
+            priority: Message priority (0=low, 1=normal, 2=high, 3=urgent).
+            metadata: Optional additional metadata dict.
+
+        Returns:
+            The ID of the created message.
+        """
+        # Convert int to Priority enum if needed
+        if isinstance(priority, int):
+            priority = Priority(priority)
+
+        message = MailboxMessage(
+            content=content,
+            sender=sender,
+            priority=priority,
+            metadata=metadata or {},
+        )
+
+        state = self._load_state()
+        state.messages.append(message)
+        state.total_messages_received += 1
+        self._save_state(state)
+
+        return message.id
+
+    def get_messages(self) -> list[MailboxMessage]:
+        """Get all messages without removing them.
+
+        Returns:
+            List of messages sorted by priority (highest first), then timestamp.
+        """
+        state = self._load_state()
+        # Sort by priority (descending) then timestamp (ascending)
+        return sorted(state.messages, key=lambda m: (-m.priority, m.timestamp))
+
+    def get_and_clear(self) -> list[MailboxMessage]:
+        """Get all messages and remove them atomically.
+
+        This is the primary method for processing messages - it ensures
+        no message is lost or processed twice.
+
+        Returns:
+            List of messages sorted by priority (highest first), then timestamp.
+        """
+        state = self._load_state()
+        messages = sorted(state.messages, key=lambda m: (-m.priority, m.timestamp))
+
+        # Clear messages and update last_checked
+        state.messages = []
+        state.last_checked = datetime.now()
+        self._save_state(state)
+
+        return messages
+
+    def clear(self) -> int:
+        """Clear all messages from the mailbox.
+
+        Returns:
+            The number of messages that were removed.
+        """
+        state = self._load_state()
+        count = len(state.messages)
+
+        state.messages = []
+        state.last_checked = datetime.now()
+        self._save_state(state)
+
+        return count
+
+    def count(self) -> int:
+        """Get the number of messages in the mailbox.
+
+        Returns:
+            Number of pending messages.
+        """
+        state = self._load_state()
+        return len(state.messages)
+
+    def get_status(self) -> dict[str, Any]:
+        """Get mailbox status information.
+
+        Returns:
+            Dict with count, previews, last_checked, and total_received.
+        """
+        state = self._load_state()
+        messages = sorted(state.messages, key=lambda m: (-m.priority, m.timestamp))
+
+        return {
+            "count": len(messages),
+            "previews": [m.to_preview().model_dump(mode="json") for m in messages],
+            "last_checked": (state.last_checked.isoformat() if state.last_checked else None),
+            "total_messages_received": state.total_messages_received,
+        }
+
+    def exists(self) -> bool:
+        """Check if the mailbox storage file exists.
+
+        Returns:
+            True if mailbox.json exists.
+        """
+        return self.storage_path.exists()

claude_task_master/mcp/server.py

@@ -63,6 +63,12 @@ PauseTaskResult = tools.PauseTaskResult
 StopTaskResult = tools.StopTaskResult
 ResumeTaskResult = tools.ResumeTaskResult
 UpdateConfigResult = tools.UpdateConfigResult
+SendMessageResult = tools.SendMessageResult
+MailboxStatusResult = tools.MailboxStatusResult
+ClearMailboxResult = tools.ClearMailboxResult
+CloneRepoResult = tools.CloneRepoResult
+SetupRepoResult = tools.SetupRepoResult
+PlanRepoResult = tools.PlanRepoResult
 
 
 # =============================================================================
@@ -348,6 +354,183 @@ def create_server(
             state_dir=state_dir,
         )
 
+    # =============================================================================
+    # Mailbox Tool Wrappers
+    # =============================================================================
+
+    @mcp.tool()
+    def send_message(
+        content: str,
+        sender: str = "anonymous",
+        priority: int = 1,
+        state_dir: str | None = None,
+    ) -> dict[str, Any]:
+        """Send a message to the claudetm mailbox.
+
+        Messages are processed after the current task completes. Multiple messages
+        are merged into a single change request that updates the plan before
+        continuing work.
+
+        Use this to send instructions, feedback, or change requests to a running
+        claudetm instance from external systems or other AI agents.
+
+        Args:
+            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.
+            state_dir: Optional custom state directory path.
+
+        Returns:
+            Dictionary containing the message_id on success, or error info.
+
+        Example:
+            send_message("Please also add unit tests for the new feature")
+            send_message("URGENT: Fix the security bug first", priority=3)
+        """
+        return tools.send_message(work_dir, content, sender, priority, state_dir)
+
+    @mcp.tool()
+    def check_mailbox(state_dir: str | None = None) -> dict[str, Any]:
+        """Check the status of the claudetm mailbox.
+
+        Returns the number of pending messages and previews of each.
+        Use this to see what messages are waiting to be processed.
+
+        Args:
+            state_dir: Optional custom state directory path.
+
+        Returns:
+            Dictionary containing mailbox status with message previews.
+        """
+        return tools.check_mailbox(work_dir, state_dir)
+
+    @mcp.tool()
+    def clear_mailbox(state_dir: str | None = None) -> dict[str, Any]:
+        """Clear all messages from the claudetm mailbox.
+
+        Use this to discard all pending messages without processing them.
+
+        Args:
+            state_dir: Optional custom state directory path.
+
+        Returns:
+            Dictionary indicating success and number of messages cleared.
+        """
+        return tools.clear_mailbox(work_dir, state_dir)
+
+    # =============================================================================
+    # Repo Setup Tool Wrappers
+    # =============================================================================
+
+    @mcp.tool()
+    def clone_repo(
+        url: str,
+        target_dir: str | None = None,
+        branch: str | None = None,
+    ) -> dict[str, Any]:
+        """Clone a git repository to the workspace.
+
+        Clones the repository to ~/workspace/claude-task-master/{project-name}
+        by default, or to a custom target directory if specified. This is the
+        first step in setting up a new development environment for AI developers.
+
+        Args:
+            url: Git repository URL (HTTPS or SSH format).
+                Examples: https://github.com/user/repo.git or git@github.com:user/repo.git
+            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.
+
+        Returns:
+            Dictionary containing:
+            - success: Whether clone was successful
+            - message: Human-readable result message
+            - repo_url: The cloned repository URL
+            - target_dir: The directory where repo was cloned
+            - branch: The branch checked out (if specified)
+            - error: Error details on failure
+
+        Example:
+            clone_repo("https://github.com/anthropics/claude-code")
+            clone_repo("git@github.com:user/project.git", branch="develop")
+            clone_repo("https://github.com/user/project", target_dir="/custom/path")
+        """
+        return tools.clone_repo(url, target_dir, branch)
+
+    @mcp.tool()
+    def setup_repo(
+        repo_dir: str,
+    ) -> dict[str, Any]:
+        """Set 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.)
+
+        Supports Python projects (pyproject.toml, setup.py, requirements.txt)
+        and Node.js projects (package.json). Uses uv for Python dependency
+        management when available, falling back to standard venv + pip.
+
+        Args:
+            repo_dir: Path to the cloned repository directory to set up.
+
+        Returns:
+            Dictionary containing:
+            - success: Whether setup completed successfully
+            - message: Human-readable result message
+            - work_dir: The directory that was set up
+            - steps_completed: List of completed setup steps
+            - venv_path: Path to virtual environment (Python projects)
+            - dependencies_installed: Whether dependencies were installed
+            - setup_scripts_run: List of setup scripts that were executed
+            - error: Error details on failure
+
+        Example:
+            setup_repo("/home/user/workspace/claude-task-master/my-project")
+            setup_repo("~/workspace/claude-task-master/python-app")
+        """
+        return tools.setup_repo(repo_dir)
+
+    @mcp.tool()
+    def plan_repo(
+        repo_dir: str,
+        goal: str,
+        model: str = "opus",
+    ) -> dict[str, Any]:
+        """Create a plan for a repository without executing any work.
+
+        This is a plan-only mode that reads the codebase using read-only tools
+        (Read, Glob, Grep) and outputs a structured plan with tasks and success
+        criteria. No changes are made to the repository.
+
+        Use this after `clone_repo` and `setup_repo` to plan work before execution,
+        or to get a plan for a new goal in an existing repository.
+
+        Args:
+            repo_dir: Path to the repository directory to plan for.
+            goal: The goal/task description to plan for. Be specific about
+                what you want to accomplish.
+            model: Model to use for planning (default: "opus" for best quality).
+                Options: "opus", "sonnet", "haiku".
+
+        Returns:
+            Dictionary containing:
+            - success: Whether planning completed successfully
+            - message: Human-readable result message
+            - work_dir: The directory that was planned for
+            - goal: The goal that was planned for
+            - plan: The generated task plan (markdown with checkboxes)
+            - criteria: Success criteria for verifying completion
+            - run_id: Unique identifier for this planning session
+            - error: Error details on failure
+
+        Example:
+            plan_repo("/home/user/workspace/project", "Add user authentication")
+            plan_repo("~/workspace/my-app", "Fix the login bug", model="sonnet")
+        """
+        return tools.plan_repo(repo_dir, goal, model)
+
     # =============================================================================
     # Resource Wrappers
     # =============================================================================