claude-mpm 4.14.6__py3-none-any.whl → 4.21.0__py3-none-any.whl

claude_mpm/services/cli/session_resume_helper.py

@@ -0,0 +1,372 @@
+"""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/)
+- Backward compatibility with legacy .claude-mpm/sessions/pause/ location
+- 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()
+        # Primary location: flattened structure
+        self.pause_dir = self.project_path / ".claude-mpm" / "sessions"
+        # Legacy location for backward compatibility
+        self.legacy_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
+        """
+        # Check both primary and legacy locations
+        session_files = []
+
+        if self.pause_dir.exists():
+            session_files.extend(list(self.pause_dir.glob("session-*.json")))
+
+        if self.legacy_pause_dir.exists():
+            session_files.extend(list(self.legacy_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
+        """
+        # Find all session files from both locations
+        session_files = []
+
+        if self.pause_dir.exists():
+            session_files.extend(list(self.pause_dir.glob("session-*.json")))
+
+        if self.legacy_pause_dir.exists():
+            session_files.extend(list(self.legacy_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
+        """
+        session_files = []
+
+        if self.pause_dir.exists():
+            session_files.extend(list(self.pause_dir.glob("session-*.json")))
+
+        if self.legacy_pause_dir.exists():
+            session_files.extend(list(self.legacy_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
+        """
+        session_files = []
+
+        if self.pause_dir.exists():
+            session_files.extend(list(self.pause_dir.glob("session-*.json")))
+
+        if self.legacy_pause_dir.exists():
+            session_files.extend(list(self.legacy_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/command_handler_service.py

@@ -12,6 +12,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 from typing import Any, Dict, List
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.services.core.interfaces import CommandHandlerInterface
 
 
@@ -169,7 +170,7 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             if command == "test":
                 success = self._handle_test_command(args)
                 return {
-                    "success": success,
+                    OperationResult.SUCCESS.value: success,
                     "command": command,
                     "args": args,
                     "message": (
@@ -179,7 +180,7 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             if command == "agents":
                 success = self._handle_agents_command(args)
                 return {
-                    "success": success,
+                    OperationResult.SUCCESS.value: success,
                     "command": command,
                     "args": args,
                     "message": (
@@ -189,14 +190,19 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
                     ),
                 }
             return {
-                "success": False,
+                OperationResult.SUCCESS.value: False,
                 "command": command,
                 "args": args,
-                "error": f"Unknown command: {command}",
+                OperationResult.ERROR.value: f"Unknown command: {command}",
                 "available_commands": self.get_available_commands(),
             }
         except Exception as e:
-            return {"success": False, "command": command, "args": args, "error": str(e)}
+            return {
+                OperationResult.SUCCESS.value: False,
+                "command": command,
+                "args": args,
+                OperationResult.ERROR.value: str(e),
+            }
 
     def get_command_help(self, command: str) -> str:
         """Get help text for a specific command.

claude_mpm/services/core/interfaces/process.py

@@ -32,10 +32,10 @@ USAGE:
 from abc import ABC, abstractmethod
 from typing import Dict, List, Optional
 
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.models.process import (
     DeploymentState,
     ProcessInfo,
-    ProcessStatus,
     StartConfig,
 )
 
@@ -102,12 +102,12 @@ class IDeploymentStateManager(ABC):
         """
 
     @abstractmethod
-    def get_deployments_by_status(self, status: ProcessStatus) -> List[DeploymentState]:
+    def get_deployments_by_status(self, status: ServiceState) -> List[DeploymentState]:
         """
         Get all deployments with a specific status.
 
         Args:
-            status: ProcessStatus to filter by
+            status: ServiceState to filter by
 
         Returns:
             List of matching DeploymentState objects
@@ -168,14 +168,14 @@ class IDeploymentStateManager(ABC):
 
     @abstractmethod
     def update_deployment_status(
-        self, deployment_id: str, status: ProcessStatus
+        self, deployment_id: str, status: ServiceState
     ) -> bool:
         """
         Update the status of a deployment.
 
         Args:
             deployment_id: Unique deployment identifier
-            status: New ProcessStatus
+            status: New ServiceState
 
         Returns:
             True if updated, False if deployment not found
@@ -290,7 +290,7 @@ class ILocalProcessManager(ABC):
 
     @abstractmethod
     def list_processes(
-        self, status_filter: Optional[ProcessStatus] = None
+        self, status_filter: Optional[ServiceState] = None
     ) -> List[ProcessInfo]:
         """
         List all managed processes.

claude_mpm/services/core/interfaces.py

@@ -20,7 +20,62 @@ focused modules for better maintainability and testing.
 """
 
 # Re-export everything from the new modular structure for backward compatibility
-from .interfaces import *
+from .interfaces import (  # noqa: F401
+    AgentCapabilitiesInterface,
+    AgentDeploymentInterface,
+    AgentMetadata,
+    CacheEntry,
+    CommandHandlerInterface,
+    HealthStatus,
+    HookServiceInterface,
+    IAgentRecommender,
+    IAgentRegistry,
+    IAutoConfigManager,
+    ICacheService,
+    IConfigurationManager,
+    IConfigurationService,
+    ICrashDetector,
+    IDeploymentStateManager,
+    IErrorHandler,
+    IEventBus,
+    IHealthCheck,
+    IHealthCheckManager,
+    IHealthMonitor,
+    ILocalProcessManager,
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IModelProvider,
+    IModelRouter,
+    InterfaceRegistry,
+    IPerformanceMonitor,
+    IPromptCache,
+    IResourceMonitor,
+    IRestartManager,
+    IRestartPolicy,
+    IServiceContainer,
+    IServiceFactory,
+    IServiceLifecycle,
+    IStructuredLogger,
+    ITemplateManager,
+    IToolchainAnalyzer,
+    MemoryHookInterface,
+    MemoryServiceInterface,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+    ProjectAnalyzerInterface,
+    RunnerConfigurationInterface,
+    ServiceType,
+    SessionManagementInterface,
+    SocketIOServiceInterface,
+    SubprocessLauncherInterface,
+    SystemInstructionsInterface,
+    T,
+    TemplateRenderContext,
+    TicketManagerInterface,
+    UtilityServiceInterface,
+    VersionServiceInterface,
+)
 
 # All interface definitions have been moved to the interfaces/ package
 # This file now serves as a compatibility layer that delegates to the modular structure

claude_mpm/services/core/models/__init__.py

@@ -24,7 +24,6 @@ from .process import (
     PROTECTED_PORT_RANGES,
     DeploymentState,
     ProcessInfo,
-    ProcessStatus,
     StartConfig,
     is_port_protected,
 )
@@ -63,7 +62,6 @@ __all__ = [  # noqa: RUF022 - Grouped by category with comments for clarity
     "ValidationResult",
     "ConfigurationPreview",
     # Process management models
-    "ProcessStatus",
     "DeploymentState",
     "ProcessInfo",
     "StartConfig",

claude_mpm/services/core/models/agent_config.py

@@ -17,6 +17,11 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Dict, List, Optional
 
+from ....core.enums import OperationResult, ValidationSeverity
+
+# Backward compatibility alias (consolidated in Phase 3A Batch 25)
+ConfigurationStatus = OperationResult
+
 
 class AgentSpecialization(str, Enum):
     """Agent specialization categories.
@@ -154,20 +159,6 @@ class AgentRecommendation:
         }
 
 
-class ConfigurationStatus(str, Enum):
-    """Status of configuration operation.
-
-    WHY: Configuration can succeed, fail, or partially succeed. This enum
-    provides a standardized way to communicate operation outcomes.
-    """
-
-    SUCCESS = "success"
-    PARTIAL_SUCCESS = "partial_success"
-    FAILURE = "failure"
-    VALIDATION_ERROR = "validation_error"
-    USER_CANCELLED = "user_cancelled"
-
-
 @dataclass
 class ConfigurationResult:
     """Result of automated configuration operation.
@@ -179,9 +170,17 @@ class ConfigurationResult:
     DESIGN DECISION: Separates successful and failed deployments to enable
     proper error handling. Includes validation results and user-facing
     messages for transparency.
+
+    NOTE: Uses core OperationResult enum (consolidated from ConfigurationStatus
+    in Phase 3A Batch 25). Mappings:
+    - SUCCESS → OperationResult.SUCCESS
+    - PARTIAL_SUCCESS → OperationResult.WARNING (partial success with issues)
+    - FAILURE → OperationResult.FAILED
+    - VALIDATION_ERROR → OperationResult.ERROR
+    - USER_CANCELLED → OperationResult.CANCELLED
     """
 
-    status: ConfigurationStatus
+    status: OperationResult
     deployed_agents: List[str] = field(default_factory=list)
     failed_agents: List[str] = field(default_factory=list)
     validation_warnings: List[str] = field(default_factory=list)
@@ -193,7 +192,7 @@ class ConfigurationResult:
     @property
     def is_successful(self) -> bool:
         """Check if configuration was completely successful."""
-        return self.status == ConfigurationStatus.SUCCESS
+        return self.status == OperationResult.SUCCESS
 
     @property
     def has_failures(self) -> bool:
@@ -223,18 +222,6 @@ class ConfigurationResult:
         }
 
 
-class ValidationSeverity(str, Enum):
-    """Severity level for validation issues.
-
-    WHY: Not all validation issues are equally critical. This enum enables
-    categorization of issues by severity to support appropriate handling.
-    """
-
-    ERROR = "error"  # Blocks deployment
-    WARNING = "warning"  # Should be reviewed but doesn't block
-    INFO = "info"  # Informational only
-
-
 @dataclass
 class ValidationIssue:
     """Represents a validation issue.

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