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

claude_mpm/commander/work/queue.py

@@ -0,0 +1,405 @@
+"""Work queue management for MPM Commander.
+
+This module provides WorkQueue for managing work items within a project,
+including priority-based execution and dependency resolution.
+"""
+
+import logging
+import uuid
+from typing import List, Optional
+
+from ..models.work import WorkItem, WorkPriority, WorkState
+
+logger = logging.getLogger(__name__)
+
+
+class WorkQueue:
+    """Manages work items for a project.
+
+    Provides operations for adding, retrieving, and updating work items
+    with support for priority-based execution and linear dependencies.
+
+    Attributes:
+        project_id: ID of the project this queue belongs to
+        _items: Internal storage of work items by ID
+
+    Example:
+        >>> queue = WorkQueue("proj-123")
+        >>> work = queue.add("Implement feature X", priority=WorkPriority.HIGH)
+        >>> next_work = queue.get_next()
+        >>> queue.start(next_work.id)
+        >>> queue.complete(next_work.id, "Feature implemented")
+    """
+
+    def __init__(self, project_id: str):
+        """Initialize work queue for a project.
+
+        Args:
+            project_id: Unique project identifier
+        """
+        self.project_id = project_id
+        self._items: dict[str, WorkItem] = {}
+        logger.debug(f"Initialized WorkQueue for project {project_id}")
+
+    def add(
+        self,
+        content: str,
+        priority: WorkPriority = WorkPriority.MEDIUM,
+        depends_on: Optional[List[str]] = None,
+    ) -> WorkItem:
+        """Add work item to queue.
+
+        Args:
+            content: The task/message to execute
+            priority: Execution priority (default: MEDIUM)
+            depends_on: List of work item IDs that must complete first
+
+        Returns:
+            The created WorkItem
+
+        Example:
+            >>> work = queue.add("Fix bug #123", WorkPriority.HIGH)
+            >>> work.state
+            <WorkState.QUEUED: 'queued'>
+        """
+        work_id = f"work-{uuid.uuid4().hex[:8]}"
+
+        work = WorkItem(
+            id=work_id,
+            project_id=self.project_id,
+            content=content,
+            state=WorkState.QUEUED,
+            priority=priority,
+            depends_on=depends_on or [],
+        )
+
+        self._items[work_id] = work
+        logger.info(
+            f"Added work item {work_id} to project {self.project_id} "
+            f"with priority {priority.name}"
+        )
+
+        return work
+
+    def get_next(self) -> Optional[WorkItem]:
+        """Get next ready work item (dependencies satisfied, highest priority).
+
+        Returns work items in this order:
+        1. QUEUED items with satisfied dependencies
+        2. Ordered by priority (CRITICAL > HIGH > MEDIUM > LOW)
+        3. Within same priority, oldest first (FIFO)
+
+        Returns:
+            Next executable work item, or None if queue empty or all blocked
+
+        Example:
+            >>> work = queue.get_next()
+            >>> if work:
+            ...     print(f"Next: {work.content}")
+        """
+        # Get all completed work IDs for dependency checking
+        completed = self.completed_ids
+
+        # Filter for QUEUED items with satisfied dependencies
+        ready_items = [
+            item
+            for item in self._items.values()
+            if item.state == WorkState.QUEUED and item.can_start(completed)
+        ]
+
+        if not ready_items:
+            return None
+
+        # Sort by priority (descending), then by created_at (ascending)
+        ready_items.sort(key=lambda x: (-x.priority.value, x.created_at))
+
+        next_item = ready_items[0]
+        logger.debug(
+            f"Next work item for {self.project_id}: {next_item.id} "
+            f"(priority={next_item.priority.name})"
+        )
+
+        return next_item
+
+    def start(self, work_id: str) -> bool:
+        """Mark work as in progress.
+
+        Args:
+            work_id: Work item ID to start
+
+        Returns:
+            True if state changed, False if not found or invalid state
+
+        Example:
+            >>> queue.start("work-123")
+            True
+        """
+        item = self._items.get(work_id)
+        if not item:
+            logger.warning(f"Work item {work_id} not found")
+            return False
+
+        if item.state != WorkState.QUEUED:
+            logger.warning(
+                f"Work item {work_id} not QUEUED (current: {item.state.value})"
+            )
+            return False
+
+        from datetime import datetime, timezone
+
+        item.state = WorkState.IN_PROGRESS
+        item.started_at = datetime.now(timezone.utc)
+
+        logger.info(f"Started work item {work_id}")
+        return True
+
+    def complete(self, work_id: str, result: Optional[str] = None) -> bool:
+        """Mark work as completed.
+
+        Args:
+            work_id: Work item ID to complete
+            result: Optional result message
+
+        Returns:
+            True if state changed, False if not found or invalid state
+
+        Example:
+            >>> queue.complete("work-123", "Successfully implemented feature")
+            True
+        """
+        item = self._items.get(work_id)
+        if not item:
+            logger.warning(f"Work item {work_id} not found")
+            return False
+
+        if item.state not in (WorkState.IN_PROGRESS, WorkState.BLOCKED):
+            logger.warning(
+                f"Work item {work_id} not IN_PROGRESS or BLOCKED "
+                f"(current: {item.state.value})"
+            )
+            return False
+
+        from datetime import datetime, timezone
+
+        item.state = WorkState.COMPLETED
+        item.completed_at = datetime.now(timezone.utc)
+        item.result = result
+
+        logger.info(f"Completed work item {work_id}")
+        return True
+
+    def fail(self, work_id: str, error: str) -> bool:
+        """Mark work as failed.
+
+        Args:
+            work_id: Work item ID to fail
+            error: Error message
+
+        Returns:
+            True if state changed, False if not found or invalid state
+
+        Example:
+            >>> queue.fail("work-123", "Execution timeout")
+            True
+        """
+        item = self._items.get(work_id)
+        if not item:
+            logger.warning(f"Work item {work_id} not found")
+            return False
+
+        if item.state not in (WorkState.IN_PROGRESS, WorkState.BLOCKED):
+            logger.warning(
+                f"Work item {work_id} not IN_PROGRESS or BLOCKED "
+                f"(current: {item.state.value})"
+            )
+            return False
+
+        from datetime import datetime, timezone
+
+        item.state = WorkState.FAILED
+        item.completed_at = datetime.now(timezone.utc)
+        item.error = error
+
+        logger.error(f"Failed work item {work_id}: {error}")
+        return True
+
+    def block(self, work_id: str, reason: str) -> bool:
+        """Mark work as blocked (e.g., waiting for event resolution).
+
+        Args:
+            work_id: Work item ID to block
+            reason: Reason for blocking
+
+        Returns:
+            True if state changed, False if not found or invalid state
+
+        Example:
+            >>> queue.block("work-123", "Waiting for user approval")
+            True
+        """
+        item = self._items.get(work_id)
+        if not item:
+            logger.warning(f"Work item {work_id} not found")
+            return False
+
+        if item.state != WorkState.IN_PROGRESS:
+            logger.warning(
+                f"Work item {work_id} not IN_PROGRESS (current: {item.state.value})"
+            )
+            return False
+
+        item.state = WorkState.BLOCKED
+        item.metadata["block_reason"] = reason
+
+        logger.info(f"Blocked work item {work_id}: {reason}")
+        return True
+
+    def unblock(self, work_id: str) -> bool:
+        """Unblock work item (resume execution).
+
+        Args:
+            work_id: Work item ID to unblock
+
+        Returns:
+            True if state changed, False if not found or invalid state
+
+        Example:
+            >>> queue.unblock("work-123")
+            True
+        """
+        item = self._items.get(work_id)
+        if not item:
+            logger.warning(f"Work item {work_id} not found")
+            return False
+
+        if item.state != WorkState.BLOCKED:
+            logger.warning(
+                f"Work item {work_id} not BLOCKED (current: {item.state.value})"
+            )
+            return False
+
+        item.state = WorkState.IN_PROGRESS
+        if "block_reason" in item.metadata:
+            del item.metadata["block_reason"]
+
+        logger.info(f"Unblocked work item {work_id}")
+        return True
+
+    def cancel(self, work_id: str) -> bool:
+        """Cancel pending work.
+
+        Args:
+            work_id: Work item ID to cancel
+
+        Returns:
+            True if state changed, False if not found or invalid state
+
+        Example:
+            >>> queue.cancel("work-123")
+            True
+        """
+        item = self._items.get(work_id)
+        if not item:
+            logger.warning(f"Work item {work_id} not found")
+            return False
+
+        if item.state not in (WorkState.PENDING, WorkState.QUEUED, WorkState.BLOCKED):
+            logger.warning(
+                f"Cannot cancel work item {work_id} in state {item.state.value}"
+            )
+            return False
+
+        from datetime import datetime, timezone
+
+        item.state = WorkState.CANCELLED
+        item.completed_at = datetime.now(timezone.utc)
+
+        logger.info(f"Cancelled work item {work_id}")
+        return True
+
+    def get(self, work_id: str) -> Optional[WorkItem]:
+        """Get work item by ID.
+
+        Args:
+            work_id: Work item ID to retrieve
+
+        Returns:
+            WorkItem if found, None otherwise
+
+        Example:
+            >>> work = queue.get("work-123")
+            >>> if work:
+            ...     print(work.content)
+        """
+        return self._items.get(work_id)
+
+    def list(self, state: Optional[WorkState] = None) -> List[WorkItem]:
+        """List work items, optionally filtered by state.
+
+        Args:
+            state: Optional state filter
+
+        Returns:
+            List of work items matching criteria (may be empty)
+
+        Example:
+            >>> queued = queue.list(WorkState.QUEUED)
+            >>> all_items = queue.list()
+        """
+        if state is None:
+            return list(self._items.values())
+
+        return [item for item in self._items.values() if item.state == state]
+
+    @property
+    def pending_count(self) -> int:
+        """Get count of pending/queued work items.
+
+        Returns:
+            Number of items in PENDING or QUEUED state
+
+        Example:
+            >>> count = queue.pending_count
+        """
+        return sum(
+            1
+            for item in self._items.values()
+            if item.state in (WorkState.PENDING, WorkState.QUEUED)
+        )
+
+    @property
+    def completed_ids(self) -> set[str]:
+        """Get IDs of completed work items (for dependency checking).
+
+        Returns:
+            Set of work item IDs in COMPLETED state
+
+        Example:
+            >>> completed = queue.completed_ids
+        """
+        return {
+            item.id
+            for item in self._items.values()
+            if item.state == WorkState.COMPLETED
+        }
+
+    def load_items(self, items: List[WorkItem]) -> None:
+        """Load work items from persistence.
+
+        Args:
+            items: List of WorkItem instances to load
+
+        Example:
+            >>> queue.load_items(persisted_items)
+        """
+        for item in items:
+            if item.project_id != self.project_id:
+                logger.warning(
+                    f"Skipping work item {item.id} - wrong project "
+                    f"(expected {self.project_id}, got {item.project_id})"
+                )
+                continue
+
+            self._items[item.id] = item
+
+        logger.info(f"Loaded {len(items)} work items for project {self.project_id}")

claude_mpm/commander/workflow/__init__.py

@@ -0,0 +1,27 @@
+"""Event resolution workflow for MPM Commander.
+
+This package provides event handling and notification capabilities for
+managing blocking events that require user input.
+
+Modules:
+    event_handler: Handles blocking events and session pause/resume
+    notifier: Sends notifications for events and resolutions
+
+Classes:
+    EventHandler: Main event resolution coordinator
+    Notifier: Notification delivery system
+    NotifierConfig: Configuration for notification channels
+
+Example:
+    >>> from claude_mpm.commander.workflow import EventHandler, Notifier
+    >>> from claude_mpm.commander.workflow import NotifierConfig
+    >>>
+    >>> notifier = Notifier(NotifierConfig(log_level="INFO"))
+    >>> handler = EventHandler(inbox, sessions)
+    >>> await handler.process_event(event)
+"""
+
+from .event_handler import EventHandler
+from .notifier import Notifier, NotifierConfig
+
+__all__ = ["EventHandler", "Notifier", "NotifierConfig"]

claude_mpm/commander/workflow/event_handler.py

@@ -0,0 +1,219 @@
+"""Event handler for pause/resume workflow on blocking events.
+
+This module provides EventHandler which manages blocking events that require
+user input and coordinates session pause/resume.
+"""
+
+import logging
+from typing import Dict, List, Optional
+
+from ..inbox import Inbox
+from ..models.events import BLOCKING_EVENTS, Event, EventStatus
+from ..project_session import ProjectSession
+
+logger = logging.getLogger(__name__)
+
+
+class EventHandler:
+    """Handles events requiring user resolution and session pause/resume.
+
+    This class detects blocking events (permission requests, errors, confirmations),
+    pauses the associated project session, and resumes execution after the event
+    is resolved with a user response.
+
+    Attributes:
+        inbox: Inbox for event management
+        session_manager: Dict mapping project_id to ProjectSession
+
+    Example:
+        >>> handler = EventHandler(inbox, sessions)
+        >>> await handler.process_event(event)  # Pauses if blocking
+        >>> success = await handler.resolve_event(event_id, "User response")
+    """
+
+    def __init__(
+        self, inbox: Inbox, session_manager: Dict[str, ProjectSession]
+    ) -> None:
+        """Initialize event handler.
+
+        Args:
+            inbox: Inbox instance for event access
+            session_manager: Dict mapping project_id -> ProjectSession
+
+        Raises:
+            ValueError: If inbox or session_manager is None
+        """
+        if inbox is None:
+            raise ValueError("Inbox cannot be None")
+        if session_manager is None:
+            raise ValueError("Session manager cannot be None")
+
+        self.inbox = inbox
+        self.session_manager = session_manager
+        self._event_manager = inbox.events
+
+        logger.debug("EventHandler initialized")
+
+    async def process_event(self, event: Event) -> None:
+        """Process an event - pause session if blocking.
+
+        If the event is blocking (requires user input), pauses the associated
+        project session until the event is resolved.
+
+        Args:
+            event: Event to process
+
+        Example:
+            >>> await handler.process_event(error_event)
+            # Session paused for project
+        """
+        if not self.is_blocking(event):
+            logger.debug(
+                "Event %s is non-blocking (%s), no pause needed",
+                event.id,
+                event.type.value,
+            )
+            return
+
+        logger.info(
+            "Processing blocking event %s for project %s: %s",
+            event.id,
+            event.project_id,
+            event.title,
+        )
+
+        # Get the project session
+        session = self.session_manager.get(event.project_id)
+        if not session:
+            logger.warning(
+                "No session found for project %s, cannot pause", event.project_id
+            )
+            return
+
+        # Pause the session
+        try:
+            await session.pause(f"Event {event.id}: {event.title}")
+            logger.info(
+                "Paused session for project %s due to event %s",
+                event.project_id,
+                event.id,
+            )
+        except Exception as e:
+            logger.error(
+                "Failed to pause session for project %s: %s", event.project_id, e
+            )
+
+    async def resolve_event(self, event_id: str, response: str) -> bool:
+        """Resolve an event with user response and resume session if applicable.
+
+        Marks the event as resolved, sends the response to the runtime, and
+        resumes the project session if it was paused for this event.
+
+        Args:
+            event_id: ID of event to resolve
+            response: User's response to the event
+
+        Returns:
+            True if resolution successful and session resumed, False otherwise
+
+        Raises:
+            KeyError: If event_id not found
+
+        Example:
+            >>> success = await handler.resolve_event("evt_123", "Use authlib")
+            >>> if success:
+            ...     print("Event resolved and session resumed")
+        """
+        # Get the event
+        event = self._event_manager.get(event_id)
+        if not event:
+            raise KeyError(f"Event not found: {event_id}")
+
+        logger.info("Resolving event %s: %s", event_id, response[:50])
+
+        # Check if event WAS blocking BEFORE resolving
+        was_blocking = self.is_blocking(event)
+
+        # Mark event as resolved
+        self._event_manager.respond(event_id, response)
+
+        # If event was NOT blocking, no need to resume
+        if not was_blocking:
+            logger.debug("Event %s was non-blocking, no resume needed", event_id)
+            return True
+
+        # Get the project session
+        session = self.session_manager.get(event.project_id)
+        if not session:
+            logger.warning(
+                "No session found for project %s, cannot resume", event.project_id
+            )
+            return False
+
+        # Check if session was paused for this event
+        if (
+            session.pause_reason
+            and event_id in session.pause_reason
+            and session.state.value == "paused"
+        ):
+            try:
+                # Send response to the runtime
+                if session.active_pane and session.executor:
+                    await session.executor.send_message(session.active_pane, response)
+                    logger.debug("Sent response to pane %s", session.active_pane)
+
+                # Resume the session
+                await session.resume()
+                logger.info(
+                    "Resumed session for project %s after resolving event %s",
+                    event.project_id,
+                    event_id,
+                )
+                return True
+
+            except Exception as e:
+                logger.error(
+                    "Failed to resume session for project %s: %s", event.project_id, e
+                )
+                return False
+        else:
+            logger.debug("Session not paused for event %s, no resume needed", event_id)
+            return True
+
+    async def get_pending_events(self, project_id: Optional[str] = None) -> List[Event]:
+        """Get unresolved events, optionally filtered by project.
+
+        Args:
+            project_id: If provided, only return events for this project
+
+        Returns:
+            List of pending events sorted by priority and time
+
+        Example:
+            >>> all_pending = await handler.get_pending_events()
+            >>> project_pending = await handler.get_pending_events("proj_123")
+        """
+        return self._event_manager.get_pending(project_id)
+
+    def is_blocking(self, event: Event) -> bool:
+        """Check if event type requires pausing execution.
+
+        Blocking event types:
+        - permission_request: Requires user approval
+        - error: Critical error blocking progress
+        - confirmation_request: User confirmation needed
+        - decision_needed: User must choose option
+        - approval: Destructive action needs approval
+
+        Args:
+            event: Event to check
+
+        Returns:
+            True if event blocks progress, False otherwise
+
+        Example:
+            >>> if handler.is_blocking(event):
+            ...     await handler.process_event(event)
+        """
+        # Check if event type is blocking and status is pending
+        return event.type in BLOCKING_EVENTS and event.status == EventStatus.PENDING