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

claude_mpm/commander/tmux_orchestrator.py

@@ -0,0 +1,361 @@
+"""Tmux orchestration layer for MPM Commander.
+
+This module wraps tmux commands to manage sessions, panes, and I/O for
+coordinating multiple project-level MPM instances.
+"""
+
+import logging
+import shutil
+import subprocess  # nosec B404 - Required for tmux interaction
+from dataclasses import dataclass
+from typing import Dict, List
+
+logger = logging.getLogger(__name__)
+
+
+class TmuxNotFoundError(Exception):
+    """Raised when tmux is not installed or not found in PATH."""
+
+    def __init__(
+        self,
+        message: str = "tmux not found. Please install tmux to use commander mode.",
+    ):
+        super().__init__(message)
+        self.message = message
+
+
+@dataclass
+class TmuxOrchestrator:
+    """Orchestrate multiple MPM sessions via tmux.
+
+    This class provides a high-level API for managing tmux sessions and panes,
+    enabling the MPM Commander to coordinate multiple project-level MPM instances.
+
+    Attributes:
+        session_name: Name of the tmux session (default: "mpm-commander")
+
+    Example:
+        >>> orchestrator = TmuxOrchestrator()
+        >>> orchestrator.create_session()
+        >>> target = orchestrator.create_pane("proj1", "/path/to/project")
+        >>> orchestrator.send_keys(target, "echo 'Hello from pane'")
+        >>> output = orchestrator.capture_output(target)
+        >>> print(output)
+        >>> orchestrator.kill_session()
+    """
+
+    session_name: str = "mpm-commander"
+
+    def __post_init__(self):
+        """Verify tmux is available on initialization."""
+        if not shutil.which("tmux"):
+            raise TmuxNotFoundError()
+
+    def _run_tmux(
+        self, args: List[str], check: bool = True
+    ) -> subprocess.CompletedProcess:
+        """Execute tmux command and return result.
+
+        Args:
+            args: List of tmux command arguments
+            check: Whether to raise exception on non-zero exit code
+
+        Returns:
+            CompletedProcess with stdout/stderr captured
+
+        Raises:
+            TmuxNotFoundError: If tmux binary not found
+            subprocess.CalledProcessError: If check=True and command fails
+        """
+        cmd = ["tmux"] + args
+        logger.debug(f"Running tmux command: {' '.join(cmd)}")
+
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=check)  # nosec B603
+
+            if result.stdout:
+                logger.debug(f"tmux stdout: {result.stdout.strip()}")
+            if result.stderr:
+                logger.debug(f"tmux stderr: {result.stderr.strip()}")
+
+            return result
+
+        except FileNotFoundError as err:
+            raise TmuxNotFoundError() from err
+
+    def session_exists(self) -> bool:
+        """Check if commander session exists.
+
+        Returns:
+            True if session exists, False otherwise
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> if not orchestrator.session_exists():
+            ...     orchestrator.create_session()
+        """
+        result = self._run_tmux(["has-session", "-t", self.session_name], check=False)
+        exists = result.returncode == 0
+        logger.debug(f"Session '{self.session_name}' exists: {exists}")
+        return exists
+
+    def create_session(self) -> bool:
+        """Create main commander tmux session if not exists.
+
+        Creates a detached tmux session for the commander. If the session
+        already exists, this is a no-op.
+
+        Returns:
+            True if session was created, False if it already existed
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            True
+            >>> orchestrator.create_session()  # Already exists
+            False
+        """
+        if self.session_exists():
+            logger.info(f"Session '{self.session_name}' already exists")
+            return False
+
+        logger.info(f"Creating tmux session '{self.session_name}'")
+        self._run_tmux(
+            [
+                "new-session",
+                "-d",  # Detached
+                "-s",
+                self.session_name,
+                "-n",
+                "commander",  # Window name
+            ]
+        )
+
+        return True
+
+    def create_pane(self, pane_id: str, working_dir: str) -> str:
+        """Create new pane for a project.
+
+        Creates a new split pane in the commander session with the specified
+        working directory.
+
+        Args:
+            pane_id: Identifier for this pane (used in logging)
+            working_dir: Working directory for the pane
+
+        Returns:
+            Tmux target string (pane ID like "%0", "%1", etc.)
+
+        Raises:
+            subprocess.CalledProcessError: If pane creation fails
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            >>> target = orchestrator.create_pane("my-project", "/Users/user/projects/my-project")
+            >>> print(target)
+            %1
+        """
+        logger.info(f"Creating pane '{pane_id}' in {working_dir}")
+
+        # Split window to create new pane
+        self._run_tmux(
+            [
+                "split-window",
+                "-t",
+                self.session_name,
+                "-c",
+                working_dir,  # Working directory
+                "-P",  # Print target of new pane
+                "-F",
+                "#{pane_id}",  # Format: just pane ID
+            ]
+        )
+
+        # Get the newly created pane's target
+        # List panes and get the last one (most recently created)
+        result = self._run_tmux(
+            [
+                "list-panes",
+                "-t",
+                self.session_name,
+                "-F",
+                "#{pane_id}",
+            ]
+        )
+
+        panes = [p for p in result.stdout.strip().split("\n") if p]
+        if not panes:
+            raise RuntimeError(f"Failed to create pane '{pane_id}'")
+
+        # Get last pane ID (most recently created)
+        # Pane ID already includes % prefix and can be used directly as target
+        new_pane_id = panes[-1]
+        target = new_pane_id  # Use pane ID directly as target
+
+        logger.debug(f"Created pane with target: {target}")
+        return target
+
+    def send_keys(self, target: str, keys: str, enter: bool = True) -> bool:
+        """Send keystrokes to a pane.
+
+        Args:
+            target: Tmux target (from create_pane)
+            keys: Keys to send to the pane
+            enter: Whether to send Enter key after keys
+
+        Returns:
+            True if successful
+
+        Raises:
+            subprocess.CalledProcessError: If target pane doesn't exist
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            >>> target = orchestrator.create_pane("proj", "/tmp")
+            >>> orchestrator.send_keys(target, "echo 'Hello'")
+            >>> orchestrator.send_keys(target, "ls -la", enter=False)
+        """
+        logger.debug(f"Sending keys to {target}: {keys}")
+
+        args = ["send-keys", "-t", target, keys]
+        if enter:
+            args.append("Enter")
+
+        self._run_tmux(args)
+        return True
+
+    def capture_output(self, target: str, lines: int = 100) -> str:
+        """Capture recent output from pane.
+
+        Args:
+            target: Tmux target (from create_pane)
+            lines: Number of lines to capture from history
+
+        Returns:
+            Captured output as string
+
+        Raises:
+            subprocess.CalledProcessError: If target pane doesn't exist
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            >>> target = orchestrator.create_pane("proj", "/tmp")
+            >>> orchestrator.send_keys(target, "echo 'Test output'")
+            >>> output = orchestrator.capture_output(target, lines=10)
+            >>> print(output)
+            Test output
+        """
+        logger.debug(f"Capturing {lines} lines from {target}")
+
+        result = self._run_tmux(
+            [
+                "capture-pane",
+                "-t",
+                target,
+                "-p",  # Print to stdout
+                "-S",
+                f"-{lines}",  # Start from N lines back
+            ]
+        )
+
+        return result.stdout
+
+    def list_panes(self) -> List[Dict[str, str]]:
+        """List all panes with their status.
+
+        Returns:
+            List of dicts with pane info (id, path, pid, active)
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            >>> panes = orchestrator.list_panes()
+            >>> for pane in panes:
+            ...     print(f"{pane['id']}: {pane['path']}")
+            %0: /Users/user/projects/proj1
+            %1: /Users/user/projects/proj2
+        """
+        if not self.session_exists():
+            logger.warning(f"Session '{self.session_name}' does not exist")
+            return []
+
+        logger.debug(f"Listing panes for session '{self.session_name}'")
+
+        result = self._run_tmux(
+            [
+                "list-panes",
+                "-t",
+                self.session_name,
+                "-F",
+                "#{pane_id}|#{pane_current_path}|#{pane_pid}|#{pane_active}",
+            ]
+        )
+
+        panes = []
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+
+            parts = line.split("|")
+            if len(parts) >= 4:
+                panes.append(
+                    {
+                        "id": parts[0],
+                        "path": parts[1],
+                        "pid": parts[2],
+                        "active": parts[3] == "1",
+                    }
+                )
+
+        logger.debug(f"Found {len(panes)} panes")
+        return panes
+
+    def kill_pane(self, target: str) -> bool:
+        """Kill a specific pane.
+
+        Args:
+            target: Tmux target (from create_pane or list_panes)
+
+        Returns:
+            True if successful
+
+        Raises:
+            subprocess.CalledProcessError: If target pane doesn't exist
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            >>> target = orchestrator.create_pane("proj", "/tmp")
+            >>> orchestrator.kill_pane(target)
+            True
+        """
+        logger.info(f"Killing pane {target}")
+
+        self._run_tmux(["kill-pane", "-t", target])
+        return True
+
+    def kill_session(self) -> bool:
+        """Kill the entire commander session.
+
+        Returns:
+            True if session was killed, False if it didn't exist
+
+        Example:
+            >>> orchestrator = TmuxOrchestrator()
+            >>> orchestrator.create_session()
+            >>> orchestrator.kill_session()
+            True
+            >>> orchestrator.kill_session()  # Already killed
+            False
+        """
+        if not self.session_exists():
+            logger.info(f"Session '{self.session_name}' does not exist")
+            return False
+
+        logger.info(f"Killing session '{self.session_name}'")
+        self._run_tmux(["kill-session", "-t", self.session_name])
+
+        return True

claude_mpm/commander/web/__init__.py

@@ -0,0 +1 @@
+"""Web UI module for MPM Commander."""

claude_mpm/commander/work/__init__.py

@@ -0,0 +1,30 @@
+"""Work queue and execution module for MPM Commander.
+
+This module provides work queue management and execution capabilities:
+- WorkItem: Data model for work items
+- WorkState: Lifecycle states (PENDING, QUEUED, IN_PROGRESS, etc.)
+- WorkPriority: Priority levels (CRITICAL, HIGH, MEDIUM, LOW)
+- WorkQueue: Queue management with priority and dependencies
+- WorkExecutor: Execution via RuntimeExecutor
+
+Example:
+    >>> from claude_mpm.commander.work import (
+    ...     WorkQueue, WorkExecutor, WorkItem, WorkState, WorkPriority
+    ... )
+    >>> queue = WorkQueue("proj-123")
+    >>> work = queue.add("Implement feature", WorkPriority.HIGH)
+    >>> executor = WorkExecutor(runtime, queue)
+    >>> await executor.execute_next()
+"""
+
+from ..models.work import WorkItem, WorkPriority, WorkState
+from .executor import WorkExecutor
+from .queue import WorkQueue
+
+__all__ = [
+    "WorkExecutor",
+    "WorkItem",
+    "WorkPriority",
+    "WorkQueue",
+    "WorkState",
+]

claude_mpm/commander/work/executor.py

@@ -0,0 +1,207 @@
+"""Work executor for MPM Commander.
+
+This module provides WorkExecutor which executes work items
+via RuntimeExecutor and handles completion/failure callbacks.
+"""
+
+import logging
+from typing import Optional
+
+from ..models.work import WorkItem
+from ..runtime.executor import RuntimeExecutor
+from .queue import WorkQueue
+
+logger = logging.getLogger(__name__)
+
+
+class WorkExecutor:
+    """Executes work items via RuntimeExecutor.
+
+    Coordinates between work queue and runtime execution,
+    handling work item lifecycle and callbacks.
+
+    Attributes:
+        runtime: RuntimeExecutor for spawning and managing tools
+        queue: WorkQueue for work item management
+
+    Example:
+        >>> executor = WorkExecutor(runtime, queue)
+        >>> executed = await executor.execute_next()
+        >>> if executed:
+        ...     print("Work item started")
+    """
+
+    def __init__(self, runtime: RuntimeExecutor, queue: WorkQueue):
+        """Initialize work executor.
+
+        Args:
+            runtime: RuntimeExecutor instance
+            queue: WorkQueue instance
+
+        Raises:
+            ValueError: If runtime or queue is None
+        """
+        if runtime is None:
+            raise ValueError("Runtime cannot be None")
+        if queue is None:
+            raise ValueError("Queue cannot be None")
+
+        self.runtime = runtime
+        self.queue = queue
+
+        logger.debug(f"Initialized WorkExecutor for project {queue.project_id}")
+
+    async def execute_next(self, pane_target: Optional[str] = None) -> bool:
+        """Execute next available work item.
+
+        Gets next work from queue, starts it, and executes via RuntimeExecutor.
+
+        Args:
+            pane_target: Optional tmux pane target for execution
+
+        Returns:
+            True if work was executed, False if queue empty/blocked
+
+        Example:
+            >>> executed = await executor.execute_next("%5")
+            >>> if not executed:
+            ...     print("No work available")
+        """
+        # Get next work item
+        work_item = self.queue.get_next()
+        if not work_item:
+            logger.debug(f"No work available for project {self.queue.project_id}")
+            return False
+
+        # Execute the work item
+        await self.execute(work_item, pane_target)
+        return True
+
+    async def execute(
+        self, work_item: WorkItem, pane_target: Optional[str] = None
+    ) -> None:
+        """Execute a specific work item.
+
+        Marks work as IN_PROGRESS and sends to RuntimeExecutor.
+        Note: This is async but returns immediately - actual execution
+        happens in the background via tmux.
+
+        Args:
+            work_item: WorkItem to execute
+            pane_target: Optional tmux pane target for execution
+
+        Raises:
+            RuntimeError: If execution fails
+
+        Example:
+            >>> await executor.execute(work_item, "%5")
+        """
+        # Mark as in progress
+        if not self.queue.start(work_item.id):
+            logger.error(
+                f"Failed to start work item {work_item.id} - "
+                f"invalid state: {work_item.state.value}"
+            )
+            return
+
+        logger.info(
+            f"Executing work item {work_item.id} for project {work_item.project_id}"
+        )
+
+        try:
+            # Send work content to runtime if pane target provided
+            if pane_target:
+                await self.runtime.send_message(pane_target, work_item.content)
+                logger.info(
+                    f"Work item {work_item.id} sent to pane {pane_target} for execution"
+                )
+            else:
+                logger.warning(
+                    f"No pane target provided for work item {work_item.id}, "
+                    f"work marked as in-progress but not sent to runtime"
+                )
+
+            # Store work item ID in metadata for callback tracking
+            work_item.metadata["execution_started"] = True
+
+        except Exception as e:
+            logger.error(f"Failed to execute work item {work_item.id}: {e}")
+            await self.handle_failure(work_item.id, str(e))
+            raise
+
+    async def handle_completion(
+        self, work_id: str, result: Optional[str] = None
+    ) -> None:
+        """Handle work completion callback.
+
+        Called when RuntimeExecutor completes work successfully.
+
+        Args:
+            work_id: Work item ID that completed
+            result: Optional result message
+
+        Example:
+            >>> await executor.handle_completion("work-123", "Feature implemented")
+        """
+        if self.queue.complete(work_id, result):
+            logger.info(f"Work item {work_id} completed successfully")
+        else:
+            logger.warning(f"Failed to mark work item {work_id} as completed")
+
+    async def handle_failure(self, work_id: str, error: str) -> None:
+        """Handle work failure callback.
+
+        Called when RuntimeExecutor encounters an error.
+
+        Args:
+            work_id: Work item ID that failed
+            error: Error message
+
+        Example:
+            >>> await executor.handle_failure("work-123", "Tool crashed")
+        """
+        if self.queue.fail(work_id, error):
+            logger.error(f"Work item {work_id} failed: {error}")
+        else:
+            logger.warning(f"Failed to mark work item {work_id} as failed")
+
+    async def handle_block(self, work_id: str, reason: str) -> bool:
+        """Handle work being blocked by an event.
+
+        Called when RuntimeMonitor detects a blocking event.
+
+        Args:
+            work_id: Work item ID that is blocked
+            reason: Reason for blocking (e.g., "Waiting for approval")
+
+        Returns:
+            True if work was successfully blocked, False otherwise
+
+        Example:
+            >>> success = await executor.handle_block("work-123", "Decision needed")
+        """
+        if self.queue.block(work_id, reason):
+            logger.info(f"Work item {work_id} blocked: {reason}")
+            return True
+        logger.warning(f"Failed to mark work item {work_id} as blocked")
+        return False
+
+    async def handle_unblock(self, work_id: str) -> bool:
+        """Handle work being unblocked after event resolution.
+
+        Called when EventHandler resolves a blocking event.
+
+        Args:
+            work_id: Work item ID to unblock
+
+        Returns:
+            True if work was successfully unblocked, False otherwise
+
+        Example:
+            >>> success = await executor.handle_unblock("work-123")
+        """
+        if self.queue.unblock(work_id):
+            logger.info(f"Work item {work_id} unblocked, resuming execution")
+            return True
+        logger.warning(f"Failed to unblock work item {work_id}")
+        return False