claude-mpm 5.4.85__py3-none-any.whl → 5.6.76__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/mcp_config_manager.py

@@ -10,7 +10,7 @@ MCP service installations.
 """
 
 import json
-import subprocess
+import subprocess  # nosec B404 - Required for MCP service management
 import sys
 from enum import Enum
 from pathlib import Path
@@ -150,6 +150,86 @@ class MCPConfigManager:
 
         return is_enabled
 
+    def get_registry_service_config(
+        self, service_name: str, env_overrides: Optional[Dict[str, str]] = None
+    ) -> Optional[Dict]:
+        """
+        Get configuration for a service from the MCP Service Registry.
+
+        Args:
+            service_name: Name of the service
+            env_overrides: Optional environment variable overrides
+
+        Returns:
+            Service configuration dict or None if service not in registry
+        """
+        try:
+            from .mcp_service_registry import MCPServiceRegistry
+
+            service = MCPServiceRegistry.get(service_name)
+            if not service:
+                return None
+
+            return MCPServiceRegistry.generate_config(service, env_overrides)
+        except ImportError:
+            self.logger.debug("MCP Service Registry not available")
+            return None
+
+    def filter_services_by_mcp_flag(
+        self, mcp_flag: Optional[str], all_services: Dict[str, Dict]
+    ) -> Dict[str, Dict]:
+        """
+        Filter MCP services based on the --mcp command line flag.
+
+        Args:
+            mcp_flag: Comma-separated list of service names, or None for all
+            all_services: Dict of all available service configurations
+
+        Returns:
+            Filtered dict of service configurations
+        """
+        if not mcp_flag:
+            return all_services
+
+        # Parse comma-separated service names
+        requested_services = {s.strip() for s in mcp_flag.split(",") if s.strip()}
+
+        # Filter services
+        filtered = {}
+        for name, config in all_services.items():
+            if name in requested_services:
+                filtered[name] = config
+            else:
+                self.logger.debug(f"MCP service '{name}' excluded by --mcp flag")
+
+        # Warn about requested services that don't exist
+        available = set(all_services.keys())
+        missing = requested_services - available
+        if missing:
+            self.logger.warning(
+                f"Requested MCP services not available: {', '.join(missing)}"
+            )
+
+        return filtered
+
+    def list_available_services(self) -> list[str]:
+        """
+        List all available MCP services from registry and static configs.
+
+        Returns:
+            List of service names
+        """
+        services = set(self.STATIC_MCP_CONFIGS.keys())
+
+        try:
+            from .mcp_service_registry import MCPServiceRegistry
+
+            services.update(MCPServiceRegistry.list_names())
+        except ImportError:
+            pass
+
+        return sorted(services)
+
     def detect_service_path(self, service_name: str) -> Optional[str]:
         """
         Detect the best path for an MCP service.
@@ -185,7 +265,7 @@ class MCPConfigManager:
             # Choose the best candidate (prefer v1.1.0+ with MCP support)
             for path in candidates:
                 try:
-                    result = subprocess.run(
+                    result = subprocess.run(  # nosec B603 B607 - Controlled service help check
                         [path, "--help"],
                         capture_output=True,
                         text=True,
@@ -258,7 +338,7 @@ class MCPConfigManager:
     def _check_system_path(self, service_name: str) -> Optional[str]:
         """Check if service is available in system PATH."""
         try:
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607 - Controlled which command
                 ["which", service_name],
                 capture_output=True,
                 text=True,
@@ -356,7 +436,7 @@ class MCPConfigManager:
                 cmd.append("--help")
 
             # Run test command with timeout
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 - Controlled service test command
                 cmd,
                 capture_output=True,
                 text=True,
@@ -560,7 +640,7 @@ class MCPConfigManager:
         # Try pipx run test
         if shutil.which("pipx"):
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Controlled pipx run command
                     ["pipx", "run", service_name, "--version"],
                     capture_output=True,
                     text=True,
@@ -576,7 +656,7 @@ class MCPConfigManager:
         # Try uvx if pipx run not available
         if not use_pipx_run and shutil.which("uvx"):
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Controlled uvx command
                     ["uvx", service_name, "--version"],
                     capture_output=True,
                     text=True,
@@ -876,7 +956,7 @@ class MCPConfigManager:
                             command_path = service_config.get("command", "")
                             results[service_name] = Path(command_path).exists()
                         return results
-                except Exception:
+                except Exception:  # nosec B110 - Graceful fallback to empty dict
                     pass
             return {}
 
@@ -946,7 +1026,7 @@ class MCPConfigManager:
         if shutil.which("pipx"):
             try:
                 self.logger.debug(f"Attempting to install {service_name} via pipx...")
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Controlled pipx install
                     ["pipx", "install", service_name],
                     capture_output=True,
                     text=True,
@@ -980,7 +1060,7 @@ class MCPConfigManager:
         if shutil.which("uvx"):
             try:
                 self.logger.debug(f"Attempting to install {service_name} via uvx...")
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Controlled uvx install
                     ["uvx", "install", service_name],
                     capture_output=True,
                     text=True,
@@ -997,7 +1077,7 @@ class MCPConfigManager:
         # Method 3: Try pip install --user
         try:
             self.logger.debug(f"Attempting to install {service_name} via pip --user...")
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607 - Controlled pip install
                 [sys.executable, "-m", "pip", "install", "--user", service_name],
                 capture_output=True,
                 text=True,
@@ -1093,7 +1173,7 @@ class MCPConfigManager:
                 self.logger.debug(
                     f"    Testing {service_name} from installed pipx venv: {pipx_venv_bin}"
                 )
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 - Controlled service help check
                     [str(pipx_venv_bin), "--help"],
                     capture_output=True,
                     text=True,
@@ -1145,7 +1225,7 @@ class MCPConfigManager:
             self.logger.debug(
                 f"    Testing {service_name} via pipx run (not installed in venv)"
             )
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607 - Controlled pipx run command
                 ["pipx", "run", service_name, "--help"],
                 capture_output=True,
                 text=True,
@@ -1216,7 +1296,7 @@ class MCPConfigManager:
             self.logger.debug(f"Uninstalling {service_name}...")
 
             # First uninstall the corrupted version
-            uninstall_result = subprocess.run(
+            uninstall_result = subprocess.run(  # nosec B603 B607 - Controlled pipx uninstall
                 ["pipx", "uninstall", service_name],
                 capture_output=True,
                 text=True,
@@ -1229,7 +1309,7 @@ class MCPConfigManager:
 
             # Now reinstall
             self.logger.debug(f"Installing fresh {service_name}...")
-            install_result = subprocess.run(
+            install_result = subprocess.run(  # nosec B603 B607 - Controlled pipx install
                 ["pipx", "install", service_name],
                 capture_output=True,
                 text=True,
@@ -1294,7 +1374,7 @@ class MCPConfigManager:
         for dep in missing_deps:
             try:
                 self.logger.debug(f"    Injecting {dep} into {service_name}...")
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Controlled pipx inject
                     ["pipx", "inject", service_name, dep],
                     capture_output=True,
                     text=True,
@@ -1348,7 +1428,7 @@ class MCPConfigManager:
                 return False
 
             self.logger.info(f"  → Uninstalling {service_name}...")
-            uninstall_result = subprocess.run(
+            uninstall_result = subprocess.run(  # nosec B603 B607 - Controlled pipx uninstall
                 ["pipx", "uninstall", service_name],
                 capture_output=True,
                 text=True,
@@ -1363,7 +1443,7 @@ class MCPConfigManager:
                 )
 
             self.logger.info(f"  → Installing fresh {service_name}...")
-            install_result = subprocess.run(
+            install_result = subprocess.run(  # nosec B603 B607 - Controlled pipx install
                 ["pipx", "install", service_name],
                 capture_output=True,
                 text=True,
@@ -1439,7 +1519,7 @@ class MCPConfigManager:
             # Try pipx run as fallback for pipx installations
             if method == "pipx":
                 try:
-                    result = subprocess.run(
+                    result = subprocess.run(  # nosec B603 B607 - Controlled pipx command
                         ["pipx", "run", service_name, "--version"],
                         capture_output=True,
                         text=True,
@@ -1462,7 +1542,7 @@ class MCPConfigManager:
             ]
 
             for cmd in test_commands:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 - Controlled service verification
                     cmd,
                     capture_output=True,
                     text=True,