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

claude_mpm/commander/models/events.py

@@ -0,0 +1,127 @@
+"""Event models for MPM Commander (Phase 2).
+
+This module defines the complete event model supporting all event types,
+priorities, and statuses for the inbox system.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+def _utc_now() -> datetime:
+    """Return current UTC time with timezone info."""
+    return datetime.now(timezone.utc)
+
+
+class EventType(Enum):
+    """Types of events that can be raised by projects."""
+
+    DECISION_NEEDED = "decision_needed"  # Tool asking which option
+    CLARIFICATION = "clarification"  # Tool needs more info
+    ERROR = "error"  # Something failed
+    APPROVAL = "approval"  # Destructive action pending
+    TASK_COMPLETE = "task_complete"  # Work item finished
+    MILESTONE = "milestone"  # Significant progress
+    STATUS = "status"  # General update
+    PROJECT_IDLE = "project_idle"  # Project has no work
+    INSTANCE_STARTING = "instance_starting"  # Instance is starting up
+    INSTANCE_READY = "instance_ready"  # Instance is ready for work
+    INSTANCE_ERROR = "instance_error"  # Instance encountered an error
+
+
+class EventPriority(Enum):
+    """Priority levels for events, ordered from highest to lowest."""
+
+    CRITICAL = "critical"  # Blocking all progress
+    HIGH = "high"  # Blocking this project
+    NORMAL = "normal"  # Needs response, not blocking
+    LOW = "low"  # Informational, can batch
+    INFO = "info"  # No response needed
+
+    def __lt__(self, other: "EventPriority") -> bool:
+        """Enable priority comparison for sorting."""
+        order = [self.CRITICAL, self.HIGH, self.NORMAL, self.LOW, self.INFO]
+        return order.index(self) < order.index(other)
+
+
+class EventStatus(Enum):
+    """Lifecycle status of an event."""
+
+    PENDING = "pending"  # Awaiting response
+    ACKNOWLEDGED = "acknowledged"  # Seen but not resolved
+    RESOLVED = "resolved"  # Response provided
+    DISMISSED = "dismissed"  # Intentionally ignored
+
+
+# Default priority by event type
+DEFAULT_PRIORITIES: Dict[EventType, EventPriority] = {
+    EventType.ERROR: EventPriority.CRITICAL,
+    EventType.DECISION_NEEDED: EventPriority.HIGH,
+    EventType.APPROVAL: EventPriority.HIGH,
+    EventType.CLARIFICATION: EventPriority.NORMAL,
+    EventType.TASK_COMPLETE: EventPriority.LOW,
+    EventType.MILESTONE: EventPriority.LOW,
+    EventType.STATUS: EventPriority.INFO,
+    EventType.PROJECT_IDLE: EventPriority.INFO,
+    EventType.INSTANCE_STARTING: EventPriority.INFO,
+    EventType.INSTANCE_READY: EventPriority.INFO,
+    EventType.INSTANCE_ERROR: EventPriority.HIGH,
+}
+
+
+# Which event types block progress and their scope
+BLOCKING_EVENTS: Dict[EventType, str] = {
+    EventType.ERROR: "all",  # Blocks all projects
+    EventType.DECISION_NEEDED: "project",  # Blocks this project
+    EventType.APPROVAL: "project",  # Blocks this project
+}
+
+
+@dataclass
+class Event:
+    """Represents an event in the MPM Commander system.
+
+    Events are raised by projects to communicate with the user or
+    system about state changes, decisions needed, or progress updates.
+
+    Attributes:
+        id: Unique event identifier
+        project_id: ID of project that raised this event
+        type: Type of event (decision, error, status, etc.)
+        priority: Urgency level
+        title: Short summary of the event
+        session_id: Optional session ID if event is session-specific
+        status: Current lifecycle status
+        content: Detailed event message or description
+        context: Additional structured data about the event
+        options: For DECISION_NEEDED events, list of choices
+        response: User's response to the event
+        responded_at: When the response was recorded
+        created_at: When the event was created
+    """
+
+    id: str
+    project_id: str
+    type: EventType
+    priority: EventPriority
+    title: str
+    session_id: Optional[str] = None
+    status: EventStatus = EventStatus.PENDING
+    content: str = ""
+    context: Dict[str, Any] = field(default_factory=dict)
+    options: Optional[List[str]] = None
+    response: Optional[str] = None
+    responded_at: Optional[datetime] = None
+    created_at: datetime = field(default_factory=_utc_now)
+
+    @property
+    def is_blocking(self) -> bool:
+        """Check if this event blocks progress."""
+        return self.type in BLOCKING_EVENTS and self.status == EventStatus.PENDING
+
+    @property
+    def blocking_scope(self) -> Optional[str]:
+        """Get the scope this event blocks ('all' or 'project')."""
+        return BLOCKING_EVENTS.get(self.type)

claude_mpm/commander/models/project.py

@@ -0,0 +1,162 @@
+"""Project data models for MPM Commander.
+
+This module defines the core data structures for managing projects,
+tool sessions, and conversation threads.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+def _utc_now() -> datetime:
+    """Return current UTC time with timezone awareness."""
+    return datetime.now(timezone.utc)
+
+
+class ProjectState(Enum):
+    """Project execution state.
+
+    Attributes:
+        IDLE: No pending work in queue
+        WORKING: Currently executing a work item
+        BLOCKED: Waiting on human input or approval
+        PAUSED: Manually paused by user
+        ERROR: Encountered unrecoverable error
+    """
+
+    IDLE = "idle"
+    WORKING = "working"
+    BLOCKED = "blocked"
+    PAUSED = "paused"
+    ERROR = "error"
+
+
+@dataclass
+class ToolSession:
+    """Tool runtime session (Claude Code, Codex, Aider, etc.).
+
+    Each session runs in an isolated tmux pane for output capture.
+
+    Attributes:
+        id: Unique session identifier
+        project_id: Parent project ID
+        runtime: Tool runtime name (e.g., "claude-code", "aider")
+        tmux_target: Tmux window:pane identifier (e.g., "commander:proj-a-cc")
+        status: Current session status
+        output_buffer: Captured output from tool
+        created_at: Session creation timestamp
+        last_output_at: Last output received timestamp
+
+    Example:
+        >>> session = ToolSession(
+        ...     id="sess-123",
+        ...     project_id="proj-abc",
+        ...     runtime="claude-code",
+        ...     tmux_target="commander:proj-abc-cc"
+        ... )
+        >>> session.status
+        'initializing'
+    """
+
+    id: str
+    project_id: str
+    runtime: str
+    tmux_target: str
+    status: str = "initializing"
+    output_buffer: str = ""
+    created_at: datetime = field(default_factory=_utc_now)
+    last_output_at: Optional[datetime] = None
+
+
+@dataclass
+class ThreadMessage:
+    """Conversation thread message.
+
+    Represents a single message in the project's conversation history,
+    which can come from user, assistant, system, or tool outputs.
+
+    Attributes:
+        id: Unique message identifier
+        role: Message sender role
+        content: Message content
+        session_id: Associated tool session (if from tool)
+        event_id: Associated event (Phase 2)
+        timestamp: Message creation timestamp
+
+    Example:
+        >>> msg = ThreadMessage(
+        ...     id="msg-1",
+        ...     role="user",
+        ...     content="Fix the login bug"
+        ... )
+        >>> msg.role
+        'user'
+    """
+
+    id: str
+    role: str  # user, assistant, system, tool
+    content: str
+    session_id: Optional[str] = None
+    event_id: Optional[str] = None
+    timestamp: datetime = field(default_factory=_utc_now)
+
+
+@dataclass
+class Project:
+    """Project context and state management.
+
+    Maintains isolated state for a single project including:
+    - Execution state and work queue
+    - Tool sessions (Claude Code, Aider, etc.)
+    - Conversation thread
+    - Events and history (Phase 2)
+
+    Attributes:
+        id: Unique project identifier (UUID)
+        path: Absolute filesystem path to project
+        name: Human-readable project name
+        state: Current execution state
+        state_reason: Optional reason for state (e.g., error message)
+        config_loaded: Whether .claude-mpm/ config loaded
+        config: Loaded configuration dict
+        sessions: Active tool sessions by session_id
+        work_queue: Pending work items (Phase 3)
+        active_work: Currently executing work item
+        completed_work: History of completed work items
+        pending_events: Events pending processing (Phase 2)
+        event_history: Processed events (Phase 2)
+        thread: Conversation message history
+        created_at: Project registration timestamp
+        last_activity: Last activity timestamp (updated on any change)
+
+    Example:
+        >>> from pathlib import Path
+        >>> project = Project(
+        ...     id="proj-abc123",
+        ...     path="/Users/masa/Projects/my-app",
+        ...     name="my-app"
+        ... )
+        >>> project.state
+        <ProjectState.IDLE: 'idle'>
+        >>> project.state = ProjectState.WORKING
+        >>> project.state_reason = "Processing ticket #123"
+    """
+
+    id: str
+    path: str
+    name: str
+    state: ProjectState = ProjectState.IDLE
+    state_reason: Optional[str] = None
+    config_loaded: bool = False
+    config: Optional[Dict[str, Any]] = None
+    sessions: Dict[str, ToolSession] = field(default_factory=dict)
+    work_queue: List[Any] = field(default_factory=list)
+    active_work: Optional[Any] = None
+    completed_work: List[Any] = field(default_factory=list)
+    pending_events: List[Any] = field(default_factory=list)
+    event_history: List[Any] = field(default_factory=list)
+    thread: List[ThreadMessage] = field(default_factory=list)
+    created_at: datetime = field(default_factory=_utc_now)
+    last_activity: datetime = field(default_factory=_utc_now)

claude_mpm/commander/models/work.py

@@ -0,0 +1,214 @@
+"""Work item models for MPM Commander work queue.
+
+This module defines work items that represent tasks to be executed
+by the Commander daemon across multiple projects.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+def _utc_now() -> datetime:
+    """Return current UTC time with timezone info."""
+    return datetime.now(timezone.utc)
+
+
+class WorkState(Enum):
+    """Lifecycle states of a work item."""
+
+    PENDING = "pending"  # Created but not yet queued
+    QUEUED = "queued"  # In queue, waiting for execution
+    IN_PROGRESS = "in_progress"  # Currently being executed
+    BLOCKED = "blocked"  # Paused due to blocking event
+    COMPLETED = "completed"  # Successfully finished
+    FAILED = "failed"  # Failed with error
+    CANCELLED = "cancelled"  # Manually cancelled
+
+
+class WorkPriority(Enum):
+    """Priority levels for work items, ordered from highest to lowest."""
+
+    CRITICAL = 4  # Execute immediately
+    HIGH = 3  # Execute as soon as possible
+    MEDIUM = 2  # Normal priority
+    LOW = 1  # Execute when idle
+
+    def __lt__(self, other: "WorkPriority") -> bool:
+        """Enable priority comparison for sorting (higher value = higher priority)."""
+        if not isinstance(other, WorkPriority):
+            return NotImplemented
+        return self.value < other.value
+
+    def __le__(self, other: "WorkPriority") -> bool:
+        """Less than or equal comparison."""
+        if not isinstance(other, WorkPriority):
+            return NotImplemented
+        return self.value <= other.value
+
+    def __gt__(self, other: "WorkPriority") -> bool:
+        """Greater than comparison."""
+        if not isinstance(other, WorkPriority):
+            return NotImplemented
+        return self.value > other.value
+
+    def __ge__(self, other: "WorkPriority") -> bool:
+        """Greater than or equal comparison."""
+        if not isinstance(other, WorkPriority):
+            return NotImplemented
+        return self.value >= other.value
+
+
+@dataclass
+class WorkItem:
+    """Represents a work item to be executed by the Commander.
+
+    Work items are queued tasks that will be executed by RuntimeExecutor.
+    They support priority-based execution and dependency chains.
+
+    Attributes:
+        id: Unique work item identifier
+        project_id: ID of project this work belongs to
+        content: The message/task to send to Claude
+        state: Current lifecycle state
+        priority: Execution priority
+        created_at: When the work item was created
+        started_at: When execution started (if IN_PROGRESS or later)
+        completed_at: When execution completed (if COMPLETED/FAILED)
+        result: Result output on completion
+        error: Error message if FAILED
+        depends_on: List of work item IDs that must complete first
+        metadata: Additional structured data about the work
+
+    Example:
+        >>> work = WorkItem(
+        ...     id="work-123",
+        ...     project_id="proj-abc",
+        ...     content="Implement OAuth2 authentication",
+        ...     priority=WorkPriority.HIGH
+        ... )
+        >>> work.can_start({"work-122"})  # Check if dependencies satisfied
+        True
+    """
+
+    id: str
+    project_id: str
+    content: str
+    state: WorkState = WorkState.PENDING
+    priority: WorkPriority = WorkPriority.MEDIUM
+    created_at: datetime = field(default_factory=_utc_now)
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    result: Optional[str] = None
+    error: Optional[str] = None
+    depends_on: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def can_start(self, completed_ids: set[str]) -> bool:
+        """Check if dependencies are satisfied.
+
+        Args:
+            completed_ids: Set of work item IDs that have completed
+
+        Returns:
+            True if all dependencies in completed_ids, False otherwise
+
+        Example:
+            >>> work = WorkItem(id="w1", project_id="p1", content="Task",
+            ...                 depends_on=["w0"])
+            >>> work.can_start({"w0"})
+            True
+            >>> work.can_start(set())
+            False
+        """
+        if not self.depends_on:
+            return True
+        return all(dep_id in completed_ids for dep_id in self.depends_on)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize for persistence.
+
+        Returns:
+            Dictionary representation suitable for JSON serialization
+
+        Example:
+            >>> work = WorkItem(id="w1", project_id="p1", content="Task")
+            >>> data = work.to_dict()
+            >>> data["id"]
+            'w1'
+        """
+        return {
+            "id": self.id,
+            "project_id": self.project_id,
+            "content": self.content,
+            "state": self.state.value,
+            "priority": self.priority.value,
+            "created_at": self.created_at.isoformat(),
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "completed_at": (
+                self.completed_at.isoformat() if self.completed_at else None
+            ),
+            "result": self.result,
+            "error": self.error,
+            "depends_on": self.depends_on,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "WorkItem":
+        """Deserialize from persistence.
+
+        Args:
+            data: Dictionary from to_dict()
+
+        Returns:
+            Reconstructed WorkItem instance
+
+        Raises:
+            ValueError: If required fields missing or invalid
+
+        Example:
+            >>> data = {"id": "w1", "project_id": "p1", "content": "Task",
+            ...         "state": "pending", "priority": 2}
+            >>> work = WorkItem.from_dict(data)
+            >>> work.id
+            'w1'
+        """
+        # Parse enums
+        try:
+            state = WorkState(data["state"])
+        except (KeyError, ValueError) as e:
+            raise ValueError(f"Invalid or missing state: {e}") from e
+
+        # Priority can be int or string
+        priority_val = data.get("priority", 2)
+        if isinstance(priority_val, str):
+            priority = WorkPriority[priority_val.upper()]
+        else:
+            priority = WorkPriority(priority_val)
+
+        # Parse datetimes
+        def parse_datetime(dt_str: Optional[str]) -> Optional[datetime]:
+            if not dt_str:
+                return None
+            return datetime.fromisoformat(dt_str)
+
+        created_at = parse_datetime(data.get("created_at"))
+        if not created_at:
+            created_at = _utc_now()
+
+        return cls(
+            id=data["id"],
+            project_id=data["project_id"],
+            content=data["content"],
+            state=state,
+            priority=priority,
+            created_at=created_at,
+            started_at=parse_datetime(data.get("started_at")),
+            completed_at=parse_datetime(data.get("completed_at")),
+            result=data.get("result"),
+            error=data.get("error"),
+            depends_on=data.get("depends_on", []),
+            metadata=data.get("metadata", {}),
+        )

claude_mpm/commander/parsing/__init__.py

@@ -0,0 +1,20 @@
+"""Output parsing module for detecting events in tool output."""
+
+from .extractor import (
+    extract_action_details,
+    extract_error_context,
+    extract_options,
+    strip_code_blocks,
+)
+from .output_parser import OutputParser, ParseResult
+from .patterns import ALL_PATTERNS
+
+__all__ = [
+    "ALL_PATTERNS",
+    "OutputParser",
+    "ParseResult",
+    "extract_action_details",
+    "extract_error_context",
+    "extract_options",
+    "strip_code_blocks",
+]

claude_mpm/commander/parsing/extractor.py

@@ -0,0 +1,132 @@
+"""Extract options and context from matched patterns."""
+
+import re
+from typing import Any, Dict, List, Optional
+
+
+def extract_options(content: str) -> Optional[List[str]]:
+    """Extract options from decision content.
+
+    Supports multiple formats:
+    - Numbered lists: "1. Option A\n2. Option B"
+    - Bullet lists: "• Option A\n- Option B"
+    - Inline options: "(option1/option2/option3)"
+    - Y/n style: "[Y/n]", "[yes/no]"
+
+    Args:
+        content: Content to extract options from
+
+    Returns:
+        List of option strings if found, None otherwise
+    """
+    # Numbered list: "1. Option A\n2. Option B"
+    numbered = re.findall(r"^\s*\d+[\.\)]\s*(.+)$", content, re.MULTILINE)
+    if numbered:
+        return [opt.strip() for opt in numbered]
+
+    # Bullet list: "• Option A\n- Option B"
+    bullets = re.findall(r"^\s*[-•*]\s*(.+)$", content, re.MULTILINE)
+    if bullets:
+        return [opt.strip() for opt in bullets]
+
+    # Inline options: "(option1/option2/option3)"
+    inline = re.search(r"\(([^)]+/[^)]+)\)", content)
+    if inline:
+        return [o.strip() for o in inline.group(1).split("/")]
+
+    # Y/n style
+    yn = re.search(r"\[(Y/n|y/N|yes/no|Yes/No)\]", content, re.I)
+    if yn:
+        parts = yn.group(1).split("/")
+        return [p.strip() for p in parts]
+
+    return None
+
+
+def extract_error_context(
+    content: str, match_start: int, match_end: int, context_lines: int = 5
+) -> Dict[str, Any]:
+    """Extract surrounding context for error.
+
+    Args:
+        content: Full content text
+        match_start: Character position where match starts
+        match_end: Character position where match ends
+        context_lines: Number of lines to include before/after error
+
+    Returns:
+        Dict with surrounding lines and error position info
+    """
+    lines = content.split("\n")
+
+    # Find which line the match is on
+    char_count = 0
+    match_line = 0
+    for i, line in enumerate(lines):
+        char_count += len(line) + 1  # +1 for newline
+        if char_count > match_start:
+            match_line = i
+            break
+
+    # Get context lines
+    start = max(0, match_line - context_lines)
+    end = min(len(lines), match_line + context_lines + 1)
+
+    return {
+        "surrounding_lines": lines[start:end],
+        "error_line_index": match_line - start,
+        "total_lines": len(lines),
+        "match_line": match_line,
+    }
+
+
+def extract_action_details(content: str, match: re.Match) -> Dict[str, Any]:
+    """Extract details about an action from approval match.
+
+    Args:
+        content: Full content text
+        match: Regex match object for the approval pattern
+
+    Returns:
+        Dict with action type, target, and reversibility info
+    """
+    groups = match.groups()
+    # Use the first captured group if available, otherwise the full match
+    action_text = groups[0] if groups else match.group(0)
+
+    # Try to identify the action type from the full matched text
+    full_match = match.group(0)
+    action_type = "unknown"
+    if re.search(r"delete|remove", full_match, re.I):
+        action_type = "delete"
+    elif re.search(r"overwrite|modify|change", full_match, re.I):
+        action_type = "modify"
+    elif re.search(r"create|add", full_match, re.I):
+        action_type = "create"
+
+    # Check if reversible
+    reversible = "cannot be undone" not in content.lower()
+
+    return {
+        "action": action_type,
+        "target": action_text.strip(),
+        "reversible": reversible,
+    }
+
+
+def strip_code_blocks(content: str) -> str:
+    """Remove code blocks to avoid false positives.
+
+    Replaces fenced code blocks and inline code with placeholders
+    to prevent pattern matching inside code.
+
+    Args:
+        content: Content to strip code blocks from
+
+    Returns:
+        Content with code blocks replaced by placeholders
+    """
+    # Remove fenced code blocks
+    content = re.sub(r"```[\s\S]*?```", "[CODE_BLOCK]", content)
+    # Remove inline code and return
+    return re.sub(r"`[^`]+`", "[INLINE_CODE]", content)