claude-mpm 5.4.41__py3-none-any.whl → 5.6.72__py3-none-any.whl

claude_mpm/commander/frameworks/mpm.py

@@ -0,0 +1,57 @@
+"""Claude MPM framework implementation."""
+
+import shlex
+import shutil
+from pathlib import Path
+
+from .base import BaseFramework
+
+
+class MPMFramework(BaseFramework):
+    """Claude MPM framework.
+
+    This framework launches Claude MPM with full agent orchestration.
+
+    Example:
+        >>> framework = MPMFramework()
+        >>> framework.name
+        'mpm'
+        >>> framework.is_available()
+        True
+        >>> framework.get_startup_command(Path("/Users/user/myapp"))
+        "cd '/Users/user/myapp' && claude-mpm"
+    """
+
+    name = "mpm"
+    display_name = "Claude MPM"
+    command = "claude-mpm"
+
+    def get_startup_command(self, project_path: Path) -> str:
+        """Get the command to start Claude MPM in a project.
+
+        Args:
+            project_path: Path to the project directory
+
+        Returns:
+            Shell command string to start Claude MPM
+
+        Example:
+            >>> framework = MPMFramework()
+            >>> framework.get_startup_command(Path("/Users/user/myapp"))
+            "cd '/Users/user/myapp' && claude-mpm"
+        """
+        quoted_path = shlex.quote(str(project_path))
+        return f"cd {quoted_path} && claude-mpm"
+
+    def is_available(self) -> bool:
+        """Check if 'claude-mpm' command is available.
+
+        Returns:
+            True if 'claude-mpm' command exists in PATH
+
+        Example:
+            >>> framework = MPMFramework()
+            >>> framework.is_available()
+            True
+        """
+        return shutil.which("claude-mpm") is not None

claude_mpm/commander/git/__init__.py

@@ -0,0 +1,5 @@
+"""Git operations for Commander."""
+
+from .worktree_manager import WorktreeInfo, WorktreeManager
+
+__all__ = ["WorktreeInfo", "WorktreeManager"]

claude_mpm/commander/git/worktree_manager.py

@@ -0,0 +1,212 @@
+"""Git worktree manager for session isolation."""
+
+import logging
+import subprocess  # nosec B404 - subprocess needed for git commands
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WorktreeInfo:
+    """Info about a git worktree."""
+
+    name: str
+    path: Path
+    branch: str
+    base_path: Path  # Original repo path
+
+
+class WorktreeManager:
+    """Manages git worktrees for session isolation."""
+
+    def __init__(self, base_path: Path):
+        """Initialize with base project path."""
+        self.base_path = Path(base_path)
+        self.worktrees_dir = self.base_path.parent / f".worktrees-{self.base_path.name}"
+
+    def create(self, name: str, branch: Optional[str] = None) -> WorktreeInfo:
+        """Create a worktree for a session.
+
+        Args:
+            name: Session/worktree name (e.g., "izzie")
+            branch: Branch name, defaults to session-{name}
+
+        Returns:
+            WorktreeInfo with path and branch details
+        """
+        branch = branch or f"session-{name}"
+        worktree_path = self.worktrees_dir / name
+
+        # Ensure worktrees directory exists
+        self.worktrees_dir.mkdir(parents=True, exist_ok=True)
+
+        # Check if worktree already exists
+        if worktree_path.exists():
+            logger.info(f"Worktree '{name}' already exists at {worktree_path}")
+            return self._get_worktree_info(name, worktree_path)
+
+        # Create new branch if it doesn't exist
+        try:
+            subprocess.run(  # nosec B603 B607 - git command with safe args
+                ["git", "branch", branch],
+                cwd=self.base_path,
+                capture_output=True,
+                check=False,  # Branch may already exist
+            )
+        except Exception as e:
+            logger.warning(f"Could not create branch {branch}: {e}")
+
+        # Create worktree
+        result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            ["git", "worktree", "add", str(worktree_path), branch],
+            check=False,
+            cwd=self.base_path,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to create worktree: {result.stderr}")
+
+        logger.info(f"Created worktree '{name}' at {worktree_path} on branch {branch}")
+        return WorktreeInfo(
+            name=name, path=worktree_path, branch=branch, base_path=self.base_path
+        )
+
+    def _get_worktree_info(self, name: str, path: Path) -> WorktreeInfo:
+        """Get info for existing worktree."""
+        result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            ["git", "branch", "--show-current"],
+            check=False,
+            cwd=path,
+            capture_output=True,
+            text=True,
+        )
+        branch = result.stdout.strip() or f"session-{name}"
+        return WorktreeInfo(
+            name=name, path=path, branch=branch, base_path=self.base_path
+        )
+
+    def list(self) -> list[WorktreeInfo]:
+        """List all worktrees for this project."""
+        result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            ["git", "worktree", "list", "--porcelain"],
+            check=False,
+            cwd=self.base_path,
+            capture_output=True,
+            text=True,
+        )
+
+        worktrees = []
+        current_path = None
+        current_branch = None
+
+        for line in result.stdout.strip().split("\n"):
+            if line.startswith("worktree "):
+                current_path = Path(line.split(" ", 1)[1])
+            elif line.startswith("branch "):
+                current_branch = line.split("/")[-1]  # refs/heads/branch -> branch
+            elif line == "":
+                if current_path and str(self.worktrees_dir) in str(current_path):
+                    name = current_path.name
+                    worktrees.append(
+                        WorktreeInfo(
+                            name=name,
+                            path=current_path,
+                            branch=current_branch or f"session-{name}",
+                            base_path=self.base_path,
+                        )
+                    )
+                current_path = None
+                current_branch = None
+
+        return worktrees
+
+    def remove(self, name: str, force: bool = False) -> bool:
+        """Remove a worktree."""
+        worktree_path = self.worktrees_dir / name
+
+        if not worktree_path.exists():
+            return False
+
+        args = ["git", "worktree", "remove", str(worktree_path)]
+        if force:
+            args.insert(3, "--force")
+
+        result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            args, check=False, cwd=self.base_path, capture_output=True, text=True
+        )
+        return result.returncode == 0
+
+    def get(self, name: str) -> Optional[WorktreeInfo]:
+        """Get worktree by name."""
+        worktree_path = self.worktrees_dir / name
+        if worktree_path.exists():
+            return self._get_worktree_info(name, worktree_path)
+        return None
+
+    def merge_to_main(self, name: str, delete_after: bool = True) -> tuple[bool, str]:
+        """Merge worktree branch back to main and optionally delete worktree.
+
+        Args:
+            name: Worktree name to merge
+            delete_after: Remove worktree after merge (default True)
+
+        Returns:
+            Tuple of (success, message)
+        """
+        worktree = self.get(name)
+        if not worktree:
+            return False, f"Worktree '{name}' not found"
+
+        # Get main branch name
+        result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            ["git", "symbolic-ref", "refs/remotes/origin/HEAD"],
+            check=False,
+            cwd=self.base_path,
+            capture_output=True,
+            text=True,
+        )
+        main_branch = (
+            result.stdout.strip().split("/")[-1] if result.returncode == 0 else "main"
+        )
+
+        # Checkout main in base repo
+        checkout_result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            ["git", "checkout", main_branch],
+            check=False,
+            cwd=self.base_path,
+            capture_output=True,
+            text=True,
+        )
+        if checkout_result.returncode != 0:
+            return False, f"Failed to checkout {main_branch}: {checkout_result.stderr}"
+
+        # Merge worktree branch
+        merge_result = subprocess.run(  # nosec B603 B607 - git command with safe args
+            ["git", "merge", worktree.branch, "--no-edit"],
+            check=False,
+            cwd=self.base_path,
+            capture_output=True,
+            text=True,
+        )
+
+        if merge_result.returncode != 0:
+            return False, f"Merge failed: {merge_result.stderr}"
+
+        # Delete worktree if requested
+        if delete_after:
+            self.remove(name, force=True)
+            # Delete branch
+            subprocess.run(  # nosec B603 B607 - git command with safe args
+                ["git", "branch", "-d", worktree.branch],
+                check=False,
+                cwd=self.base_path,
+                capture_output=True,
+            )
+
+        logger.info(f"Merged '{worktree.branch}' to {main_branch}")
+        return True, f"Merged '{worktree.branch}' to {main_branch}"

claude_mpm/commander/inbox/__init__.py

@@ -0,0 +1,16 @@
+"""Inbox system for MPM Commander.
+
+Provides centralized event aggregation and display.
+"""
+
+from .dedup import DedupEntry, EventDeduplicator
+from .inbox import Inbox, InboxCounts
+from .models import InboxItem
+
+__all__ = [
+    "DedupEntry",
+    "EventDeduplicator",
+    "Inbox",
+    "InboxCounts",
+    "InboxItem",
+]

claude_mpm/commander/inbox/dedup.py

@@ -0,0 +1,128 @@
+"""Event deduplication logic for inbox system.
+
+Prevents duplicate events within a configurable time window using
+content hashing and time-based expiration.
+"""
+
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Dict
+
+
+@dataclass
+class DedupEntry:
+    """Deduplication cache entry.
+
+    Tracks when an event was first seen and how many times it's appeared.
+
+    Attributes:
+        key: Unique deduplication key
+        first_seen: When this key was first encountered
+        count: Number of times this key has been seen
+    """
+
+    key: str
+    first_seen: datetime
+    count: int = 1
+
+
+class EventDeduplicator:
+    """Prevent duplicate events within a time window.
+
+    Uses content hashing to detect duplicates and time-based expiration
+    to automatically clean up old entries.
+
+    The deduplication key is constructed from:
+    - Project ID
+    - Event type
+    - Title hash (first 8 chars of MD5)
+
+    Example:
+        >>> dedup = EventDeduplicator(window_seconds=60)
+        >>> dedup.is_duplicate("proj_123", "error", "Connection failed")
+        False  # First occurrence
+        >>> dedup.is_duplicate("proj_123", "error", "Connection failed")
+        True   # Duplicate within 60 seconds
+    """
+
+    def __init__(self, window_seconds: int = 60):
+        """Initialize deduplicator with time window.
+
+        Args:
+            window_seconds: Duration in seconds to consider events as duplicates.
+                           Default is 60 seconds.
+        """
+        self.window = timedelta(seconds=window_seconds)
+        self._seen: Dict[str, DedupEntry] = {}
+
+    def make_key(self, project_id: str, event_type: str, title: str) -> str:
+        """Create deduplication key from event attributes.
+
+        Generates a key in the format: {project_id}:{event_type}:{title_hash}
+
+        Args:
+            project_id: Unique project identifier
+            event_type: Type of event (from EventType enum)
+            title: Event title text
+
+        Returns:
+            Composite key string for deduplication
+
+        Example:
+            >>> dedup = EventDeduplicator()
+            >>> dedup.make_key("proj_123", "error", "Connection failed")
+            'proj_123:error:a1b2c3d4'
+        """
+        title_hash = hashlib.md5(title.encode(), usedforsecurity=False).hexdigest()[:8]
+        return f"{project_id}:{event_type}:{title_hash}"
+
+    def is_duplicate(self, project_id: str, event_type: str, title: str) -> bool:
+        """Check if this event is a duplicate within the window.
+
+        Args:
+            project_id: Unique project identifier
+            event_type: Type of event
+            title: Event title
+
+        Returns:
+            True if this is a duplicate, False if it's new
+
+        Side Effects:
+            - Increments count for duplicates
+            - Creates new entry for new events
+            - Cleans up expired entries
+
+        Example:
+            >>> dedup = EventDeduplicator(window_seconds=60)
+            >>> dedup.is_duplicate("proj_123", "error", "Timeout")
+            False  # First occurrence
+            >>> dedup.is_duplicate("proj_123", "error", "Timeout")
+            True   # Duplicate within window
+        """
+        self._cleanup_expired()
+        key = self.make_key(project_id, event_type, title)
+
+        if key in self._seen:
+            self._seen[key].count += 1
+            return True
+
+        self._seen[key] = DedupEntry(
+            key=key,
+            first_seen=datetime.now(timezone.utc),
+        )
+        return False
+
+    def _cleanup_expired(self) -> None:
+        """Remove entries older than the deduplication window.
+
+        Called automatically before each is_duplicate check to prevent
+        unbounded memory growth.
+
+        Side Effects:
+            Removes all entries where (now - first_seen) > window
+        """
+        now = datetime.now(timezone.utc)
+        expired = [k for k, v in self._seen.items() if now - v.first_seen > self.window]
+        for k in expired:
+            del self._seen[k]

claude_mpm/commander/inbox/inbox.py

@@ -0,0 +1,224 @@
+"""Centralized inbox for MPM Commander.
+
+Aggregates events from all projects with filtering, sorting, and pagination.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ..events.manager import EventManager
+from ..models.events import Event, EventPriority, EventType
+from ..registry import ProjectRegistry
+from .dedup import EventDeduplicator
+from .models import InboxItem
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InboxCounts:
+    """Count of events by priority.
+
+    Provides quick summary statistics for inbox state.
+
+    Attributes:
+        critical: Count of CRITICAL priority events
+        high: Count of HIGH priority events
+        normal: Count of NORMAL priority events
+        low: Count of LOW priority events
+        info: Count of INFO priority events
+        total: Total count of all events
+    """
+
+    critical: int = 0
+    high: int = 0
+    normal: int = 0
+    low: int = 0
+    info: int = 0
+    total: int = 0
+
+
+class Inbox:
+    """Centralized inbox aggregating events from all projects.
+
+    Provides a unified view of all pending events with:
+    - Multi-level filtering (priority, project, event type)
+    - Pagination support
+    - Priority-based sorting
+    - Project metadata enrichment
+    - Deduplication
+
+    Example:
+        >>> inbox = Inbox(event_manager, project_registry)
+        >>> items = inbox.get_items(limit=10, priority=EventPriority.HIGH)
+        >>> counts = inbox.get_counts()
+        >>> print(f"Total pending: {counts.total}")
+    """
+
+    def __init__(
+        self,
+        event_manager: EventManager,
+        project_registry: ProjectRegistry,
+        dedup_window: int = 60,
+    ):
+        """Initialize inbox with dependencies.
+
+        Args:
+            event_manager: Event lifecycle manager
+            project_registry: Project registration system
+            dedup_window: Deduplication window in seconds (default: 60)
+        """
+        self.events = event_manager
+        self.projects = project_registry
+        self.deduplicator = EventDeduplicator(window_seconds=dedup_window)
+
+    def get_items(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+        priority: Optional[EventPriority] = None,
+        project_id: Optional[str] = None,
+        event_type: Optional[EventType] = None,
+    ) -> List[InboxItem]:
+        """Get inbox items with optional filtering and pagination.
+
+        Applies filters in this order:
+        1. Get all pending events (optionally for specific project)
+        2. Filter by priority if specified
+        3. Filter by event type if specified
+        4. Sort by priority (high to low) then created_at (old to new)
+        5. Paginate with limit and offset
+        6. Enrich with project metadata
+
+        Args:
+            limit: Maximum number of items to return (default: 50)
+            offset: Number of items to skip for pagination (default: 0)
+            priority: Filter to specific priority level (optional)
+            project_id: Filter to specific project (optional)
+            event_type: Filter to specific event type (optional)
+
+        Returns:
+            List of enriched InboxItems, sorted and paginated
+
+        Example:
+            # Get first 20 critical events
+            >>> items = inbox.get_items(limit=20, priority=EventPriority.CRITICAL)
+
+            # Get high-priority errors for specific project
+            >>> items = inbox.get_items(
+            ...     priority=EventPriority.HIGH,
+            ...     project_id="proj_123",
+            ...     event_type=EventType.ERROR
+            ... )
+
+            # Pagination: get items 50-100
+            >>> items = inbox.get_items(limit=50, offset=50)
+        """
+        # Get all pending events (optionally filtered by project)
+        pending = self.events.get_pending(project_id)
+
+        # Filter by priority
+        if priority:
+            pending = [e for e in pending if e.priority == priority]
+
+        # Filter by event type
+        if event_type:
+            pending = [e for e in pending if e.type == event_type]
+
+        # Sort by priority (CRITICAL first) then created_at (oldest first)
+        priority_order = [
+            EventPriority.CRITICAL,
+            EventPriority.HIGH,
+            EventPriority.NORMAL,
+            EventPriority.LOW,
+            EventPriority.INFO,
+        ]
+
+        def sort_key(event: Event):
+            pri_idx = (
+                priority_order.index(event.priority)
+                if event.priority in priority_order
+                else 99
+            )
+            return (pri_idx, event.created_at)
+
+        sorted_events = sorted(pending, key=sort_key)
+
+        # Paginate
+        paginated = sorted_events[offset : offset + limit]
+
+        # Enrich with project metadata
+        items = []
+        for event in paginated:
+            project = self.projects.get(event.project_id)
+            if project:
+                session_runtime = None
+                if event.session_id and event.session_id in project.sessions:
+                    session_runtime = project.sessions[event.session_id].runtime
+
+                items.append(
+                    InboxItem(
+                        event=event,
+                        project_name=project.name,
+                        project_path=project.path,
+                        session_runtime=session_runtime,
+                    )
+                )
+
+        return items
+
+    def get_counts(self, project_id: Optional[str] = None) -> InboxCounts:
+        """Get count of pending events by priority.
+
+        Args:
+            project_id: If provided, only count events for this project
+
+        Returns:
+            InboxCounts with breakdown by priority and total
+
+        Example:
+            >>> counts = inbox.get_counts()
+            >>> print(f"Critical: {counts.critical}, Total: {counts.total}")
+
+            >>> project_counts = inbox.get_counts(project_id="proj_123")
+        """
+        pending = self.events.get_pending(project_id)
+
+        counts = InboxCounts()
+        for event in pending:
+            counts.total += 1
+            if event.priority == EventPriority.CRITICAL:
+                counts.critical += 1
+            elif event.priority == EventPriority.HIGH:
+                counts.high += 1
+            elif event.priority == EventPriority.NORMAL:
+                counts.normal += 1
+            elif event.priority == EventPriority.LOW:
+                counts.low += 1
+            elif event.priority == EventPriority.INFO:
+                counts.info += 1
+
+        return counts
+
+    def should_create_event(
+        self, project_id: str, event_type: EventType, title: str
+    ) -> bool:
+        """Check if event should be created (not a duplicate).
+
+        Uses deduplication to prevent creating duplicate events within
+        the configured time window.
+
+        Args:
+            project_id: Project raising the event
+            event_type: Type of event
+            title: Event title
+
+        Returns:
+            True if event should be created, False if it's a duplicate
+
+        Example:
+            >>> if inbox.should_create_event("proj_123", EventType.ERROR, "Timeout"):
+            ...     event = event_manager.create(...)
+        """
+        return not self.deduplicator.is_duplicate(project_id, event_type.value, title)