claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/commander/parsing/output_parser.py

@@ -0,0 +1,270 @@
+"""Parse tool output and detect events."""
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from ..events.manager import EventManager
+from ..models.events import EventType
+from .extractor import (
+    extract_action_details,
+    extract_error_context,
+    extract_options,
+    strip_code_blocks,
+)
+from .patterns import ALL_PATTERNS
+
+logger = logging.getLogger(__name__)
+
+# ANSI escape code pattern
+ANSI_ESCAPE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+
+@dataclass
+class ParseResult:
+    """Result of parsing output."""
+
+    event_type: EventType
+    title: str
+    content: str
+    options: Optional[List[str]] = None
+    context: Optional[Dict[str, Any]] = None
+    match_start: int = 0
+    match_end: int = 0
+
+
+class OutputParser:
+    """Parses tool output and detects events.
+
+    Detects various event types including:
+    - Decisions needed (with option extraction)
+    - Approvals required (with action details)
+    - Errors (with context)
+    - Task completions
+    - Clarifications needed
+
+    Features:
+    - ANSI escape code stripping
+    - Code block exclusion (avoid false positives)
+    - Overlap deduplication
+    - Option extraction from various formats
+    - Integration with EventManager
+    """
+
+    def __init__(self, event_manager: Optional[EventManager] = None):
+        """Initialize parser.
+
+        Args:
+            event_manager: Optional EventManager for automatic event creation
+        """
+        self.event_manager = event_manager
+        self._patterns = ALL_PATTERNS
+
+    def strip_ansi(self, text: str) -> str:
+        """Remove ANSI escape codes.
+
+        Args:
+            text: Text potentially containing ANSI codes
+
+        Returns:
+            Text with ANSI codes removed
+        """
+        return ANSI_ESCAPE.sub("", text)
+
+    def parse(
+        self,
+        content: str,
+        project_id: str,
+        session_id: Optional[str] = None,
+        create_events: bool = True,
+    ) -> List[ParseResult]:
+        """Parse output and detect all events.
+
+        Args:
+            content: Output content to parse
+            project_id: Project identifier for event creation
+            session_id: Optional session identifier
+            create_events: Whether to create events via EventManager
+
+        Returns:
+            List of ParseResult objects for all detected events
+        """
+        results: List[ParseResult] = []
+
+        # Clean content
+        clean_content = self.strip_ansi(content)
+
+        # Strip code blocks for pattern matching
+        matchable_content = strip_code_blocks(clean_content)
+
+        # Check each pattern category
+        for category, patterns in self._patterns.items():
+            for pattern, event_type in patterns:
+                for match in pattern.finditer(matchable_content):
+                    result = self._create_result(
+                        event_type=event_type,
+                        match=match,
+                        original_content=clean_content,
+                        matchable_content=matchable_content,
+                    )
+                    if result:
+                        results.append(result)
+
+        # Deduplicate overlapping results
+        results = self._deduplicate(results)
+
+        # Create events if manager provided and flag set
+        if self.event_manager and create_events:
+            for result in results:
+                self.event_manager.create(
+                    project_id=project_id,
+                    session_id=session_id,
+                    event_type=result.event_type,
+                    title=result.title,
+                    content=result.content,
+                    options=result.options,
+                    context=result.context,
+                )
+
+        logger.debug("Parsed %d events from output", len(results))
+        return results
+
+    def _create_result(
+        self,
+        event_type: EventType,
+        match: re.Match,
+        original_content: str,
+        matchable_content: str,
+    ) -> Optional[ParseResult]:
+        """Create a ParseResult from a pattern match.
+
+        Args:
+            event_type: Type of event detected
+            match: Regex match object
+            original_content: Original content (with code blocks)
+            matchable_content: Content with code blocks stripped
+
+        Returns:
+            ParseResult if valid, None otherwise
+        """
+        matched_text = match.group(0)
+        options = None
+        context = {}
+
+        # Generate title and extract context based on event type
+        if event_type == EventType.ERROR:
+            title = self._extract_error_title(matched_text)
+            context = extract_error_context(
+                original_content, match.start(), match.end()
+            )
+        elif event_type == EventType.DECISION_NEEDED:
+            title = "Decision needed"
+            # Look ahead for options (up to 500 chars)
+            options = extract_options(
+                original_content[match.start() : match.start() + 500]
+            )
+            context = {"options_detected": len(options) if options else 0}
+        elif event_type == EventType.APPROVAL:
+            title = "Approval required"
+            context = extract_action_details(original_content, match)
+            options = ["Yes", "No"]
+        elif event_type == EventType.TASK_COMPLETE:
+            title = "Task completed"
+        elif event_type == EventType.CLARIFICATION:
+            title = "Clarification needed"
+        else:
+            title = f"{event_type.value} detected"
+
+        return ParseResult(
+            event_type=event_type,
+            title=title,
+            content=matched_text[:500],  # Truncate long matches
+            options=options
+            if event_type in (EventType.DECISION_NEEDED, EventType.APPROVAL)
+            else None,
+            context=context,
+            match_start=match.start(),
+            match_end=match.end(),
+        )
+
+    def _extract_error_title(self, matched_text: str) -> str:
+        """Extract a concise error title.
+
+        Args:
+            matched_text: Text that matched the error pattern
+
+        Returns:
+            Concise error title (max 80 chars)
+        """
+        # Try to get the error type and message
+        error_match = re.search(
+            r"(\w+(?:Error|Exception)): (.+?)(?:\n|$)", matched_text
+        )
+        if error_match:
+            error_type = error_match.group(1)
+            error_msg = error_match.group(2)[:50]
+            return f"{error_type}: {error_msg}"
+
+        # Fallback to first line
+        first_line = matched_text.split("\n")[0].strip()
+        return first_line[:80] if first_line else "Error detected"
+
+    def _deduplicate(self, results: List[ParseResult]) -> List[ParseResult]:
+        """Remove duplicate or overlapping results.
+
+        When results overlap, keep the one with higher priority.
+        Priority order: ERROR > APPROVAL > DECISION > CLARIFICATION > COMPLETION
+
+        Args:
+            results: List of ParseResult objects to deduplicate
+
+        Returns:
+            Deduplicated list of ParseResult objects
+        """
+        if not results:
+            return results
+
+        # Sort by position
+        sorted_results = sorted(results, key=lambda r: r.match_start)
+
+        # Priority order (lower index = higher priority)
+        priority_order = [
+            EventType.ERROR,
+            EventType.APPROVAL,
+            EventType.DECISION_NEEDED,
+            EventType.CLARIFICATION,
+            EventType.TASK_COMPLETE,
+        ]
+
+        deduped: List[ParseResult] = []
+        for result in sorted_results:
+            # Check if overlaps with any existing result
+            overlaps = False
+            for existing in deduped:
+                if (
+                    result.match_start < existing.match_end
+                    and result.match_end > existing.match_start
+                ):
+                    # Overlap detected - keep higher priority
+                    result_priority = (
+                        priority_order.index(result.event_type)
+                        if result.event_type in priority_order
+                        else 99
+                    )
+                    existing_priority = (
+                        priority_order.index(existing.event_type)
+                        if existing.event_type in priority_order
+                        else 99
+                    )
+
+                    if result_priority < existing_priority:
+                        deduped.remove(existing)
+                    else:
+                        overlaps = True
+                    break
+
+            if not overlaps:
+                deduped.append(result)
+
+        return deduped

claude_mpm/commander/parsing/patterns.py

@@ -0,0 +1,100 @@
+"""Detection patterns for various event types in tool output."""
+
+import re
+from typing import List, Tuple
+
+from ..models.events import EventType
+
+# Pattern format: (compiled_regex, event_type)
+
+DECISION_PATTERNS: List[Tuple[re.Pattern, EventType]] = [
+    (
+        re.compile(
+            r"Which (?:option|approach|method) (?:would you|do you) prefer\?", re.I
+        ),
+        EventType.DECISION_NEEDED,
+    ),
+    (
+        re.compile(
+            r"Should I (?:proceed|continue|use|implement) (?:with )?(.+)\?", re.I
+        ),
+        EventType.DECISION_NEEDED,
+    ),
+    (re.compile(r"Do you want me to (.+)\?", re.I), EventType.DECISION_NEEDED),
+    (
+        re.compile(r"Please choose:?\s*\n(?:\s*\d+[\.\)]\s*.+\n?)+", re.I | re.M),
+        EventType.DECISION_NEEDED,
+    ),
+    (
+        re.compile(r"Options:?\s*\n(?:\s*[-•]\s*.+\n?)+", re.I | re.M),
+        EventType.DECISION_NEEDED,
+    ),
+    (re.compile(r"\(y/n\)\??", re.I), EventType.DECISION_NEEDED),
+    (re.compile(r"\[Y/n\]", re.I), EventType.DECISION_NEEDED),
+    (re.compile(r"\[yes/no\]", re.I), EventType.DECISION_NEEDED),
+    (re.compile(r"Select an option:", re.I), EventType.DECISION_NEEDED),
+]
+
+APPROVAL_PATTERNS: List[Tuple[re.Pattern, EventType]] = [
+    (
+        re.compile(r"This will (?:delete|remove|overwrite|modify) (.+)", re.I),
+        EventType.APPROVAL,
+    ),
+    (re.compile(r"Are you sure you want to (.+)\?", re.I), EventType.APPROVAL),
+    (re.compile(r"This action cannot be undone", re.I), EventType.APPROVAL),
+    (re.compile(r"Warning: This will (.+)", re.I), EventType.APPROVAL),
+    (re.compile(r"Do you want to allow (.+)\?", re.I), EventType.APPROVAL),
+    (re.compile(r"Permanently delete", re.I), EventType.APPROVAL),
+]
+
+ERROR_PATTERNS: List[Tuple[re.Pattern, EventType]] = [
+    (re.compile(r"Traceback \(most recent call last\):", re.I), EventType.ERROR),
+    (re.compile(r"(\w+Error): (.+)", re.I), EventType.ERROR),
+    (re.compile(r"(\w+Exception): (.+)", re.I), EventType.ERROR),
+    (re.compile(r"^Error: (.+)", re.I | re.M), EventType.ERROR),
+    (re.compile(r"^Failed: (.+)", re.I | re.M), EventType.ERROR),
+    (re.compile(r"^FATAL: (.+)", re.I | re.M), EventType.ERROR),
+    (re.compile(r"Permission denied", re.I), EventType.ERROR),
+    (re.compile(r"Access denied", re.I), EventType.ERROR),
+    (re.compile(r"(?:File|Directory) not found", re.I), EventType.ERROR),
+    (re.compile(r"Connection refused", re.I), EventType.ERROR),
+    (re.compile(r"Timeout(?:Error)?", re.I), EventType.ERROR),
+    (re.compile(r"✗", re.I), EventType.ERROR),  # Claude Code error indicator
+]
+
+COMPLETION_PATTERNS: List[Tuple[re.Pattern, EventType]] = [
+    (
+        re.compile(r"(?:Done|Complete|Finished|Success)[\.\!]?\s*$", re.I | re.M),
+        EventType.TASK_COMPLETE,
+    ),
+    (re.compile(r"Successfully (.+)", re.I), EventType.TASK_COMPLETE),
+    (
+        re.compile(r"I(?:'ve| have) (?:completed|finished|done) (.+)", re.I),
+        EventType.TASK_COMPLETE,
+    ),
+    (re.compile(r"Task (?:complete|finished)", re.I), EventType.TASK_COMPLETE),
+]
+
+CLARIFICATION_PATTERNS: List[Tuple[re.Pattern, EventType]] = [
+    (
+        re.compile(
+            r"Could you (?:please )?(?:clarify|explain|provide more details)", re.I
+        ),
+        EventType.CLARIFICATION,
+    ),
+    (re.compile(r"I need more information about", re.I), EventType.CLARIFICATION),
+    (re.compile(r"What do you mean by", re.I), EventType.CLARIFICATION),
+    (re.compile(r"Can you be more specific", re.I), EventType.CLARIFICATION),
+]
+
+# Patterns to ignore (inside code blocks, etc.)
+CODE_BLOCK_PATTERN = re.compile(r"```[\s\S]*?```", re.M)
+INLINE_CODE_PATTERN = re.compile(r"`[^`]+`")
+
+ALL_PATTERNS = {
+    "decision": DECISION_PATTERNS,
+    "approval": APPROVAL_PATTERNS,
+    "error": ERROR_PATTERNS,
+    "completion": COMPLETION_PATTERNS,
+    "clarification": CLARIFICATION_PATTERNS,
+}

claude_mpm/commander/persistence/__init__.py

@@ -0,0 +1,11 @@
+"""Persistence layer for MPM Commander.
+
+This module provides state persistence and recovery capabilities for
+the Commander daemon, including atomic writes and graceful recovery.
+"""
+
+from .event_store import EventStore
+from .state_store import StateStore
+from .work_store import WorkStore
+
+__all__ = ["EventStore", "StateStore", "WorkStore"]

claude_mpm/commander/persistence/event_store.py

@@ -0,0 +1,274 @@
+"""Event persistence for MPM Commander.
+
+This module handles persistence and recovery of the event queue/inbox,
+including append-only event logging and efficient event removal.
+"""
+
+import asyncio
+import json
+import logging
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ..models.events import Event, EventPriority, EventStatus, EventType
+
+logger = logging.getLogger(__name__)
+
+
+class EventStore:
+    """Persists and recovers events.
+
+    Provides efficient event persistence with:
+    - Batch save of all events
+    - Append-only logging for real-time persistence
+    - Safe event removal
+    - Atomic writes to prevent corruption
+
+    Attributes:
+        state_dir: Directory for state files
+        events_path: Path to events.json
+
+    Example:
+        >>> store = EventStore(Path("~/.claude-mpm/commander"))
+        >>> await store.save_events(inbox)
+        >>> events = await store.load_events()
+    """
+
+    VERSION = "1.0"
+
+    def __init__(self, state_dir: Path):
+        """Initialize event store.
+
+        Args:
+            state_dir: Directory for state files (created if needed)
+        """
+        self.state_dir = state_dir.expanduser()
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+        self.events_path = self.state_dir / "events.json"
+
+        logger.info(f"Initialized EventStore at {self.state_dir}")
+
+    async def save_events(self, inbox: "Inbox") -> None:  # noqa: F821
+        """Save pending events to disk.
+
+        Args:
+            inbox: Inbox containing events to persist
+
+        Raises:
+            IOError: If write fails
+        """
+        # Get all pending events from event manager
+        events = inbox.events.get_pending()
+
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "events": [self._serialize_event(e) for e in events],
+        }
+
+        # Run sync I/O in executor
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._atomic_write, self.events_path, data
+        )
+
+        logger.info(f"Saved {len(events)} events to {self.events_path}")
+
+    async def load_events(self) -> List[Event]:
+        """Load events from disk.
+
+        Returns:
+            List of Event instances (empty if file missing or corrupt)
+        """
+        if not self.events_path.exists():
+            logger.info("No events file found, returning empty list")
+            return []
+
+        try:
+            # Run sync I/O in executor
+            data = await asyncio.get_event_loop().run_in_executor(
+                None, self._read_json, self.events_path
+            )
+
+            if data.get("version") != self.VERSION:
+                logger.warning(
+                    f"Version mismatch: expected {self.VERSION}, "
+                    f"got {data.get('version')}"
+                )
+
+            events = [self._deserialize_event(e) for e in data.get("events", [])]
+
+            logger.info(f"Loaded {len(events)} events from {self.events_path}")
+            return events
+
+        except Exception as e:
+            logger.error(f"Failed to load events: {e}", exc_info=True)
+            return []
+
+    async def append_event(self, event: Event) -> None:
+        """Append single event (for real-time persistence).
+
+        Loads existing events, adds new event, and saves atomically.
+        For high-frequency updates, consider batching with save_events().
+
+        Args:
+            event: Event to append
+
+        Raises:
+            IOError: If write fails
+        """
+        # Load existing events
+        events = await self.load_events()
+
+        # Add new event
+        events.append(event)
+
+        # Save back
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "events": [self._serialize_event(e) for e in events],
+        }
+
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._atomic_write, self.events_path, data
+        )
+
+        logger.debug(f"Appended event {event.id} to {self.events_path}")
+
+    async def remove_event(self, event_id: str) -> None:
+        """Remove resolved event from store.
+
+        Args:
+            event_id: ID of event to remove
+
+        Raises:
+            IOError: If write fails
+        """
+        # Load existing events
+        events = await self.load_events()
+
+        # Filter out resolved event
+        filtered = [e for e in events if e.id != event_id]
+
+        if len(filtered) == len(events):
+            logger.warning(f"Event {event_id} not found in store")
+            return
+
+        # Save back
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "events": [self._serialize_event(e) for e in filtered],
+        }
+
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._atomic_write, self.events_path, data
+        )
+
+        logger.debug(f"Removed event {event_id} from {self.events_path}")
+
+    def _atomic_write(self, path: Path, data: Dict) -> None:
+        """Write atomically (write to temp, then rename).
+
+        Args:
+            path: Target file path
+            data: Data to serialize as JSON
+
+        Raises:
+            IOError: If write fails
+        """
+        # Write to temporary file in same directory
+        fd, tmp_path = tempfile.mkstemp(
+            dir=path.parent, prefix=f".{path.name}.", suffix=".tmp"
+        )
+
+        try:
+            with open(fd, "w") as f:
+                json.dump(data, f, indent=2)
+
+            # Atomic rename
+            Path(tmp_path).rename(path)
+
+            logger.debug(f"Atomically wrote to {path}")
+
+        except Exception as e:
+            # Clean up temp file on error
+            try:
+                Path(tmp_path).unlink()
+            except Exception:  # nosec B110
+                pass  # Ignore errors during cleanup
+            raise OSError(f"Failed to write {path}: {e}") from e
+
+    def _read_json(self, path: Path) -> Dict:
+        """Read JSON file.
+
+        Args:
+            path: File to read
+
+        Returns:
+            Parsed JSON data
+
+        Raises:
+            IOError: If read fails
+        """
+        with open(path) as f:
+            return json.load(f)
+
+    def _serialize_event(self, event: Event) -> Dict[str, Any]:
+        """Serialize Event to JSON-compatible dict.
+
+        Args:
+            event: Event instance
+
+        Returns:
+            JSON-serializable dict
+        """
+        return {
+            "id": event.id,
+            "project_id": event.project_id,
+            "type": event.type.value,
+            "priority": event.priority.value,
+            "title": event.title,
+            "session_id": event.session_id,
+            "status": event.status.value,
+            "content": event.content,
+            "context": event.context,
+            "options": event.options,
+            "response": event.response,
+            "responded_at": (
+                event.responded_at.isoformat() if event.responded_at else None
+            ),
+            "created_at": event.created_at.isoformat(),
+        }
+
+    def _deserialize_event(self, data: Dict[str, Any]) -> Event:
+        """Deserialize Event from JSON dict.
+
+        Args:
+            data: Serialized event data
+
+        Returns:
+            Event instance
+        """
+        return Event(
+            id=data["id"],
+            project_id=data["project_id"],
+            type=EventType(data["type"]),
+            priority=EventPriority(data["priority"]),
+            title=data["title"],
+            session_id=data.get("session_id"),
+            status=EventStatus(data["status"]),
+            content=data.get("content", ""),
+            context=data.get("context", {}),
+            options=data.get("options"),
+            response=data.get("response"),
+            responded_at=(
+                datetime.fromisoformat(data["responded_at"])
+                if data.get("responded_at")
+                else None
+            ),
+            created_at=datetime.fromisoformat(data["created_at"]),
+        )