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

claude_mpm/services/session_management_service.py

@@ -0,0 +1,314 @@
+from pathlib import Path
+
+"""Session management service for orchestrating Claude sessions.
+
+This service handles:
+1. Interactive session orchestration
+2. Oneshot session orchestration
+3. Session lifecycle management
+4. Session logging and cleanup
+
+Extracted from ClaudeRunner to follow Single Responsibility Principle.
+
+DEPENDENCY INJECTION:
+This service uses protocol-based dependency injection to avoid circular imports.
+It accepts a ClaudeRunnerProtocol instead of importing ClaudeRunner directly.
+"""
+
+import time
+import uuid
+from datetime import timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult, ServiceState
+from claude_mpm.services.core.interfaces import SessionManagementInterface
+
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
+
+class SessionManagementService(BaseService, SessionManagementInterface):
+    """Service for managing Claude session orchestration."""
+
+    def __init__(self, runner: Optional["ClaudeRunnerProtocol"] = None):
+        """Initialize the session management service.
+
+        Args:
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
+                    for delegation
+        """
+        super().__init__(name="session_management_service")
+        self.runner: Optional[ClaudeRunnerProtocol] = runner
+        self.active_sessions = {}  # Track active sessions
+
+    async def _initialize(self) -> None:
+        """Initialize the service. No special initialization needed."""
+
+    async def _cleanup(self) -> None:
+        """Cleanup service resources. No cleanup needed."""
+
+    def run_interactive_session(self, initial_context: Optional[str] = None) -> bool:
+        """Run Claude in interactive mode using session delegation.
+
+        WHY: This method delegates to InteractiveSession class for better
+        maintainability and reduced complexity. The session class handles all
+        the details while this method provides the orchestration interface.
+
+        Args:
+            initial_context: Optional initial context to pass to Claude
+
+        Returns:
+            bool: True if session completed successfully, False otherwise
+        """
+        try:
+            from claude_mpm.core.interactive_session import InteractiveSession
+
+            # Create session handler
+            session = InteractiveSession(self.runner)
+
+            # Step 1: Initialize session
+            success, error = session.initialize_interactive_session()
+            if not success:
+                self.logger.error(f"Failed to initialize interactive session: {error}")
+                return False
+
+            # Step 2: Set up environment
+            success, environment = session.setup_interactive_environment()
+            if not success:
+                self.logger.error("Failed to setup interactive environment")
+                return False
+
+            # Step 3: Handle interactive input/output
+            # This is where the actual Claude process runs
+            session.handle_interactive_input(environment)
+
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Interactive session failed: {e}")
+            return False
+        finally:
+            # Step 4: Clean up session
+            if "session" in locals():
+                session.cleanup_interactive_session()
+
+    def run_oneshot_session(self, prompt: str, context: Optional[str] = None) -> bool:
+        """Run Claude with a single prompt using session delegation.
+
+        WHY: This method delegates to OneshotSession class for better
+        maintainability and reduced complexity. The session class handles
+        all the details while this method provides the orchestration interface.
+
+        Args:
+            prompt: The command or prompt to execute
+            context: Optional context to prepend to the prompt
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            from claude_mpm.core.oneshot_session import OneshotSession
+
+            # Create session handler
+            session = OneshotSession(self.runner)
+
+            # Step 1: Initialize session
+            success, error = session.initialize_session(prompt)
+            if not success:
+                return False
+
+            # Special case: MPM commands return early
+            if (
+                error is None
+                and self.runner.command_handler_service
+                and self.runner.command_handler_service.is_mpm_command(prompt)
+            ):
+                return success
+
+            # Step 2: Deploy agents
+            if not session.deploy_agents():
+                self.logger.warning("Agent deployment had issues, continuing...")
+
+            # Step 3: Set up infrastructure
+            infrastructure = session.setup_infrastructure()
+
+            # Step 4: Execute command
+            success, response = session.execute_command(prompt, context, infrastructure)
+
+            return success
+
+        except Exception as e:
+            self.logger.error(f"Oneshot session failed: {e}")
+            return False
+        finally:
+            # Step 5: Clean up session
+            if "session" in locals():
+                session.cleanup_session()
+
+    def create_session_log_file(self) -> Optional[Path]:
+        """Create a session log file for the current session.
+
+        Returns:
+            Path to the created log file, or None if creation failed
+        """
+        try:
+            import uuid
+            from datetime import datetime
+
+            from claude_mpm.config.paths import paths
+
+            # Create session logs directory if it doesn't exist
+            session_logs_dir = paths.project_root / ".claude-mpm" / "logs" / "sessions"
+            session_logs_dir.mkdir(parents=True, exist_ok=True)
+
+            # Generate unique session log filename
+            timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+            session_id = str(uuid.uuid4())[:8]
+            log_filename = f"session_{timestamp}_{session_id}.jsonl"
+            log_file = session_logs_dir / log_filename
+
+            # Create empty log file
+            log_file.touch()
+
+            self.logger.debug(f"Created session log file: {log_file}")
+            return log_file
+
+        except Exception as e:
+            self.logger.warning(f"Failed to create session log file: {e}")
+            return None
+
+    def log_session_event(self, log_file: Path, event_data: dict):
+        """Log an event to the session log file.
+
+        Args:
+            log_file: Path to the session log file
+            event_data: Event data to log
+        """
+        if not log_file or not log_file.exists():
+            return
+
+        try:
+            import json
+            from datetime import datetime
+
+            # Add timestamp to event data
+            event_data["timestamp"] = datetime.now(timezone.utc).isoformat()
+
+            # Append to log file as JSONL
+            with log_file.open("a") as f:
+                f.write(json.dumps(event_data) + "\n")
+
+        except Exception as e:
+            self.logger.warning(f"Failed to log session event: {e}")
+
+    def get_service_status(self) -> dict:
+        """Get current session management service status.
+
+        Returns:
+            dict: Session management service status information
+        """
+        return {
+            "service_available": True,
+            "runner_available": self.runner is not None,
+            "interactive_session_available": True,
+            "oneshot_session_available": True,
+            "active_sessions": len(self.active_sessions),
+        }
+
+    # Implementation of abstract methods from SessionManagementInterface
+
+    def start_session(self, session_config: Dict[str, Any]) -> str:
+        """Start a new session.
+
+        Args:
+            session_config: Configuration for the session
+
+        Returns:
+            Session ID
+        """
+        session_id = str(uuid.uuid4())
+        session_info = {
+            "id": session_id,
+            "config": session_config,
+            "start_time": time.time(),
+            "status": ServiceState.RUNNING,
+            "type": session_config.get("type", "interactive"),
+        }
+
+        self.active_sessions[session_id] = session_info
+        self.logger.info(f"Started session {session_id}")
+
+        return session_id
+
+    def end_session(self, session_id: str) -> bool:
+        """End an active session.
+
+        Args:
+            session_id: ID of session to end
+
+        Returns:
+            True if session ended successfully
+        """
+        if session_id in self.active_sessions:
+            session_info = self.active_sessions[session_id]
+            session_info["status"] = "ended"
+            session_info["end_time"] = time.time()
+
+            # Remove from active sessions
+            del self.active_sessions[session_id]
+
+            self.logger.info(f"Ended session {session_id}")
+            return True
+        self.logger.warning(f"Session {session_id} not found")
+        return False
+
+    def get_session_status(self, session_id: str) -> Dict[str, Any]:
+        """Get status of a session.
+
+        Args:
+            session_id: ID of session
+
+        Returns:
+            Dictionary with session status information
+        """
+        if session_id in self.active_sessions:
+            return self.active_sessions[session_id].copy()
+        return {
+            "id": session_id,
+            "status": OperationResult.ERROR,
+            "error": "Session not found",
+        }
+
+    def list_active_sessions(self) -> List[str]:
+        """List all active session IDs.
+
+        Returns:
+            List of active session IDs
+        """
+        return list(self.active_sessions.keys())
+
+    async def cleanup_sessions(self) -> int:
+        """Clean up inactive or expired sessions.
+
+        Returns:
+            Number of sessions cleaned up
+        """
+        current_time = time.time()
+        expired_sessions = []
+
+        # Find sessions older than 24 hours
+        for session_id, session_info in self.active_sessions.items():
+            if current_time - session_info["start_time"] > 86400:  # 24 hours
+                expired_sessions.append(session_id)
+
+        # Clean up expired sessions
+        for session_id in expired_sessions:
+            self.end_session(session_id)
+
+        self.logger.info(f"Cleaned up {len(expired_sessions)} expired sessions")
+        return len(expired_sessions)

claude_mpm/services/session_manager.py

@@ -0,0 +1,380 @@
+"""
+Session Manager Service
+
+Centralized session ID management with thread-safe singleton pattern.
+Ensures a single session ID is generated and used across all components.
+
+This service addresses race conditions and duplicate session ID generation
+by providing a single source of truth for session identifiers.
+
+Extended with:
+- Token usage tracking and monitoring
+- Resume log generation on session end
+- Context metrics persistence
+- Automatic resume log injection on session startup
+"""
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import Lock
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class SessionManager:
+    """
+    Thread-safe singleton session manager.
+
+    Provides centralized session ID generation and management to prevent
+    duplicate session IDs across different components.
+
+    Uses double-checked locking pattern for thread-safe singleton initialization.
+    """
+
+    _instance: Optional["SessionManager"] = None
+    _lock = Lock()
+    _initialized = False
+
+    def __new__(cls) -> "SessionManager":
+        """
+        Create or return the singleton instance using double-checked locking.
+
+        Returns:
+            The singleton SessionManager instance
+        """
+        # First check without lock (fast path)
+        if cls._instance is None:
+            # Acquire lock for thread safety
+            with cls._lock:
+                # Double-check inside lock
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        """
+        Initialize the session manager (only once).
+
+        This method uses an initialization flag to ensure it only
+        runs once, even if __init__ is called multiple times.
+        """
+        # Use class-level lock to ensure thread-safe initialization
+        with self.__class__._lock:
+            if self.__class__._initialized:
+                return
+
+            # Generate session ID once during initialization
+            self._session_id = self._generate_session_id()
+            self._session_start_time = datetime.now(timezone.utc)
+
+            # Token usage tracking
+            self._cumulative_tokens = 0
+            self._total_budget = 200000  # Default Claude Code budget
+            self._last_stop_reason: Optional[str] = None
+
+            # Context metrics storage
+            self._context_metrics: Dict[str, Any] = {
+                "total_budget": self._total_budget,
+                "used_tokens": 0,
+                "remaining_tokens": self._total_budget,
+                "percentage_used": 0.0,
+                "stop_reason": None,
+                "model": "claude-sonnet-4.5",
+            }
+
+            # Resume log reference (loaded on startup if exists)
+            self._resume_log_content: Optional[str] = None
+
+            # Mark as initialized
+            self.__class__._initialized = True
+
+            logger.debug(
+                f"SessionManager initialized with session ID: {self._session_id}"
+            )
+
+            # Check for resume log from previous session
+            self._load_resume_log()
+
+    def _generate_session_id(self) -> str:
+        """
+        Generate or retrieve a session ID.
+
+        Checks environment variables first, then generates a timestamp-based ID.
+
+        Returns:
+            A unique session identifier
+        """
+        # Check environment variables in order of preference
+        env_vars = ["CLAUDE_SESSION_ID", "ANTHROPIC_SESSION_ID", "SESSION_ID"]
+
+        for env_var in env_vars:
+            session_id = os.environ.get(env_var)
+            if session_id:
+                logger.debug(f"Using session ID from {env_var}: {session_id}")
+                return session_id
+
+        # Generate timestamp-based session ID
+        session_id = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+        logger.debug(f"Generated new session ID: {session_id}")
+        return session_id
+
+    def get_session_id(self) -> str:
+        """
+        Get the current session ID.
+
+        Thread-safe method to retrieve the session ID.
+
+        Returns:
+            The current session ID
+        """
+        return self._session_id
+
+    def get_session_start_time(self) -> datetime:
+        """
+        Get the session start time.
+
+        Returns:
+            The datetime when the session was initialized
+        """
+        return self._session_start_time
+
+    def set_session_id(self, session_id: str) -> None:
+        """
+        Override the session ID.
+
+        This should only be used in special circumstances, as it can
+        break the single session ID guarantee.
+
+        Args:
+            session_id: The new session ID to use
+        """
+        with self.__class__._lock:
+            old_id = self._session_id
+            if old_id != session_id:
+                self._session_id = session_id
+                logger.warning(f"Session ID changed from {old_id} to {session_id}")
+            else:
+                logger.debug(
+                    f"Session ID already set to {session_id}, no change needed"
+                )
+
+    def update_token_usage(
+        self,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        stop_reason: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Update cumulative token usage for the session.
+
+        Args:
+            input_tokens: Input tokens from latest API call
+            output_tokens: Output tokens from latest API call
+            stop_reason: Stop reason from Claude API
+
+        Returns:
+            Updated context metrics
+        """
+        with self.__class__._lock:
+            # Update cumulative usage
+            tokens_used = input_tokens + output_tokens
+            self._cumulative_tokens += tokens_used
+
+            # Update stop reason if provided
+            if stop_reason:
+                self._last_stop_reason = stop_reason
+
+            # Calculate metrics
+            remaining = max(0, self._total_budget - self._cumulative_tokens)
+            percentage = (self._cumulative_tokens / self._total_budget) * 100
+
+            # Update context metrics
+            self._context_metrics = {
+                "total_budget": self._total_budget,
+                "used_tokens": self._cumulative_tokens,
+                "remaining_tokens": remaining,
+                "percentage_used": percentage,
+                "stop_reason": self._last_stop_reason,
+                "model": "claude-sonnet-4.5",
+            }
+
+            logger.debug(
+                f"Token usage updated: {self._cumulative_tokens}/{self._total_budget} "
+                f"({percentage:.1f}%) - Stop reason: {stop_reason}"
+            )
+
+            return self._context_metrics.copy()
+
+    def get_context_metrics(self) -> Dict[str, Any]:
+        """
+        Get current context metrics.
+
+        Returns:
+            Dictionary containing token usage and context metrics
+        """
+        with self.__class__._lock:
+            return self._context_metrics.copy()
+
+    def get_token_usage_percentage(self) -> float:
+        """
+        Get current token usage as a percentage (0.0 to 1.0).
+
+        Returns:
+            Token usage percentage
+        """
+        with self.__class__._lock:
+            return self._context_metrics["percentage_used"] / 100.0
+
+    def should_warn_context_limit(self, threshold: float = 0.70) -> bool:
+        """
+        Check if context usage has reached warning threshold.
+
+        Args:
+            threshold: Warning threshold (0.0 to 1.0)
+
+        Returns:
+            True if threshold reached
+        """
+        return self.get_token_usage_percentage() >= threshold
+
+    def _load_resume_log(self) -> None:
+        """
+        Load resume log from previous session if it exists.
+
+        This is called during initialization to check for session continuity.
+        """
+        try:
+            # Lazy import to avoid circular dependencies
+            from claude_mpm.services.infrastructure.resume_log_generator import (
+                ResumeLogGenerator,
+            )
+
+            generator = ResumeLogGenerator()
+
+            # Check if there's a resume log for this session
+            # (Could be from a previous interrupted session with same ID)
+            resume_content = generator.load_resume_log(self._session_id)
+
+            if resume_content:
+                self._resume_log_content = resume_content
+                logger.info(f"Loaded resume log for session {self._session_id}")
+            else:
+                logger.debug("No resume log found for current session")
+
+        except Exception as e:
+            logger.warning(f"Failed to load resume log: {e}")
+            # Non-critical error, continue without resume log
+
+    def get_resume_log_content(self) -> Optional[str]:
+        """
+        Get resume log content if loaded.
+
+        Returns:
+            Resume log markdown content or None
+        """
+        with self.__class__._lock:
+            return self._resume_log_content
+
+    def generate_resume_log(
+        self,
+        session_state: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Path]:
+        """
+        Generate and save resume log for current session.
+
+        Args:
+            session_state: Optional session state data to include
+
+        Returns:
+            Path to saved resume log or None if generation failed
+        """
+        try:
+            # Lazy import to avoid circular dependencies
+            from claude_mpm.models.resume_log import ContextMetrics, ResumeLog
+            from claude_mpm.services.infrastructure.resume_log_generator import (
+                ResumeLogGenerator,
+            )
+
+            generator = ResumeLogGenerator()
+
+            # Create context metrics from current state
+            context_metrics = ContextMetrics(
+                total_budget=self._total_budget,
+                used_tokens=self._cumulative_tokens,
+                remaining_tokens=self._context_metrics["remaining_tokens"],
+                percentage_used=self._context_metrics["percentage_used"],
+                stop_reason=self._last_stop_reason,
+                model=self._context_metrics["model"],
+                session_id=self._session_id,
+            )
+
+            if session_state:
+                # Generate from provided session state
+                resume_log = generator.generate_from_session_state(
+                    session_id=self._session_id,
+                    session_state=session_state,
+                    stop_reason=self._last_stop_reason,
+                )
+            else:
+                # Create minimal resume log
+                resume_log = ResumeLog(
+                    session_id=self._session_id,
+                    context_metrics=context_metrics,
+                    mission_summary="Session ended - resume log auto-generated.",
+                )
+
+            if resume_log:
+                file_path = generator.save_resume_log(resume_log)
+                logger.info(f"Resume log generated and saved: {file_path}")
+                return file_path
+            logger.warning("Resume log generation returned None")
+            return None
+
+        except Exception as e:
+            logger.error(f"Failed to generate resume log: {e}", exc_info=True)
+            return None
+
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Reset the singleton instance (mainly for testing).
+
+        This method should not be used in production code.
+        """
+        with cls._lock:
+            cls._instance = None
+            cls._initialized = False
+            logger.debug("SessionManager singleton reset")
+
+
+# Global accessor function
+_manager: Optional[SessionManager] = None
+
+
+def get_session_manager() -> SessionManager:
+    """
+    Get the global SessionManager instance.
+
+    Thread-safe accessor that ensures a single SessionManager exists.
+
+    Returns:
+        The singleton SessionManager instance
+    """
+    global _manager
+    if _manager is None:
+        _manager = SessionManager()
+    return _manager
+
+
+def get_session_id() -> str:
+    """
+    Convenience function to get the current session ID.
+
+    Returns:
+        The current session ID
+    """
+    return get_session_manager().get_session_id()