claude-mpm 5.0.9__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/services/infrastructure/context_usage_tracker.py

@@ -0,0 +1,291 @@
+"""Context Usage Tracker Service.
+
+WHY: Track cumulative token usage across Claude Code hook invocations to prevent
+context window exhaustion and enable intelligent auto-pause behavior.
+
+DESIGN DECISIONS:
+- File-based persistence (hooks run in separate processes)
+- Atomic file operations using StateStorage
+- Threshold detection at 70% (caution), 85% (warning), 90% (auto_pause), 95% (critical)
+- Session-scoped tracking with reset capability
+- Compatible with 200k context budget for Claude Sonnet 4.5
+
+USAGE:
+    tracker = ContextUsageTracker()
+    state = tracker.update_usage(input_tokens=15000, output_tokens=2000)
+    if tracker.should_auto_pause():
+        # Trigger auto-pause workflow
+        pass
+"""
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logger import get_logger
+from claude_mpm.storage.state_storage import StateStorage
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ContextUsageState:
+    """State tracking for cumulative context/token usage.
+
+    Attributes:
+        session_id: Unique session identifier
+        cumulative_input_tokens: Total input tokens across all hook invocations
+        cumulative_output_tokens: Total output tokens across all hook invocations
+        cache_creation_tokens: Total tokens spent creating prompt cache
+        cache_read_tokens: Total tokens read from prompt cache
+        percentage_used: Percentage of 200k context budget used (0.0-100.0)
+        threshold_reached: Highest threshold crossed ('caution', 'warning', 'auto_pause', 'critical')
+        auto_pause_active: Whether auto-pause has been triggered
+        last_updated: ISO timestamp of last update
+    """
+
+    session_id: str
+    cumulative_input_tokens: int = 0
+    cumulative_output_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    percentage_used: float = 0.0
+    threshold_reached: Optional[str] = None
+    auto_pause_active: bool = False
+    last_updated: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+
+class ContextUsageTracker:
+    """Track cumulative context/token usage across hook invocations.
+
+    Features:
+    - Cumulative tracking across multiple API calls
+    - File-based persistence for cross-process state sharing
+    - Atomic file operations for concurrent safety
+    - Threshold detection (70%, 85%, 90%, 95%)
+    - Auto-pause triggering at 90%+ usage
+    - Session management with reset capability
+    """
+
+    # Claude Sonnet 4.5 context window
+    CONTEXT_BUDGET = 200000
+
+    # Threshold levels for warnings and auto-pause
+    THRESHOLDS = {
+        "caution": 0.70,  # Yellow warning
+        "warning": 0.85,  # Orange warning
+        "auto_pause": 0.90,  # Trigger auto-pause
+        "critical": 0.95,  # Red critical alert
+    }
+
+    def __init__(self, project_path: Optional[Path] = None):
+        """Initialize context usage tracker.
+
+        Args:
+            project_path: Project root path (default: current directory)
+        """
+        self.project_path = (project_path or Path.cwd()).resolve()
+        self.state_dir = self.project_path / ".claude-mpm" / "state"
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        self.state_file = self.state_dir / "context-usage.json"
+
+        # Use StateStorage for atomic operations
+        self.storage = StateStorage(self.state_dir)
+
+        logger.debug(f"ContextUsageTracker initialized: {self.state_file}")
+
+    def update_usage(
+        self,
+        input_tokens: int,
+        output_tokens: int,
+        cache_creation: int = 0,
+        cache_read: int = 0,
+    ) -> ContextUsageState:
+        """Update cumulative usage from API response.
+
+        Args:
+            input_tokens: Input tokens from this API call
+            output_tokens: Output tokens from this API call
+            cache_creation: Cache creation tokens (optional)
+            cache_read: Cache read tokens (optional)
+
+        Returns:
+            Updated context usage state
+
+        Raises:
+            ValueError: If token counts are negative
+        """
+        if any(
+            t < 0 for t in [input_tokens, output_tokens, cache_creation, cache_read]
+        ):
+            raise ValueError("Token counts cannot be negative")
+
+        # Load current state
+        state = self._load_state()
+
+        # Update cumulative counters
+        state.cumulative_input_tokens += input_tokens
+        state.cumulative_output_tokens += output_tokens
+        state.cache_creation_tokens += cache_creation
+        state.cache_read_tokens += cache_read
+
+        # Calculate total effective tokens (input + output, cache read is "free")
+        total_tokens = state.cumulative_input_tokens + state.cumulative_output_tokens
+        state.percentage_used = (total_tokens / self.CONTEXT_BUDGET) * 100
+
+        # Check thresholds
+        state.threshold_reached = self.check_thresholds(state)
+
+        # Activate auto-pause if threshold reached
+        if state.threshold_reached in {"auto_pause", "critical"}:
+            state.auto_pause_active = True
+
+        # Update timestamp
+        state.last_updated = datetime.now(timezone.utc).isoformat()
+
+        # Persist state atomically
+        self._save_state(state)
+
+        logger.debug(
+            f"Usage updated: {total_tokens}/{self.CONTEXT_BUDGET} tokens "
+            f"({state.percentage_used:.1f}%), threshold: {state.threshold_reached}"
+        )
+
+        return state
+
+    def check_thresholds(
+        self, state: Optional[ContextUsageState] = None
+    ) -> Optional[str]:
+        """Check which threshold (if any) has been exceeded.
+
+        Args:
+            state: Optional state to check (uses current state if None)
+
+        Returns:
+            Highest threshold exceeded ('caution', 'warning', 'auto_pause', 'critical')
+            or None if no thresholds exceeded
+        """
+        if state is None:
+            state = self.get_current_state()
+
+        percentage = state.percentage_used / 100  # Convert to 0.0-1.0
+
+        # Check thresholds in descending order (highest first)
+        for threshold_name in ["critical", "auto_pause", "warning", "caution"]:
+            if percentage >= self.THRESHOLDS[threshold_name]:
+                return threshold_name
+
+        return None
+
+    def should_auto_pause(self) -> bool:
+        """Check if auto-pause should be triggered.
+
+        Returns:
+            True if 90%+ context budget used
+        """
+        state = self.get_current_state()
+        return state.percentage_used >= (self.THRESHOLDS["auto_pause"] * 100)
+
+    def get_current_state(self) -> ContextUsageState:
+        """Get current usage state without modifying.
+
+        Returns:
+            Current context usage state
+        """
+        return self._load_state()
+
+    def reset_session(self, new_session_id: str) -> None:
+        """Reset tracking for a new session.
+
+        Args:
+            new_session_id: New session identifier
+        """
+        state = ContextUsageState(session_id=new_session_id)
+        self._save_state(state)
+        logger.info(f"Context usage reset for new session: {new_session_id}")
+
+    def _load_state(self) -> ContextUsageState:
+        """Load state from persistence file.
+
+        Returns:
+            Loaded state or default state if file doesn't exist/is corrupted
+        """
+        try:
+            if not self.state_file.exists():
+                # Generate initial session ID
+                session_id = (
+                    f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
+                )
+                logger.debug("No state file found, creating default state")
+                return ContextUsageState(session_id=session_id)
+
+            # Load JSON state
+            data = self.storage.read_json(self.state_file)
+
+            if data is None:
+                logger.warning("Failed to read state file, using default state")
+                session_id = (
+                    f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
+                )
+                return ContextUsageState(session_id=session_id)
+
+            # Reconstruct ContextUsageState from dict
+            return ContextUsageState(**data)
+
+        except Exception as e:
+            logger.error(f"Error loading state, using default: {e}")
+            session_id = (
+                f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
+            )
+            return ContextUsageState(session_id=session_id)
+
+    def _save_state(self, state: ContextUsageState) -> None:
+        """Save state to persistence file atomically.
+
+        Args:
+            state: Context usage state to persist
+
+        Raises:
+            RuntimeError: If atomic write fails
+        """
+        try:
+            # Convert dataclass to dict
+            state_dict = asdict(state)
+
+            # Atomic write using StateStorage
+            if not self.storage.write_json(state_dict, self.state_file, atomic=True):
+                raise RuntimeError(f"Failed to write state to {self.state_file}")
+
+            logger.debug(f"State saved: {self.state_file}")
+
+        except Exception as e:
+            logger.error(f"Error saving state: {e}")
+            raise RuntimeError(f"Failed to persist context usage state: {e}") from e
+
+    def get_usage_summary(self) -> dict:
+        """Get human-readable usage summary.
+
+        Returns:
+            Dictionary with usage statistics
+        """
+        state = self.get_current_state()
+        total_tokens = state.cumulative_input_tokens + state.cumulative_output_tokens
+
+        return {
+            "session_id": state.session_id,
+            "total_tokens": total_tokens,
+            "budget": self.CONTEXT_BUDGET,
+            "percentage_used": round(state.percentage_used, 2),
+            "threshold_reached": state.threshold_reached,
+            "auto_pause_active": state.auto_pause_active,
+            "breakdown": {
+                "input_tokens": state.cumulative_input_tokens,
+                "output_tokens": state.cumulative_output_tokens,
+                "cache_creation_tokens": state.cache_creation_tokens,
+                "cache_read_tokens": state.cache_read_tokens,
+            },
+            "last_updated": state.last_updated,
+        }

claude_mpm/services/infrastructure/resume_log_generator.py

@@ -6,7 +6,8 @@ Integrates with session management and response tracking infrastructure.
 Triggers:
 - model_context_window_exceeded (stop_reason)
 - Manual pause command
-- 95% token threshold reached
+- 95% token threshold reached (critical)
+- 90% token threshold reached (auto-pause)
 - Session end with high token usage (>85%)
 
 Design Principles:
@@ -71,6 +72,7 @@ class ResumeLogGenerator:
         thresholds = self.config.get("context_management", {}).get("thresholds", {})
         self.threshold_caution = thresholds.get("caution", 0.70)
         self.threshold_warning = thresholds.get("warning", 0.85)
+        self.threshold_auto_pause = thresholds.get("auto_pause", 0.90)
         self.threshold_critical = thresholds.get("critical", 0.95)
 
         logger.info(
@@ -96,14 +98,14 @@ class ResumeLogGenerator:
         if not self.enabled or not self.auto_generate:
             return manual_trigger  # Only generate on manual trigger if auto is disabled
 
-        # Trigger conditions
+        # Trigger conditions (ordered by severity)
         triggers = [
             stop_reason == "max_tokens",
             stop_reason == "model_context_window_exceeded",
             manual_trigger,
-            token_usage_pct and token_usage_pct >= self.threshold_critical,
-            token_usage_pct
-            and token_usage_pct >= self.threshold_warning,  # Generate at 85% too
+            token_usage_pct and token_usage_pct >= self.threshold_critical,  # 95%
+            token_usage_pct and token_usage_pct >= self.threshold_auto_pause,  # 90%
+            token_usage_pct and token_usage_pct >= self.threshold_warning,  # 85%
         ]
 
         should_gen = any(triggers)
@@ -121,6 +123,22 @@ class ResumeLogGenerator:
 
         return should_gen
 
+    def should_auto_pause(self, token_usage_pct: Optional[float]) -> bool:
+        """Check if auto-pause threshold (90%) has been reached.
+
+        This is a convenience method to check specifically for the 90% threshold
+        which triggers automatic session pausing.
+
+        Args:
+            token_usage_pct: Current token usage percentage (0.0-1.0)
+
+        Returns:
+            True if auto-pause threshold has been reached
+        """
+        if token_usage_pct is None:
+            return False
+        return token_usage_pct >= self.threshold_auto_pause
+
     def generate_from_session_state(
         self,
         session_id: str,
@@ -427,6 +445,7 @@ class ResumeLogGenerator:
                 "thresholds": {
                     "caution": f"{self.threshold_caution:.0%}",
                     "warning": f"{self.threshold_warning:.0%}",
+                    "auto_pause": f"{self.threshold_auto_pause:.0%}",
                     "critical": f"{self.threshold_critical:.0%}",
                 },
             }

claude_mpm/services/monitor/daemon.py

@@ -44,6 +44,7 @@ class UnifiedMonitorDaemon:
         daemon_mode: bool = False,
         pid_file: Optional[str] = None,
         log_file: Optional[str] = None,
+        enable_hot_reload: bool = False,
     ):
         """Initialize the unified monitor daemon.
 
@@ -53,10 +54,12 @@ class UnifiedMonitorDaemon:
             daemon_mode: Whether to run as background daemon
             pid_file: Path to PID file for daemon mode
             log_file: Path to log file for daemon mode
+            enable_hot_reload: Enable file watching and hot reload for development
         """
         self.host = host
         self.port = port
         self.daemon_mode = daemon_mode
+        self.enable_hot_reload = enable_hot_reload
         self.logger = get_logger(__name__)
 
         # Use new consolidated DaemonManager for all daemon operations
@@ -75,7 +78,9 @@ class UnifiedMonitorDaemon:
         )
 
         # Core server
-        self.server = UnifiedMonitorServer(host=host, port=port)
+        self.server = UnifiedMonitorServer(
+            host=host, port=port, enable_hot_reload=enable_hot_reload
+        )
 
         # Health monitoring
         self.health_monitor = HealthMonitor(port=port)
@@ -510,7 +515,9 @@ class UnifiedMonitorDaemon:
 
         # Recreate the server and health monitor after stop() sets them to None
         self.logger.info(f"Recreating server components for {self.host}:{self.port}")
-        self.server = UnifiedMonitorServer(host=self.host, port=self.port)
+        self.server = UnifiedMonitorServer(
+            host=self.host, port=self.port, enable_hot_reload=self.enable_hot_reload
+        )
         self.health_monitor = HealthMonitor(port=self.port)
 
         # Reset the shutdown event for the new run

claude_mpm/services/monitor/daemon_manager.py

@@ -34,6 +34,11 @@ from typing import Optional, Tuple
 from ...core.enums import OperationResult
 from ...core.logging_config import get_logger
 
+# Exit code constants for signal handling
+EXIT_NORMAL = 0
+EXIT_SIGKILL = 137  # 128 + SIGKILL(9) - forced termination
+EXIT_SIGTERM = 143  # 128 + SIGTERM(15) - graceful shutdown
+
 
 class DaemonManager:
     """Centralized manager for all daemon lifecycle operations.
@@ -90,10 +95,10 @@ class DaemonManager:
     def _get_default_log_file(self) -> Path:
         """Get default log file path with port number to support multiple daemons."""
         project_root = Path.cwd()
-        claude_mpm_dir = project_root / ".claude-mpm"
-        claude_mpm_dir.mkdir(exist_ok=True)
+        logs_dir = project_root / ".claude-mpm" / "logs"
+        logs_dir.mkdir(parents=True, exist_ok=True)
         # Include port in filename to support multiple daemon instances
-        return claude_mpm_dir / f"monitor-daemon-{self.port}.log"
+        return logs_dir / f"monitor-daemon-{self.port}.log"
 
     def cleanup_port_conflicts(self, max_retries: int = 3) -> bool:
         """Clean up any processes using the daemon port.
@@ -556,7 +561,7 @@ class DaemonManager:
             # Use subprocess for clean daemon startup (v4.2.40)
             # This avoids fork() issues with Python threading
             if self.use_subprocess_daemon():
-                return self.start_daemon_subprocess()
+                return self.start_daemon_subprocess(force_restart=force_restart)
             # Fallback to traditional fork (kept for compatibility)
             return self.daemonize()
 
@@ -574,12 +579,15 @@ class DaemonManager:
         # Otherwise, use subprocess for monitor daemon to avoid threading issues
         return True
 
-    def start_daemon_subprocess(self) -> bool:
+    def start_daemon_subprocess(self, force_restart: bool = False) -> bool:
         """Start daemon using subprocess.Popen for clean process isolation.
 
         This avoids all the fork() + threading issues by starting the monitor
         in a completely fresh process with no inherited threads or locks.
 
+        Args:
+            force_restart: Whether this is a force restart (helps interpret exit codes)
+
         Returns:
             True if daemon started successfully
         """
@@ -641,18 +649,56 @@ class DaemonManager:
 
                 # Wait for the subprocess to write its PID file and bind to port
                 # The subprocess will write the PID file after it starts successfully
-                max_wait = 10  # seconds
+                # Allow configuration via environment variable (default 30s to account for agent/skill sync)
+                max_wait = int(os.environ.get("CLAUDE_MPM_MONITOR_TIMEOUT", "30"))
                 start_time = time.time()
                 pid_file_found = False
                 port_bound = False
+                last_progress_log = 0.0
 
                 self.logger.debug(f"Waiting up to {max_wait}s for daemon to start...")
 
                 while time.time() - start_time < max_wait:
+                    # Log progress every 5 seconds to show we're waiting
+                    elapsed = time.time() - start_time
+                    if elapsed - last_progress_log >= 5.0:
+                        self.logger.info(
+                            f"Waiting for monitor daemon... ({int(elapsed)}s elapsed, syncing agents/skills)"
+                        )
+                        last_progress_log = elapsed
+
                     # Check if process is still running
                     returncode = process.poll()
                     if returncode is not None:
-                        # Process exited - this is the bug we're fixing!
+                        # Process exited - interpret exit code with context
+                        # Exit codes 137 (SIGKILL) and 143 (SIGTERM) are common during daemon replacement
+                        if returncode == EXIT_SIGKILL:
+                            # SIGKILL - process was forcefully terminated
+                            if force_restart:
+                                # This is expected during force restart - old daemon was killed
+                                self.logger.info(
+                                    f"Previous monitor instance replaced (exit {EXIT_SIGKILL}: SIGKILL during force restart)"
+                                )
+                            else:
+                                # Unexpected SIGKILL - something else killed our new daemon
+                                self.logger.warning(
+                                    f"Monitor subprocess terminated unexpectedly (exit {EXIT_SIGKILL}: SIGKILL). "
+                                    f"Check {self.log_file} for details."
+                                )
+                            return False
+                        if returncode == EXIT_SIGTERM:
+                            # SIGTERM - graceful shutdown requested
+                            self.logger.info(
+                                f"Monitor subprocess cleanly terminated (exit {EXIT_SIGTERM}: SIGTERM, graceful shutdown)"
+                            )
+                            return False
+                        if returncode == EXIT_NORMAL:
+                            # Normal exit
+                            self.logger.info(
+                                f"Monitor subprocess exited normally (exit code {EXIT_NORMAL})"
+                            )
+                            return False
+                        # Unexpected exit code - this IS an error
                         self.logger.error(
                             f"Monitor daemon subprocess exited prematurely with code {returncode}"
                         )
@@ -940,6 +986,7 @@ class DaemonManager:
                 os.dup2(null_in.fileno(), sys.stdin.fileno())
 
             # Redirect stdout and stderr to log file
+            # Ensure logs directory exists
             self.log_file.parent.mkdir(parents=True, exist_ok=True)
             with self.log_file.open("a") as log_out:
                 os.dup2(log_out.fileno(), sys.stdout.fileno())

claude_mpm/services/monitor/management/lifecycle.py

@@ -128,12 +128,16 @@ class DaemonLifecycle:
             # Redirect stdout and stderr
             if self.log_file:
                 # Redirect to log file
+                # Ensure logs directory exists
+                self.log_file.parent.mkdir(parents=True, exist_ok=True)
                 with self.log_file.open("a") as log_out:
                     os.dup2(log_out.fileno(), sys.stdout.fileno())
                     os.dup2(log_out.fileno(), sys.stderr.fileno())
             else:
                 # Default to a daemon log file instead of /dev/null for errors
-                default_log = Path.home() / ".claude-mpm" / "monitor-daemon.log"
+                default_log = (
+                    Path.home() / ".claude-mpm" / "logs" / "monitor-daemon.log"
+                )
                 default_log.parent.mkdir(parents=True, exist_ok=True)
                 with default_log.open("a") as log_out:
                     os.dup2(log_out.fileno(), sys.stdout.fileno())
@@ -475,14 +479,22 @@ class DaemonLifecycle:
         try:
             # If no log file specified, create a default one
             if not self.log_file:
-                default_log = Path.home() / ".claude-mpm" / "monitor-daemon.log"
+                default_log = (
+                    Path.home() / ".claude-mpm" / "logs" / "monitor-daemon.log"
+                )
                 default_log.parent.mkdir(parents=True, exist_ok=True)
                 self.log_file = default_log
 
             # Configure logger to write to file immediately
             import logging
 
-            file_handler = logging.FileHandler(self.log_file)
+            # Use RotatingFileHandler for automatic log rotation
+            # 5MB max size, 5 backup files (consistent with project logging standards)
+            file_handler = logging.handlers.RotatingFileHandler(
+                self.log_file,
+                maxBytes=5 * 1024 * 1024,  # 5MB
+                backupCount=5,
+            )
             file_handler.setLevel(logging.DEBUG)
             formatter = logging.Formatter(
                 "%(asctime)s - %(name)s - %(levelname)s - %(message)s"