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

claude_mpm/commander/polling/output_buffer.py

@@ -0,0 +1,49 @@
+"""Output buffer for tracking session output changes."""
+
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional
+
+
+@dataclass
+class OutputBuffer:
+    """Tracks output from a session and detects changes."""
+
+    session_id: str
+    content: str = ""
+    last_hash: str = ""
+    last_update: Optional[datetime] = None
+    lines_captured: int = 0
+
+    def update(self, new_content: str) -> tuple[bool, str]:
+        """Update buffer with new content.
+
+        Args:
+            new_content: The new output content to check
+
+        Returns:
+            Tuple of (has_changed, new_lines_only)
+            - has_changed: True if content changed since last update
+            - new_lines_only: Only the new lines added (diff)
+        """
+        new_hash = hashlib.md5(new_content.encode(), usedforsecurity=False).hexdigest()
+        if new_hash == self.last_hash:
+            return False, ""
+
+        # Find new lines (diff)
+        old_lines = self.content.split("\n") if self.content else []
+        new_lines = new_content.split("\n")
+
+        # Simple diff: new lines at the end
+        if len(new_lines) > len(old_lines):
+            diff = "\n".join(new_lines[len(old_lines) :])
+        else:
+            diff = new_content  # Content replaced entirely
+
+        self.content = new_content
+        self.last_hash = new_hash
+        self.last_update = datetime.now(timezone.utc)
+        self.lines_captured = len(new_lines)
+
+        return True, diff

claude_mpm/commander/polling/output_poller.py

@@ -0,0 +1,153 @@
+"""Output polling loop for MPM Commander."""
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Callable, Dict, Optional
+
+from ..models.project import ProjectState, ToolSession
+from ..registry import ProjectRegistry
+from ..tmux_orchestrator import TmuxOrchestrator
+from .event_detector import BasicEventDetector
+from .output_buffer import OutputBuffer
+
+if TYPE_CHECKING:
+    from .event_detector import DetectedEvent
+
+logger = logging.getLogger(__name__)
+
+
+class OutputPoller:
+    """Polls tmux sessions for new output and detects events."""
+
+    def __init__(
+        self,
+        tmux: TmuxOrchestrator,
+        registry: ProjectRegistry,
+        poll_interval: float = 0.5,
+        capture_lines: int = 1000,
+    ):
+        """Initialize output poller.
+
+        Args:
+            tmux: TmuxOrchestrator instance for capturing output
+            registry: ProjectRegistry for state management
+            poll_interval: Seconds between polls (default: 0.5)
+            capture_lines: Number of lines to capture from tmux (default: 1000)
+        """
+        self.tmux = tmux
+        self.registry = registry
+        self.poll_interval = poll_interval
+        self.capture_lines = capture_lines
+        self.detector = BasicEventDetector()
+        self.buffers: Dict[str, OutputBuffer] = {}
+        self._running = False
+        self._task: Optional[asyncio.Task[None]] = None
+        self.on_error: Optional[Callable[[str, DetectedEvent], None]] = None
+        self.on_idle: Optional[Callable[[str], None]] = None
+
+    async def start(self) -> None:
+        """Start the polling loop."""
+        if self._running:
+            return
+        self._running = True
+        self._task = asyncio.create_task(self._poll_loop())
+        logger.info("Output poller started (interval: %.2fs)", self.poll_interval)
+
+    async def stop(self) -> None:
+        """Stop the polling loop."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        logger.info("Output poller stopped")
+
+    async def _poll_loop(self) -> None:
+        """Main polling loop - runs until stopped."""
+        while self._running:
+            try:
+                await self._poll_all_sessions()
+            except Exception as e:
+                logger.error("Polling error: %s", e, exc_info=True)
+            await asyncio.sleep(self.poll_interval)
+
+    async def _poll_all_sessions(self) -> None:
+        """Poll all active sessions for new output."""
+        for project in self.registry.list_all():
+            for session_id, session in project.sessions.items():
+                if session.status in ("stopped", "error"):
+                    continue
+
+                await self._poll_session(project.id, session)
+
+    async def _poll_session(self, project_id: str, session: ToolSession) -> None:
+        """Poll a single session for output changes.
+
+        Args:
+            project_id: ID of the project owning the session
+            session: Session object to poll
+        """
+        # Skip stopped or errored sessions
+        if session.status in ("stopped", "error"):
+            return
+
+        # Get or create buffer
+        if session.id not in self.buffers:
+            self.buffers[session.id] = OutputBuffer(session_id=session.id)
+
+        buffer = self.buffers[session.id]
+
+        # Capture output from tmux
+        try:
+            output = self.tmux.capture_output(
+                session.tmux_target, lines=self.capture_lines
+            )
+        except Exception as e:
+            logger.warning("Failed to capture output for %s: %s", session.id, e)
+            return
+
+        # Check for changes
+        has_changed, new_content = buffer.update(output)
+        if not has_changed:
+            return
+
+        # Update session output buffer
+        session.output_buffer = output
+        session.last_output_at = datetime.now(timezone.utc)
+
+        # Detect events - errors take priority
+        error_event = self.detector.detect_error(new_content)
+        if error_event:
+            logger.warning("Error detected in %s: %s", session.id, error_event.content)
+            session.status = "error"
+            self.registry.update_state(
+                project_id, ProjectState.ERROR, error_event.content
+            )
+            if self.on_error:
+                self.on_error(session.id, error_event)
+            return
+
+        # Check for idle state
+        is_idle = self.detector.detect_idle(output)
+        if is_idle:
+            if session.status != "idle":
+                logger.debug("Session %s now idle", session.id)
+                session.status = "idle"
+                if self.on_idle:
+                    self.on_idle(session.id)
+        elif session.status == "idle":
+            logger.debug("Session %s now running", session.id)
+            session.status = "running"
+            self.registry.update_state(project_id, ProjectState.WORKING)
+
+    def clear_buffer(self, session_id: str) -> None:
+        """Clear the buffer for a session.
+
+        Args:
+            session_id: ID of session to clear buffer for
+        """
+        if session_id in self.buffers:
+            del self.buffers[session_id]

claude_mpm/commander/project_session.py

@@ -0,0 +1,268 @@
+"""Project session lifecycle coordinator for MPM Commander.
+
+This module manages per-project execution state, coordinating between
+runtime processes, events, and work queue.
+"""
+
+import logging
+from enum import Enum
+from typing import Optional
+
+from .models import Project, ProjectState
+from .runtime.executor import RuntimeExecutor
+from .runtime.monitor import RuntimeMonitor
+from .tmux_orchestrator import TmuxOrchestrator
+
+logger = logging.getLogger(__name__)
+
+
+class SessionState(Enum):
+    """Project session execution state.
+
+    Attributes:
+        IDLE: No active work, ready to start
+        STARTING: Initializing session resources
+        RUNNING: Actively executing work
+        PAUSED: Execution paused (e.g., waiting for event resolution)
+        STOPPING: Shutting down gracefully
+        STOPPED: Session terminated
+    """
+
+    IDLE = "idle"
+    STARTING = "starting"
+    RUNNING = "running"
+    PAUSED = "paused"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+
+
+class ProjectSession:
+    """Manages lifecycle of a single project's work execution.
+
+    Coordinates between runtime executor, event system, and work queue
+    for autonomous task execution within a project.
+
+    Attributes:
+        project: Associated project instance
+        orchestrator: Tmux orchestrator for process management
+        executor: RuntimeExecutor for spawning/managing processes
+        monitor: RuntimeMonitor for output monitoring and event detection
+        state: Current session execution state
+        pause_reason: Reason for pause (e.g., event ID)
+        active_pane: Tmux pane target for active runtime, if any
+
+    Example:
+        >>> session = ProjectSession(project, tmux_orchestrator, executor, monitor)
+        >>> await session.start()
+        >>> session.state
+        <SessionState.RUNNING: 'running'>
+        >>> await session.pause("Event requires user input")
+        >>> await session.resume()
+        >>> await session.stop()
+    """
+
+    def __init__(
+        self,
+        project: Project,
+        orchestrator: TmuxOrchestrator,
+        executor: Optional[RuntimeExecutor] = None,
+        monitor: Optional[RuntimeMonitor] = None,
+    ):
+        """Initialize project session.
+
+        Args:
+            project: Project instance to manage
+            orchestrator: TmuxOrchestrator for process control
+            executor: Optional RuntimeExecutor (created if not provided)
+            monitor: Optional RuntimeMonitor (not used if not provided)
+
+        Raises:
+            ValueError: If project or orchestrator is None
+        """
+        if project is None:
+            raise ValueError("Project cannot be None")
+        if orchestrator is None:
+            raise ValueError("Orchestrator cannot be None")
+
+        self.project = project
+        self.orchestrator = orchestrator
+        self.executor = executor or RuntimeExecutor(orchestrator)
+        self.monitor = monitor
+        self._state = SessionState.IDLE
+        self.pause_reason: Optional[str] = None
+        self.active_pane: Optional[str] = None
+
+        logger.info(f"Created ProjectSession for project {project.id}")
+
+    @property
+    def state(self) -> SessionState:
+        """Get current session state.
+
+        Returns:
+            Current SessionState
+        """
+        return self._state
+
+    async def start(self) -> None:
+        """Initialize and start project session.
+
+        Transitions from IDLE → STARTING → RUNNING.
+        Spawns Claude Code via RuntimeExecutor and starts output monitoring
+        via RuntimeMonitor if available.
+
+        Raises:
+            RuntimeError: If session not in IDLE state
+        """
+        if self._state != SessionState.IDLE:
+            raise RuntimeError(
+                f"Cannot start session in state {self._state}. Must be IDLE."
+            )
+
+        logger.info(f"Starting session for project {self.project.id}")
+        self._state = SessionState.STARTING
+
+        try:
+            # Create tmux session if needed
+            if not self.orchestrator.session_exists():
+                self.orchestrator.create_session()
+                logger.debug("Created tmux session")
+
+            # Spawn Claude Code process
+            self.active_pane = await self.executor.spawn(self.project, command="claude")
+            logger.info(f"Spawned Claude Code in pane {self.active_pane}")
+
+            # Start monitoring if monitor available
+            if self.monitor:
+                await self.monitor.start_monitoring(self.active_pane, self.project.id)
+                logger.debug(f"Started monitoring pane {self.active_pane}")
+
+            # Update project state
+            self.project.state = ProjectState.IDLE
+            self.project.state_reason = None
+
+            # Transition to RUNNING
+            self._state = SessionState.RUNNING
+            logger.info(f"Session started for project {self.project.id}")
+
+        except Exception as e:
+            logger.error(f"Failed to start session: {e}")
+            self._state = SessionState.IDLE
+            # Clean up pane if created
+            if self.active_pane:
+                try:
+                    await self.executor.terminate(self.active_pane)
+                except Exception as cleanup_error:
+                    logger.debug(f"Error cleaning up pane: {cleanup_error}")
+                self.active_pane = None
+            raise
+
+    async def pause(self, reason: str) -> None:
+        """Pause execution (e.g., waiting for event resolution).
+
+        Transitions from RUNNING → PAUSED.
+        Execution will not resume until resume() is called.
+
+        Args:
+            reason: Reason for pause (typically event ID or description)
+
+        Raises:
+            RuntimeError: If session not in RUNNING state
+        """
+        if self._state != SessionState.RUNNING:
+            raise RuntimeError(
+                f"Cannot pause session in state {self._state}. Must be RUNNING."
+            )
+
+        logger.info(f"Pausing session for project {self.project.id}: {reason}")
+        self._state = SessionState.PAUSED
+        self.pause_reason = reason
+
+        # Update project state
+        self.project.state = ProjectState.BLOCKED
+        self.project.state_reason = reason
+
+    async def resume(self) -> None:
+        """Resume execution after pause.
+
+        Transitions from PAUSED → RUNNING.
+        Clears pause reason and continues work execution.
+
+        Raises:
+            RuntimeError: If session not in PAUSED state
+        """
+        if self._state != SessionState.PAUSED:
+            raise RuntimeError(
+                f"Cannot resume session in state {self._state}. Must be PAUSED."
+            )
+
+        logger.info(f"Resuming session for project {self.project.id}")
+        self._state = SessionState.RUNNING
+        self.pause_reason = None
+
+        # Update project state
+        self.project.state = ProjectState.WORKING
+        self.project.state_reason = None
+
+    async def stop(self) -> None:
+        """Gracefully stop project session.
+
+        Transitions from any state → STOPPING → STOPPED.
+        Stops monitoring, terminates runtime, and cleans up resources.
+        """
+        logger.info(f"Stopping session for project {self.project.id}")
+        self._state = SessionState.STOPPING
+
+        try:
+            # Stop monitoring if active
+            if self.monitor and self.active_pane:
+                await self.monitor.stop_monitoring(self.active_pane)
+                logger.debug(f"Stopped monitoring pane {self.active_pane}")
+
+            # Terminate active pane
+            if self.active_pane:
+                await self.executor.terminate(self.active_pane)
+                logger.debug(f"Terminated pane {self.active_pane}")
+                self.active_pane = None
+
+            # Clean up any remaining sessions (backward compatibility)
+            for session_id in list(self.project.sessions.keys()):
+                try:
+                    session = self.project.sessions[session_id]
+                    if session.tmux_target:
+                        # Kill tmux pane
+                        self.orchestrator.kill_pane(session.tmux_target)
+                        logger.debug(f"Killed pane {session.tmux_target}")
+                except Exception as e:
+                    logger.warning(f"Error killing session {session_id}: {e}")
+
+            # Update project state
+            self.project.state = ProjectState.IDLE
+            self.project.state_reason = None
+
+            # Transition to STOPPED
+            self._state = SessionState.STOPPED
+            logger.info(f"Session stopped for project {self.project.id}")
+
+        except Exception as e:
+            logger.error(f"Error during session stop: {e}")
+            self._state = SessionState.STOPPED
+            raise
+
+    def is_ready(self) -> bool:
+        """Check if session can start new work.
+
+        Returns:
+            True if session is in RUNNING state (not blocked or paused)
+        """
+        return self._state == SessionState.RUNNING
+
+    def can_accept_work(self) -> bool:
+        """Check if session can accept new work items.
+
+        Returns:
+            True if session is IDLE or RUNNING with no active work
+        """
+        return (
+            self._state in (SessionState.IDLE, SessionState.RUNNING)
+            and self.project.active_work is None
+        )

claude_mpm/commander/proxy/__init__.py

@@ -0,0 +1,12 @@
+"""Output proxy and summarization for MPM Commander."""
+
+from .formatter import OutputFormatter
+from .output_handler import OutputChunk, OutputHandler
+from .relay import OutputRelay
+
+__all__ = [
+    "OutputChunk",
+    "OutputFormatter",
+    "OutputHandler",
+    "OutputRelay",
+]

claude_mpm/commander/proxy/formatter.py

@@ -0,0 +1,89 @@
+"""Formats output for Commander chat display."""
+
+from .output_handler import OutputChunk
+
+
+class OutputFormatter:
+    """Formats Claude Code output for user display."""
+
+    def __init__(self, max_raw_display: int = 500):
+        """Initialize OutputFormatter.
+
+        Args:
+            max_raw_display: Maximum characters of raw output to display.
+        """
+        self.max_raw_display = max_raw_display
+
+    def format_summary(self, chunk: OutputChunk) -> str:
+        """Format a summarized output chunk for display.
+
+        Args:
+            chunk: OutputChunk with summary.
+
+        Returns:
+            Formatted output with summary and optionally truncated raw output.
+        """
+        lines = []
+
+        # Instance header
+        status = "✓" if chunk.is_complete else "⋯"
+        lines.append(f"[{chunk.instance_name}] {status}")
+
+        # Summary if available
+        if chunk.summary:
+            lines.append(f"\n📝 Summary: {chunk.summary}")
+
+        # Show truncated raw output if it's short enough
+        if len(chunk.raw_output) <= self.max_raw_display:
+            lines.append(f"\n```\n{chunk.raw_output}\n```")
+        else:
+            # Show truncated preview
+            preview = chunk.raw_output[: self.max_raw_display]
+            lines.append(
+                f"\n```\n{preview}...\n(truncated, {len(chunk.raw_output)} chars total)\n```"
+            )
+
+        return "".join(lines)
+
+    def format_raw(self, chunk: OutputChunk, truncate: bool = True) -> str:
+        """Format raw output, optionally truncated.
+
+        Args:
+            chunk: OutputChunk to format.
+            truncate: Whether to truncate long output.
+
+        Returns:
+            Formatted raw output.
+        """
+        status = "✓" if chunk.is_complete else "⋯"
+        header = f"[{chunk.instance_name}] {status}"
+
+        raw = chunk.raw_output
+        if truncate and len(raw) > self.max_raw_display:
+            raw = raw[: self.max_raw_display] + "...\n(truncated)"
+
+        return f"{header}\n```\n{raw}\n```"
+
+    def format_status(self, instance_name: str, status: str) -> str:
+        """Format a status message.
+
+        Args:
+            instance_name: Name of the instance.
+            status: Status message.
+
+        Returns:
+            Formatted status message.
+        """
+        return f"[{instance_name}] ℹ️  {status}"
+
+    def format_error(self, instance_name: str, error: str) -> str:
+        """Format an error message.
+
+        Args:
+            instance_name: Name of the instance.
+            error: Error message.
+
+        Returns:
+            Formatted error message.
+        """
+        return f"[{instance_name}] ❌ Error: {error}"