claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/services/event_log.py

@@ -0,0 +1,325 @@
+"""Event Log Service for persistent event storage.
+
+WHY this is needed:
+- Decouple event producers from consumers
+- Persist events for later processing (e.g., autotodos CLI)
+- Enable event-driven architecture patterns
+- Provide audit trail of system events
+
+DESIGN DECISION: Simple JSON file storage because:
+- Human-readable and inspectable
+- No additional database dependencies
+- Fast for small event volumes
+- Easy to clear and manage
+- Follows existing pattern (hook_error_memory)
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+from ..core.logger import get_logger
+
+# Event status types
+EventStatus = Literal["pending", "resolved", "archived"]
+
+# Max message length to prevent file bloat
+MAX_MESSAGE_LENGTH = 2000
+
+
+class EventLog:
+    """Persistent event log with simple JSON storage.
+
+    WHY this design:
+    - Store events with timestamp, type, payload, status
+    - Support filtering by status and event type
+    - Prevent file bloat with message truncation
+    - Enable mark-as-resolved workflow
+    - Keep it simple - no complex queries needed
+    """
+
+    def __init__(self, log_file: Optional[Path] = None):
+        """Initialize event log.
+
+        Args:
+            log_file: Path to event log file (default: .claude-mpm/event_log.json)
+        """
+        self.logger = get_logger("event_log")
+
+        # Use default location if not specified
+        if log_file is None:
+            log_file = Path.cwd() / ".claude-mpm" / "event_log.json"
+
+        self.log_file = log_file
+        self.events: List[Dict[str, Any]] = self._load_events()
+
+    def _load_events(self) -> List[Dict[str, Any]]:
+        """Load events from disk.
+
+        Returns:
+            List of event records
+        """
+        if not self.log_file.exists():
+            return []
+
+        try:
+            content = self.log_file.read_text()
+            if not content.strip():
+                return []
+            data = json.loads(content)
+
+            # Validate structure
+            if not isinstance(data, list):
+                self.logger.warning("Event log is not a list, resetting")
+                return []
+
+            return data
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Failed to parse event log: {e}, resetting")
+            return []
+        except Exception as e:
+            self.logger.error(f"Error loading event log: {e}")
+            return []
+
+    def _save_events(self):
+        """Persist events to disk."""
+        try:
+            # Ensure directory exists
+            self.log_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write with pretty formatting for human readability
+            self.log_file.write_text(json.dumps(self.events, indent=2))
+        except Exception as e:
+            self.logger.error(f"Failed to save event log: {e}")
+
+    def _truncate_message(self, message: str) -> str:
+        """Truncate message to prevent file bloat.
+
+        Args:
+            message: Message to truncate
+
+        Returns:
+            Truncated message with ellipsis if needed
+        """
+        if len(message) <= MAX_MESSAGE_LENGTH:
+            return message
+
+        return message[:MAX_MESSAGE_LENGTH] + "... (truncated)"
+
+    def append_event(
+        self,
+        event_type: str,
+        payload: Dict[str, Any],
+        status: EventStatus = "pending",
+    ) -> str:
+        """Append a new event to the log.
+
+        Args:
+            event_type: Type of event (e.g., "autotodo.error", "hook.error")
+            payload: Event data (will be truncated if too large)
+            status: Event status (default: "pending")
+
+        Returns:
+            Event ID (timestamp-based for simplicity)
+        """
+        # Truncate any message fields in payload
+        truncated_payload = payload.copy()
+        if "message" in truncated_payload:
+            truncated_payload["message"] = self._truncate_message(
+                str(truncated_payload["message"])
+            )
+        if "full_message" in truncated_payload:
+            truncated_payload["full_message"] = self._truncate_message(
+                str(truncated_payload["full_message"])
+            )
+
+        # Create event record
+        timestamp = datetime.now(timezone.utc).isoformat()
+        event = {
+            "id": timestamp,  # Use timestamp as ID for simplicity
+            "timestamp": timestamp,
+            "event_type": event_type,
+            "payload": truncated_payload,
+            "status": status,
+        }
+
+        # Append and save
+        self.events.append(event)
+        self._save_events()
+
+        self.logger.debug(f"Appended event: {event_type} (status: {status})")
+        return timestamp
+
+    def list_events(
+        self,
+        event_type: Optional[str] = None,
+        status: Optional[EventStatus] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """List events with optional filtering.
+
+        Args:
+            event_type: Filter by event type (e.g., "autotodo.error")
+            status: Filter by status (e.g., "pending")
+            limit: Maximum number of events to return (most recent first)
+
+        Returns:
+            List of matching events
+        """
+        # Filter events
+        filtered = self.events
+
+        if event_type:
+            filtered = [e for e in filtered if e["event_type"] == event_type]
+
+        if status:
+            filtered = [e for e in filtered if e["status"] == status]
+
+        # Sort by timestamp (most recent first)
+        filtered = sorted(filtered, key=lambda e: e["timestamp"], reverse=True)
+
+        # Apply limit
+        if limit:
+            filtered = filtered[:limit]
+
+        return filtered
+
+    def mark_resolved(self, event_id: str) -> bool:
+        """Mark an event as resolved.
+
+        Args:
+            event_id: Event ID (timestamp)
+
+        Returns:
+            True if event was found and updated
+        """
+        for event in self.events:
+            if event["id"] == event_id:
+                event["status"] = "resolved"
+                event["resolved_at"] = datetime.now(timezone.utc).isoformat()
+                self._save_events()
+                self.logger.debug(f"Marked event resolved: {event_id}")
+                return True
+
+        return False
+
+    def mark_all_resolved(
+        self, event_type: Optional[str] = None, status: EventStatus = "pending"
+    ) -> int:
+        """Mark multiple events as resolved.
+
+        Args:
+            event_type: Optional filter by event type
+            status: Filter by current status (default: "pending")
+
+        Returns:
+            Number of events marked as resolved
+        """
+        count = 0
+        now = datetime.now(timezone.utc).isoformat()
+
+        for event in self.events:
+            # Check filters
+            if event["status"] != status:
+                continue
+            if event_type and event["event_type"] != event_type:
+                continue
+
+            # Mark resolved
+            event["status"] = "resolved"
+            event["resolved_at"] = now
+            count += 1
+
+        if count > 0:
+            self._save_events()
+            self.logger.debug(f"Marked {count} events as resolved")
+
+        return count
+
+    def clear_resolved(self, older_than_days: Optional[int] = None) -> int:
+        """Remove resolved events from the log.
+
+        Args:
+            older_than_days: Only clear events older than N days
+
+        Returns:
+            Number of events removed
+        """
+        if older_than_days:
+            # Calculate cutoff timestamp
+            from datetime import timedelta
+
+            cutoff = datetime.now(timezone.utc) - timedelta(days=older_than_days)
+            cutoff_iso = cutoff.isoformat()
+
+            # Keep events that are NOT resolved OR are newer than cutoff
+            before_count = len(self.events)
+            self.events = [
+                e
+                for e in self.events
+                if e["status"] != "resolved" or e.get("resolved_at", "") > cutoff_iso
+            ]
+            removed = before_count - len(self.events)
+        else:
+            # Remove all resolved events
+            before_count = len(self.events)
+            self.events = [e for e in self.events if e["status"] != "resolved"]
+            removed = before_count - len(self.events)
+
+        if removed > 0:
+            self._save_events()
+            self.logger.debug(f"Cleared {removed} resolved events")
+
+        return removed
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get event log statistics.
+
+        Returns:
+            Dictionary with event counts by status and type
+        """
+        stats = {
+            "total_events": len(self.events),
+            "by_status": {"pending": 0, "resolved": 0, "archived": 0},
+            "by_type": {},
+            "log_file": str(self.log_file),
+        }
+
+        for event in self.events:
+            # Count by status
+            status = event["status"]
+            stats["by_status"][status] = stats["by_status"].get(status, 0) + 1
+
+            # Count by type
+            event_type = event["event_type"]
+            stats["by_type"][event_type] = stats["by_type"].get(event_type, 0) + 1
+
+        return stats
+
+
+# Global instance
+_event_log: Optional[EventLog] = None
+
+
+def get_event_log(log_file: Optional[Path] = None) -> EventLog:
+    """Get the global event log instance.
+
+    Args:
+        log_file: Optional custom log file path
+
+    Returns:
+        EventLog instance
+
+    Note:
+        If log_file is provided and differs from the current instance,
+        a new EventLog is created and replaces the global instance.
+        This allows hooks to use project-specific event logs.
+    """
+    global _event_log
+    if _event_log is None:
+        _event_log = EventLog(log_file)
+    elif log_file is not None and _event_log.log_file != log_file:
+        # Create new instance if log file differs from current
+        _event_log = EventLog(log_file)
+    return _event_log

claude_mpm/services/infrastructure/__init__.py

@@ -11,8 +11,10 @@ Services:
 - LoggingService: Centralized logging with structured output
 - HealthMonitor: System health monitoring and alerting
 - MemoryGuardian: Memory monitoring and process restart management
+- ContextUsageTracker: Token usage tracking across hook invocations
 """
 
+from .context_usage_tracker import ContextUsageState, ContextUsageTracker
 from .logging import LoggingService
 from .monitoring import (
     AdvancedHealthMonitor,
@@ -36,6 +38,8 @@ except ImportError:
 
 __all__ = [
     "AdvancedHealthMonitor",  # For SocketIO server monitoring
+    "ContextUsageState",
+    "ContextUsageTracker",
     "LoggingService",
     # New service-based monitoring API
     "MonitoringAggregatorService",

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%}",
                 },
             }