claude-mpm 4.15.6__py3-none-any.whl → 4.21.3__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/core/base.py

@@ -9,6 +9,7 @@ and lifecycle management.
 Part of TSK-0046: Service Layer Architecture Reorganization
 """
 
+import threading
 from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional
 
@@ -221,29 +222,43 @@ class SingletonService(SyncBaseService):
     """
     Base class for singleton services.
 
-    Ensures only one instance of the service exists.
+    Ensures only one instance of the service exists with thread-safe initialization.
+    Uses double-checked locking pattern to prevent race conditions.
     """
 
     _instances: Dict[type, "SingletonService"] = {}
+    _lock = threading.Lock()
 
     def __new__(cls, *args, **kwargs):
-        """Ensure only one instance exists."""
+        """Ensure only one instance exists with thread-safe initialization."""
+        # Fast path - check without lock
         if cls not in cls._instances:
-            cls._instances[cls] = super().__new__(cls)
+            # Slow path - acquire lock and double-check
+            with cls._lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = super().__new__(cls)
         return cls._instances[cls]
 
     @classmethod
     def get_instance(cls) -> "SingletonService":
-        """Get the singleton instance."""
+        """Get the singleton instance with thread-safe initialization."""
+        # Fast path - check without lock
         if cls not in cls._instances:
-            cls._instances[cls] = cls()
+            # Slow path - acquire lock and double-check
+            with cls._lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = cls()
         return cls._instances[cls]
 
     @classmethod
     def clear_instance(cls) -> None:
-        """Clear the singleton instance (useful for testing)."""
-        if cls in cls._instances:
-            instance = cls._instances[cls]
-            if hasattr(instance, "shutdown") and not instance.is_shutdown:
-                instance.shutdown()
-            del cls._instances[cls]
+        """Clear the singleton instance (useful for testing).
+
+        Thread-safe implementation ensures proper cleanup.
+        """
+        with cls._lock:
+            if cls in cls._instances:
+                instance = cls._instances[cls]
+                if hasattr(instance, "shutdown") and not instance.is_shutdown:
+                    instance.shutdown()
+                del cls._instances[cls]

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/agent_config.py

@@ -19,6 +19,9 @@ 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.

claude_mpm/services/core/models/process.py

@@ -25,6 +25,9 @@ from typing import Any, Dict, List, Optional
 
 from claude_mpm.core.enums import ServiceState
 
+# Backward compatibility alias (consolidated in Phase 3A Batch 24)
+ProcessStatus = ServiceState
+
 
 @dataclass
 class DeploymentState:
@@ -230,6 +233,7 @@ __all__ = [
     "PROTECTED_PORT_RANGES",
     "DeploymentState",
     "ProcessInfo",
+    "ProcessStatus",  # Backward compatibility alias for ServiceState
     "StartConfig",
     "is_port_protected",
 ]

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/diagnostics/models.py

@@ -6,11 +6,32 @@ consistency across all checks and reporting.
 """
 
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Any, Dict, List, Optional, Union
 
 from ...core.enums import OperationResult, ValidationSeverity
 
 
+class DiagnosticStatus(str, Enum):
+    """Backward compatibility wrapper for diagnostic status values.
+
+    WHY: Provides backward compatibility for tests and code that use
+    DiagnosticStatus instead of the consolidated OperationResult/ValidationSeverity.
+
+    DESIGN DECISION: Maps to the appropriate consolidated enum values:
+    - OK → OperationResult.SUCCESS
+    - WARNING → ValidationSeverity.WARNING
+    - ERROR → ValidationSeverity.ERROR
+
+    Note: This is a compatibility layer. New code should use OperationResult
+    and ValidationSeverity directly.
+    """
+
+    OK = "success"  # Maps to OperationResult.SUCCESS
+    WARNING = "warning"  # Maps to ValidationSeverity.WARNING
+    ERROR = "error"  # Maps to ValidationSeverity.ERROR
+
+
 @dataclass
 class DiagnosticResult:
     """Result from a diagnostic check.

claude_mpm/services/event_bus/relay.py

@@ -9,6 +9,7 @@ WHY separate relay component:
 """
 
 import os
+import threading
 import time
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
@@ -271,11 +272,15 @@ class SocketIORelay:
 
 # Global relay instance
 _relay_instance: Optional[SocketIORelay] = None
+_relay_lock = threading.Lock()
 
 
 def get_relay(port: Optional[int] = None) -> SocketIORelay:
     """Get or create the global SocketIO relay instance.
 
+    Thread-safe implementation using double-checked locking pattern to
+    prevent race conditions during concurrent initialization.
+
     Args:
         port: Optional port number
 
@@ -283,9 +288,16 @@ def get_relay(port: Optional[int] = None) -> SocketIORelay:
         SocketIORelay: The relay instance
     """
     global _relay_instance
-    if _relay_instance is None:
-        _relay_instance = SocketIORelay(port)
-    return _relay_instance
+
+    # Fast path - check without lock
+    if _relay_instance is not None:
+        return _relay_instance
+
+    # Slow path - acquire lock and double-check
+    with _relay_lock:
+        if _relay_instance is None:
+            _relay_instance = SocketIORelay(port)
+        return _relay_instance
 
 
 def start_relay(port: Optional[int] = None) -> SocketIORelay:
@@ -303,8 +315,12 @@ def start_relay(port: Optional[int] = None) -> SocketIORelay:
 
 
 def stop_relay() -> None:
-    """Stop the global SocketIO relay."""
+    """Stop the global SocketIO relay.
+
+    Thread-safe implementation ensures proper cleanup.
+    """
     global _relay_instance
-    if _relay_instance:
-        _relay_instance.stop()
-        _relay_instance = None
+    with _relay_lock:
+        if _relay_instance:
+            _relay_instance.stop()
+            _relay_instance = None