claude-mpm 4.15.2__py3-none-any.whl → 4.20.3__py3-none-any.whl

claude_mpm/services/cli/session_manager.py

@@ -11,8 +11,10 @@ DESIGN DECISIONS:
 - Automatic session cleanup and archiving
 - Thread-safe session operations
 - Non-blocking validation with structured warnings
+- Async-first design with periodic auto-save task
 """
 
+import asyncio
 import gzip
 import json
 import uuid
@@ -217,8 +219,39 @@ class SessionManager(ISessionManager):
         self.config_service = config_service
         self.logger = get_logger("SessionManager")
         self._sessions_cache: Dict[str, SessionInfo] = {}
+        self._auto_save_task: Optional[asyncio.Task] = None
+        self._running = False
         self._load_sessions()
 
+        # Start auto-save task if enabled and event loop is running
+        if config_service:
+            auto_save_enabled = config_service.get("session.auto_save", True)
+            if auto_save_enabled:
+                self._start_auto_save()
+            else:
+                self.logger.info("Auto-save disabled by configuration")
+        else:
+            self.logger.debug("No config service provided, auto-save not started")
+
+    def _start_auto_save(self) -> None:
+        """Start the auto-save background task.
+
+        WHY: Separated from __init__ to allow safe initialization without event loop.
+        Can be called when event loop is available.
+        """
+        try:
+            loop = asyncio.get_running_loop()
+            self._running = True
+            self._auto_save_task = loop.create_task(self._periodic_session_save())
+            self.logger.info("Auto-save task started")
+        except RuntimeError:
+            # No event loop running, schedule for later
+            self.logger.debug(
+                "No event loop running, auto-save will start when loop is available"
+            )
+            # Set flag so we know to start it later
+            self._running = True
+
     def create_session(
         self, context: str = "default", options: Optional[Dict[str, Any]] = None
     ) -> SessionInfo:
@@ -477,6 +510,60 @@ class SessionManager(ISessionManager):
             self.logger.error(f"Failed to load sessions: {e}")
             self._sessions_cache = {}
 
+    async def _periodic_session_save(self) -> None:
+        """Periodically save sessions to disk.
+
+        WHY: Ensures sessions are persisted regularly to prevent data loss.
+        Follows the async pattern from EventAggregator._periodic_cleanup().
+        """
+        if not self.config_service:
+            self.logger.warning("No config service, cannot determine save interval")
+            return
+
+        save_interval = self.config_service.get("session.save_interval", 300)
+        self.logger.info(f"Starting periodic session save (interval: {save_interval}s)")
+
+        while self._running:
+            try:
+                await asyncio.sleep(save_interval)
+
+                if self._sessions_cache:
+                    self._save_sessions()
+                    self.logger.debug(
+                        f"Auto-saved {len(self._sessions_cache)} session(s)"
+                    )
+                else:
+                    self.logger.debug("No sessions to save")
+
+            except asyncio.CancelledError:
+                self.logger.info("Auto-save task cancelled")
+                break
+            except Exception as e:
+                self.logger.error(f"Error in auto-save task: {e}")
+
+    async def cleanup(self) -> None:
+        """Clean up resources and stop background tasks.
+
+        WHY: Ensures graceful shutdown of the SessionManager and all background tasks.
+        """
+        self.logger.info("Shutting down SessionManager...")
+        self._running = False
+
+        # Cancel auto-save task
+        if self._auto_save_task and not self._auto_save_task.done():
+            self._auto_save_task.cancel()
+            try:
+                await self._auto_save_task
+            except asyncio.CancelledError:
+                pass
+
+        # Final save before shutdown
+        if self._sessions_cache:
+            self._save_sessions()
+            self.logger.info(f"Final save: {len(self._sessions_cache)} session(s)")
+
+        self.logger.info("SessionManager shutdown complete")
+
 
 # Context manager for session management
 class ManagedSession:

claude_mpm/services/cli/session_resume_helper.py

@@ -0,0 +1,352 @@
+"""Session Resume Helper Service.
+
+WHY: This service provides automatic session resume detection and prompting for PM startup.
+It detects paused sessions, calculates git changes since pause, and presents resumption
+context to users.
+
+DESIGN DECISIONS:
+- Project-specific session storage (.claude-mpm/sessions/pause/)
+- Non-blocking detection with graceful degradation
+- Git change detection for context updates
+- User-friendly prompts with time elapsed information
+- Integration with existing SessionManager infrastructure
+"""
+
+import json
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class SessionResumeHelper:
+    """Helper for automatic session resume detection and prompting."""
+
+    def __init__(self, project_path: Optional[Path] = None):
+        """Initialize session resume helper.
+
+        Args:
+            project_path: Project root path (default: current directory)
+        """
+        self.project_path = project_path or Path.cwd()
+        self.pause_dir = self.project_path / ".claude-mpm" / "sessions" / "pause"
+
+    def has_paused_sessions(self) -> bool:
+        """Check if there are any paused sessions.
+
+        Returns:
+            True if paused sessions exist, False otherwise
+        """
+        if not self.pause_dir.exists():
+            return False
+
+        # Look for session JSON files
+        session_files = list(self.pause_dir.glob("session-*.json"))
+        return len(session_files) > 0
+
+    def get_most_recent_session(self) -> Optional[Dict[str, Any]]:
+        """Get the most recent paused session.
+
+        Returns:
+            Session data dictionary or None if no sessions found
+        """
+        if not self.pause_dir.exists():
+            return None
+
+        # Find all session files
+        session_files = list(self.pause_dir.glob("session-*.json"))
+        if not session_files:
+            return None
+
+        # Sort by modification time (most recent first)
+        session_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+
+        # Load the most recent session
+        try:
+            with session_files[0].open("r") as f:
+                session_data = json.load(f)
+            session_data["file_path"] = session_files[0]
+            return session_data
+        except Exception as e:
+            logger.error(f"Failed to load session file {session_files[0]}: {e}")
+            return None
+
+    def get_git_changes_since_pause(
+        self, paused_at: str, recent_commits: List[Dict[str, str]]
+    ) -> Tuple[int, List[Dict[str, str]]]:
+        """Calculate git changes since session was paused.
+
+        Args:
+            paused_at: ISO-8601 timestamp when session was paused
+            recent_commits: List of recent commits from session data
+
+        Returns:
+            Tuple of (new_commit_count, new_commits_list)
+        """
+        try:
+            # Parse pause timestamp
+            pause_time = datetime.fromisoformat(paused_at)
+
+            # Get commits since pause time
+            cmd = [
+                "git",
+                "log",
+                f'--since="{pause_time.isoformat()}"',
+                "--pretty=format:%h|%an|%ai|%s",
+                "--all",
+            ]
+
+            result = subprocess.run(
+                cmd,
+                cwd=self.project_path,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            if result.returncode != 0:
+                logger.warning(f"Git log command failed: {result.stderr}")
+                return 0, []
+
+            # Parse commit output
+            new_commits = []
+            for line in result.stdout.strip().split("\n"):
+                if line:
+                    parts = line.split("|", 3)
+                    if len(parts) == 4:
+                        new_commits.append(
+                            {
+                                "sha": parts[0],
+                                "author": parts[1],
+                                "timestamp": parts[2],
+                                "message": parts[3],
+                            }
+                        )
+
+            return len(new_commits), new_commits
+
+        except Exception as e:
+            logger.error(f"Failed to get git changes: {e}")
+            return 0, []
+
+    def get_time_elapsed(self, paused_at: str) -> str:
+        """Calculate human-readable time elapsed since pause.
+
+        Args:
+            paused_at: ISO-8601 timestamp when session was paused
+
+        Returns:
+            Human-readable time string (e.g., "2 hours ago", "3 days ago")
+        """
+        try:
+            pause_time = datetime.fromisoformat(paused_at)
+            now = datetime.now(timezone.utc)
+
+            # Ensure pause_time is timezone-aware
+            if pause_time.tzinfo is None:
+                pause_time = pause_time.replace(tzinfo=timezone.utc)
+
+            delta = now - pause_time
+
+            # Calculate time components
+            days = delta.days
+            hours = delta.seconds // 3600
+            minutes = (delta.seconds % 3600) // 60
+
+            # Format human-readable string
+            if days > 0:
+                if days == 1:
+                    return "1 day ago"
+                return f"{days} days ago"
+            if hours > 0:
+                if hours == 1:
+                    return "1 hour ago"
+                return f"{hours} hours ago"
+            if minutes > 0:
+                if minutes == 1:
+                    return "1 minute ago"
+                return f"{minutes} minutes ago"
+            return "just now"
+
+        except Exception as e:
+            logger.error(f"Failed to calculate time elapsed: {e}")
+            return "unknown time ago"
+
+    def format_resume_prompt(self, session_data: Dict[str, Any]) -> str:
+        """Format a user-friendly resume prompt.
+
+        Args:
+            session_data: Session data dictionary
+
+        Returns:
+            Formatted prompt string for display
+        """
+        try:
+            # Extract session information
+            paused_at = session_data.get("paused_at", "")
+            conversation = session_data.get("conversation", {})
+            git_context = session_data.get("git_context", {})
+
+            summary = conversation.get("summary", "No summary available")
+            accomplishments = conversation.get("accomplishments", [])
+            next_steps = conversation.get("next_steps", [])
+
+            # Calculate time elapsed
+            time_ago = self.get_time_elapsed(paused_at)
+
+            # Get git changes
+            recent_commits = git_context.get("recent_commits", [])
+            new_commit_count, new_commits = self.get_git_changes_since_pause(
+                paused_at, recent_commits
+            )
+
+            # Build prompt
+            lines = []
+            lines.append("\n" + "=" * 80)
+            lines.append("📋 PAUSED SESSION FOUND")
+            lines.append("=" * 80)
+            lines.append(f"\nPaused: {time_ago}")
+            lines.append(f"\nLast working on: {summary}")
+
+            if accomplishments:
+                lines.append("\nCompleted:")
+                for item in accomplishments[:5]:  # Limit to first 5
+                    lines.append(f"  ✓ {item}")
+                if len(accomplishments) > 5:
+                    lines.append(f"  ... and {len(accomplishments) - 5} more")
+
+            if next_steps:
+                lines.append("\nNext steps:")
+                for item in next_steps[:5]:  # Limit to first 5
+                    lines.append(f"  • {item}")
+                if len(next_steps) > 5:
+                    lines.append(f"  ... and {len(next_steps) - 5} more")
+
+            # Git changes information
+            if new_commit_count > 0:
+                lines.append(f"\nGit changes since pause: {new_commit_count} commits")
+                if new_commits:
+                    lines.append("\nRecent commits:")
+                    for commit in new_commits[:3]:  # Show first 3
+                        lines.append(
+                            f"  {commit['sha']} - {commit['message']} ({commit['author']})"
+                        )
+                    if len(new_commits) > 3:
+                        lines.append(f"  ... and {len(new_commits) - 3} more")
+            else:
+                lines.append("\nNo git changes since pause")
+
+            lines.append("\n" + "=" * 80)
+            lines.append(
+                "Use this context to resume work, or start fresh if not relevant."
+            )
+            lines.append("=" * 80 + "\n")
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            logger.error(f"Failed to format resume prompt: {e}")
+            return "\n📋 Paused session found, but failed to format details.\n"
+
+    def check_and_display_resume_prompt(self) -> Optional[Dict[str, Any]]:
+        """Check for paused sessions and display resume prompt if found.
+
+        This is the main entry point for PM startup integration.
+
+        Returns:
+            Session data if found and user should resume, None otherwise
+        """
+        if not self.has_paused_sessions():
+            logger.debug("No paused sessions found")
+            return None
+
+        # Get most recent session
+        session_data = self.get_most_recent_session()
+        if not session_data:
+            logger.debug("Failed to load paused session data")
+            return None
+
+        # Display resume prompt
+        prompt_text = self.format_resume_prompt(session_data)
+        print(prompt_text)
+
+        # Return session data for PM to use
+        return session_data
+
+    def clear_session(self, session_data: Dict[str, Any]) -> bool:
+        """Clear a paused session after successful resume.
+
+        Args:
+            session_data: Session data dictionary with 'file_path' key
+
+        Returns:
+            True if successfully cleared, False otherwise
+        """
+        try:
+            file_path = session_data.get("file_path")
+            if not file_path or not isinstance(file_path, Path):
+                logger.error("Invalid session file path")
+                return False
+
+            if file_path.exists():
+                file_path.unlink()
+                logger.info(f"Cleared paused session: {file_path}")
+
+                # Also remove SHA256 checksum file if exists
+                sha_file = file_path.parent / f".{file_path.name}.sha256"
+                if sha_file.exists():
+                    sha_file.unlink()
+                    logger.debug(f"Cleared session checksum: {sha_file}")
+
+                return True
+            logger.warning(f"Session file not found: {file_path}")
+            return False
+
+        except Exception as e:
+            logger.error(f"Failed to clear session: {e}")
+            return False
+
+    def get_session_count(self) -> int:
+        """Get count of paused sessions.
+
+        Returns:
+            Number of paused sessions
+        """
+        if not self.pause_dir.exists():
+            return 0
+
+        session_files = list(self.pause_dir.glob("session-*.json"))
+        return len(session_files)
+
+    def list_all_sessions(self) -> List[Dict[str, Any]]:
+        """List all paused sessions sorted by most recent.
+
+        Returns:
+            List of session data dictionaries
+        """
+        if not self.pause_dir.exists():
+            return []
+
+        session_files = list(self.pause_dir.glob("session-*.json"))
+        if not session_files:
+            return []
+
+        # Sort by modification time (most recent first)
+        session_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+
+        sessions = []
+        for session_file in session_files:
+            try:
+                with session_file.open("r") as f:
+                    session_data = json.load(f)
+                session_data["file_path"] = session_file
+                sessions.append(session_data)
+            except Exception as e:
+                logger.error(f"Failed to load session {session_file}: {e}")
+                continue
+
+        return sessions

claude_mpm/services/core/models/health.py

@@ -16,36 +16,9 @@ ARCHITECTURE:
 
 from dataclasses import asdict, dataclass, field
 from datetime import datetime
-from enum import Enum
 from typing import Any, Dict, List
 
-
-class HealthStatus(Enum):
-    """
-    Health status levels.
-
-    WHY: Provides granular health states to distinguish between different
-    levels of service degradation.
-
-    States:
-        HEALTHY: All checks passing, process operating normally
-        DEGRADED: Process running but with issues (high resource usage, slow responses)
-        UNHEALTHY: Critical failure (process dead, crashed, or unresponsive)
-        UNKNOWN: Cannot determine health status
-    """
-
-    HEALTHY = "healthy"
-    DEGRADED = "degraded"
-    UNHEALTHY = "unhealthy"
-    UNKNOWN = "unknown"
-
-    def is_operational(self) -> bool:
-        """Check if status indicates operational service."""
-        return self in (HealthStatus.HEALTHY, HealthStatus.DEGRADED)
-
-    def is_critical(self) -> bool:
-        """Check if status indicates critical failure."""
-        return self == HealthStatus.UNHEALTHY
+from ....core.enums import HealthStatus
 
 
 @dataclass

claude_mpm/services/core/path_resolver.py

@@ -281,7 +281,7 @@ class PathResolver(IPathResolver):
 
         if agents_dir and agents_dir.exists():
             discovered_agents_dir = agents_dir
-            self.logger.info(f"Using custom agents directory: {discovered_agents_dir}")
+            self.logger.debug(f"Using custom agents directory: {discovered_agents_dir}")
         elif framework_path and framework_path != Path("__PACKAGED__"):
             # Prioritize templates directory over main agents directory
             templates_dir = (

claude_mpm/services/infrastructure/monitoring/__init__.py

@@ -3,12 +3,12 @@
 Exports main monitoring components for backward compatibility.
 """
 
+from ....core.enums import HealthStatus
 from .aggregator import MonitoringAggregatorService
 from .base import (
     HealthChecker,
     HealthCheckResult,
     HealthMetric,
-    HealthStatus,
 )
 
 # Legacy exports for backward compatibility

claude_mpm/services/infrastructure/monitoring/aggregator.py

@@ -9,12 +9,12 @@ import time
 from collections import deque
 from typing import Any, Callable, Dict, List, Optional
 
+from ....core.enums import HealthStatus
 from .base import (
     BaseMonitoringService,
     HealthChecker,
     HealthCheckResult,
     HealthMetric,
-    HealthStatus,
 )
 
 
@@ -212,14 +212,14 @@ class MonitoringAggregatorService(BaseMonitoringService):
 
         total_metrics = len(metrics)
 
-        # Critical if any critical metrics
-        if status_counts[HealthStatus.CRITICAL] > 0:
-            return HealthStatus.CRITICAL
+        # Unhealthy if any unhealthy metrics
+        if status_counts[HealthStatus.UNHEALTHY] > 0:
+            return HealthStatus.UNHEALTHY
 
-        # Warning if >30% warning metrics
-        warning_ratio = status_counts[HealthStatus.WARNING] / total_metrics
-        if warning_ratio > 0.3:
-            return HealthStatus.WARNING
+        # Degraded if >30% degraded metrics
+        degraded_ratio = status_counts[HealthStatus.DEGRADED] / total_metrics
+        if degraded_ratio > 0.3:
+            return HealthStatus.DEGRADED
 
         # Unknown if >50% unknown metrics
         unknown_ratio = status_counts[HealthStatus.UNKNOWN] / total_metrics
@@ -375,10 +375,10 @@ class MonitoringAggregatorService(BaseMonitoringService):
         checks_count = len(recent_results)
 
         # Determine aggregated status
-        if status_counts[HealthStatus.CRITICAL] > 0:
-            aggregated_status = HealthStatus.CRITICAL
-        elif status_counts[HealthStatus.WARNING] > checks_count * 0.3:
-            aggregated_status = HealthStatus.WARNING
+        if status_counts[HealthStatus.UNHEALTHY] > 0:
+            aggregated_status = HealthStatus.UNHEALTHY
+        elif status_counts[HealthStatus.DEGRADED] > checks_count * 0.3:
+            aggregated_status = HealthStatus.DEGRADED
         elif status_counts[HealthStatus.UNKNOWN] > checks_count * 0.5:
             aggregated_status = HealthStatus.UNKNOWN
         else:

claude_mpm/services/infrastructure/monitoring/base.py

@@ -7,17 +7,9 @@ import time
 from abc import ABC, abstractmethod
 from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
-from enum import Enum
 from typing import Any, Dict, List, Optional, Union
 
-
-class HealthStatus(Enum):
-    """Health status levels for monitoring."""
-
-    HEALTHY = "healthy"
-    WARNING = "warning"
-    CRITICAL = "critical"
-    UNKNOWN = "unknown"
+from ....core.enums import HealthStatus
 
 
 @dataclass
@@ -75,11 +67,11 @@ class HealthCheckResult:
             "healthy_metrics": len(
                 [m for m in self.metrics if m.status == HealthStatus.HEALTHY]
             ),
-            "warning_metrics": len(
-                [m for m in self.metrics if m.status == HealthStatus.WARNING]
+            "degraded_metrics": len(
+                [m for m in self.metrics if m.status == HealthStatus.DEGRADED]
             ),
-            "critical_metrics": len(
-                [m for m in self.metrics if m.status == HealthStatus.CRITICAL]
+            "unhealthy_metrics": len(
+                [m for m in self.metrics if m.status == HealthStatus.UNHEALTHY]
             ),
         }
 

claude_mpm/services/infrastructure/monitoring/network.py

@@ -6,7 +6,8 @@ Monitors network connectivity, port availability, and socket health.
 import socket
 from typing import Dict, List, Optional
 
-from .base import BaseMonitoringService, HealthMetric, HealthStatus
+from ....core.enums import HealthStatus
+from .base import BaseMonitoringService, HealthMetric
 
 
 class NetworkHealthService(BaseMonitoringService):
@@ -98,7 +99,7 @@ class NetworkHealthService(BaseMonitoringService):
                 HealthMetric(
                     name="socket_creation",
                     value=False,
-                    status=HealthStatus.CRITICAL,
+                    status=HealthStatus.UNHEALTHY,
                     message=f"Failed to create socket: {e}",
                 )
             )
@@ -142,11 +143,11 @@ class NetworkHealthService(BaseMonitoringService):
                     )
                 )
             else:
-                # Determine if this is critical or warning based on endpoint type
+                # Determine if this is unhealthy or degraded based on endpoint type
                 status = (
-                    HealthStatus.WARNING
+                    HealthStatus.DEGRADED
                     if "optional" in name.lower()
-                    else HealthStatus.CRITICAL
+                    else HealthStatus.UNHEALTHY
                 )
                 metrics.append(
                     HealthMetric(
@@ -161,7 +162,7 @@ class NetworkHealthService(BaseMonitoringService):
                 HealthMetric(
                     name=metric_name,
                     value=False,
-                    status=HealthStatus.WARNING,
+                    status=HealthStatus.DEGRADED,
                     message=f"Connection to {host}:{port} timed out after {timeout}s",
                 )
             )