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

claude_mpm/services/instructions/instruction_cache_service.py

@@ -0,0 +1,374 @@
+"""Instruction cache service for managing assembled PM instruction content.
+
+WHY: Linux systems have ARG_MAX limits (~128-256KB) that prevent passing
+assembled PM instructions (~450KB) via CLI arguments. This service caches
+the complete assembled instruction content to a file that Claude Code can
+load directly.
+
+DESIGN DECISION: Cache FULL assembled instruction content (BASE_PM + PM_INSTRUCTIONS
++ WORKFLOW + capabilities + temporal context) rather than single source file.
+Uses SHA-256 hash-based invalidation to update cache only when assembled content
+changes. This avoids unnecessary file I/O while ensuring cache stays synchronized.
+
+Trade-offs:
+- Performance: Hash computation adds ~1ms overhead but saves 450KB arg passing
+- Complexity: Content-based hashing vs. multi-file dependency tracking
+- Reliability: Hash-based validation is deterministic and platform-independent
+- Flexibility: Caller assembles content, service only caches (separation of concerns)
+
+Alternatives Considered:
+1. File-based tracking: Rejected - can't detect changes in dynamic components
+2. Multi-file dependency tracking: Rejected - complex and error-prone
+3. No caching (always pass via CLI): Rejected due to Linux ARG_MAX limits
+4. Database caching: Rejected as overkill for single-content caching
+
+Extension Points:
+- Compression: Add gzip compression if content sizes grow beyond disk constraints
+- Multiple cache slots: Support caching different agent instruction sets
+- TTL-based invalidation: Add time-based expiration for dynamic content
+"""
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class InstructionCacheService:
+    """Manages cached assembled PM instruction content for file-based loading.
+
+    The cache is stored at `.claude-mpm/PM_INSTRUCTIONS.md` and includes
+    a metadata file `.claude-mpm/PM_INSTRUCTIONS.md.meta` containing:
+    - content_hash: SHA-256 of assembled instruction content
+    - content_size_bytes: Size of cached content in bytes
+    - content_type: Type identifier ("assembled_instruction")
+    - components: List of instruction components that were assembled
+    - cached_at: ISO timestamp of cache creation
+    - version: Cache format version
+
+    Cache Updates:
+    - Triggered during agent deployment or interactive sessions
+    - Accepts pre-assembled instruction content from caller
+    - Only updates if content hash changes
+    - Atomic writes to prevent partial updates
+    - Graceful error handling (deployment continues on cache failure)
+
+    Performance:
+    - Hash computation: O(n) where n = content size, ~1ms for 450KB content
+    - Cache validation: O(1) metadata read + O(n) hash computation
+    - Update operation: O(n) content write, atomic via temp file
+
+    Error Handling:
+    - All methods return result dicts instead of raising exceptions
+    - Errors are logged but don't propagate to callers
+    - Graceful degradation: Cache failures don't break deployments
+    """
+
+    CACHE_DIR = ".claude-mpm"
+    CACHE_FILENAME = "PM_INSTRUCTIONS.md"
+    META_FILENAME = "PM_INSTRUCTIONS.md.meta"
+    CACHE_VERSION = "1.0"
+
+    def __init__(self, project_root: Optional[Path] = None) -> None:
+        """Initialize instruction cache service.
+
+        Args:
+            project_root: Project root directory. If None, uses current directory.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.cache_dir = self.project_root / self.CACHE_DIR
+        self.cache_file = self.cache_dir / self.CACHE_FILENAME
+        self.meta_file = self.cache_dir / self.META_FILENAME
+        self.logger = get_logger(__name__)
+
+    def update_cache(
+        self, instruction_content: str, force: bool = False
+    ) -> Dict[str, Any]:
+        """Update cache with assembled instruction content.
+
+        This method implements atomic cache updates using a temp file strategy:
+        1. Calculate content hash
+        2. Compare with cached hash (if exists)
+        3. If different or force=True, write content to temp file
+        4. Atomically replace cache with temp file
+        5. Write metadata with new hash
+
+        Args:
+            instruction_content: Complete assembled instruction content
+                (BASE_PM + PM_INSTRUCTIONS + WORKFLOW + capabilities + temporal context)
+            force: Force update even if hash matches
+
+        Returns:
+            Result dictionary with:
+            - updated: Whether cache was updated
+            - reason: Why update occurred or was skipped
+            - cache_path: Path to cache file
+            - content_hash: SHA-256 hash of content
+            - content_size_kb: Size of content in KB
+
+        Error Handling:
+            Does NOT raise exceptions - returns error in result dict.
+            This ensures cache failures don't break agent deployments.
+
+        Example:
+            >>> service = InstructionCacheService()
+            >>> assembled = "# BASE_PM\\n...\\n# PM_INSTRUCTIONS\\n..."
+            >>> result = service.update_cache(instruction_content=assembled)
+            >>> if result["updated"]:
+            ...     print(f"Cache updated: {result['reason']}")
+        """
+        try:
+            # Ensure cache directory exists
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+            # Calculate content hash
+            content_hash = self._calculate_hash_from_content(instruction_content)
+
+            # Check if update needed
+            if not force and self.is_cache_valid(instruction_content):
+                return {
+                    "updated": False,
+                    "reason": "cache_valid",
+                    "cache_path": str(self.cache_file),
+                    "content_hash": content_hash,
+                }
+
+            # Write content to cache (atomic operation)
+            temp_file = self.cache_file.with_suffix(".tmp")
+            temp_file.write_text(instruction_content, encoding="utf-8")
+            temp_file.replace(self.cache_file)
+
+            # Write metadata
+            self._write_metadata(content_hash, len(instruction_content))
+
+            self.logger.info(f"Updated instruction cache: {self.cache_file}")
+
+            return {
+                "updated": True,
+                "reason": "content_changed" if not force else "forced",
+                "cache_path": str(self.cache_file),
+                "content_hash": content_hash,
+                "content_size_kb": len(instruction_content) / 1024,
+            }
+
+        except Exception as e:
+            self.logger.error(f"Failed to update instruction cache: {e}")
+            return {
+                "updated": False,
+                "reason": "error",
+                "error": str(e),
+                "cache_path": str(self.cache_file),
+            }
+
+    def get_cache_path(self) -> Path:
+        """Get path to cache file.
+
+        Returns:
+            Path to PM_INSTRUCTIONS.md cache
+
+        Example:
+            >>> service = InstructionCacheService()
+            >>> cache_path = service.get_cache_path()
+            >>> print(cache_path)  # .claude-mpm/PM_INSTRUCTIONS.md
+        """
+        return self.cache_file
+
+    def is_cache_valid(self, instruction_content: str) -> bool:
+        """Check if cache matches current assembled content.
+
+        Validation checks:
+        1. Cache file exists
+        2. Metadata file exists
+        3. Content hash matches cached hash
+
+        Args:
+            instruction_content: Current assembled instruction to validate against
+
+        Returns:
+            True if cache exists and hash matches content
+
+        Example:
+            >>> service = InstructionCacheService()
+            >>> assembled = "# BASE_PM\\n...\\n# PM_INSTRUCTIONS\\n..."
+            >>> if not service.is_cache_valid(assembled):
+            ...     service.update_cache(assembled)
+        """
+        try:
+            if not self.cache_file.exists() or not self.meta_file.exists():
+                return False
+
+            content_hash = self._calculate_hash_from_content(instruction_content)
+            cached_hash = self._get_cached_hash()
+
+            return content_hash == cached_hash
+
+        except Exception as e:
+            self.logger.debug(f"Cache validation failed: {e}")
+            return False
+
+    def invalidate_cache(self) -> bool:
+        """Invalidate cache by removing cache files.
+
+        This method removes both the cache file and metadata file,
+        forcing a fresh cache creation on next update.
+
+        Returns:
+            True if cache was invalidated (files removed), False otherwise
+
+        Example:
+            >>> service = InstructionCacheService()
+            >>> if service.invalidate_cache():
+            ...     print("Cache cleared")
+        """
+        try:
+            removed = False
+            if self.cache_file.exists():
+                self.cache_file.unlink()
+                removed = True
+            if self.meta_file.exists():
+                self.meta_file.unlink()
+                removed = True
+
+            if removed:
+                self.logger.info("Invalidated instruction cache")
+
+            return removed
+
+        except Exception as e:
+            self.logger.error(f"Failed to invalidate cache: {e}")
+            return False
+
+    def get_cache_info(self) -> Dict[str, Any]:
+        """Get information about current cache state.
+
+        Returns cache metadata including existence, sizes, and timestamps
+        for debugging and monitoring. Note: cannot validate cache without
+        current content, so cache_valid is always None.
+
+        Returns:
+            Dictionary with cache metadata:
+            - cache_exists: Whether cache file exists
+            - cache_path: Path to cache file
+            - cache_valid: Always None (validation requires current content)
+            - content_type: Type of cached content ("assembled_instruction")
+            - cache_size_kb: Cache file size in KB (if exists)
+            - cached_at: Cache creation timestamp (if exists)
+            - content_hash: Content hash (if cache exists)
+            - content_size_bytes: Cached content size in bytes (if exists)
+            - components: List of instruction components (if exists)
+
+        Example:
+            >>> service = InstructionCacheService()
+            >>> info = service.get_cache_info()
+            >>> print(f"Cache exists: {info['cache_exists']}")
+            >>> print(f"Size: {info.get('cache_size_kb', 0):.1f}KB")
+        """
+        info: Dict[str, Any] = {
+            "cache_exists": self.cache_file.exists(),
+            "cache_path": str(self.cache_file),
+            "cache_valid": None,  # Can't validate without current content
+            "content_type": "assembled_instruction",
+        }
+
+        try:
+            if self.cache_file.exists():
+                info["cache_size_kb"] = self.cache_file.stat().st_size / 1024
+
+                # Load metadata
+                if self.meta_file.exists():
+                    meta = json.loads(self.meta_file.read_text())
+                    info.update(
+                        {
+                            "cached_at": meta.get("cached_at"),
+                            "content_hash": meta.get("content_hash"),
+                            "content_size_bytes": meta.get("content_size_bytes"),
+                            "components": meta.get("components", []),
+                            "cache_version": meta.get("version"),
+                        }
+                    )
+
+        except Exception as e:
+            info["error"] = str(e)
+
+        return info
+
+    def _calculate_hash_from_content(self, content: str) -> str:
+        """Calculate SHA-256 hash of content string.
+
+        Args:
+            content: String content to hash
+
+        Returns:
+            Hex digest of SHA-256 hash
+
+        Performance:
+            - Time complexity: O(n) where n = content size
+            - Memory usage: O(1) - hash computed incrementally
+        """
+        sha256 = hashlib.sha256()
+        sha256.update(content.encode("utf-8"))
+        return sha256.hexdigest()
+
+    def _get_cached_hash(self) -> Optional[str]:
+        """Get cached content hash from metadata.
+
+        Returns:
+            Cached hash or None if not available
+        """
+        try:
+            if not self.meta_file.exists():
+                return None
+
+            meta = json.loads(self.meta_file.read_text())
+            return meta.get("content_hash")
+
+        except Exception as e:
+            self.logger.debug(f"Failed to read cached hash: {e}")
+            return None
+
+    def _write_metadata(self, content_hash: str, content_size: int) -> None:
+        """Write cache metadata file.
+
+        Metadata includes:
+        - version: Cache format version (for future compatibility)
+        - content_type: Type identifier ("assembled_instruction")
+        - content_hash: SHA-256 hash of assembled content
+        - content_size_bytes: Size of cached content in bytes
+        - components: List of instruction components that were assembled
+        - cached_at: ISO 8601 timestamp with UTC timezone
+
+        Args:
+            content_hash: SHA-256 hash of assembled content
+            content_size: Size of content in bytes
+
+        Example metadata:
+            {
+                "version": "1.0",
+                "content_type": "assembled_instruction",
+                "content_hash": "abc123...",
+                "content_size_bytes": 450000,
+                "components": ["BASE_PM.md", "PM_INSTRUCTIONS.md", ...],
+                "cached_at": "2025-11-30T15:30:00Z"
+            }
+        """
+        metadata = {
+            "version": self.CACHE_VERSION,
+            "content_type": "assembled_instruction",
+            "components": [
+                "BASE_PM.md",
+                "PM_INSTRUCTIONS.md",
+                "WORKFLOW.md",
+                "agent_capabilities",
+                "temporal_context",
+            ],
+            "content_hash": content_hash,
+            "content_size_bytes": content_size,
+            "cached_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+        self.meta_file.write_text(json.dumps(metadata, indent=2))

claude_mpm/services/local_ops/__init__.py

@@ -0,0 +1,155 @@
+"""
+Local Operations Service Package
+=================================
+
+WHY: Provides process management and health monitoring capabilities for local
+development deployments. This package implements the core infrastructure needed
+by the local-ops-agent to spawn, track, manage, and monitor background processes.
+
+DESIGN DECISION: Organized as a service package under services/ to integrate
+with the existing service architecture and dependency injection system.
+
+ARCHITECTURE:
+- StateManager: Persistent deployment state tracking
+- ProcessManager: Process lifecycle management with isolation
+- HealthCheckManager: Three-tier health monitoring (HTTP, process, resource)
+- HealthChecks: HTTP, process, and resource health check implementations
+- CrashDetector: Crash detection via health status monitoring
+- RestartPolicy: Intelligent restart policies with exponential backoff
+- RestartManager: Auto-restart orchestration with circuit breaker
+- MemoryLeakDetector: Proactive memory leak detection using trend analysis
+- LogMonitor: Real-time log file monitoring for error patterns
+- ResourceMonitor: Comprehensive resource exhaustion prevention
+- Data Models: Process status, deployment state, health status, restart history,
+              stability metrics (memory trends, log matches, resource usage)
+- Interfaces: ILocalProcessManager, IDeploymentStateManager, IHealthCheckManager,
+             ICrashDetector, IRestartPolicy, IRestartManager, IMemoryLeakDetector,
+             ILogMonitor, IResourceMonitor
+
+USAGE:
+    from claude_mpm.services.local_ops import (
+        LocalProcessManager,
+        DeploymentStateManager,
+        HealthCheckManager,
+        StartConfig,
+        HealthStatus,
+    )
+    from claude_mpm.core.enums import ServiceState
+
+    # Initialize managers
+    state_manager = DeploymentStateManager(".claude-mpm/deployment-state.json")
+    process_manager = LocalProcessManager(state_manager)
+    health_manager = HealthCheckManager(process_manager, check_interval=30)
+
+    # Start a process
+    config = StartConfig(
+        command=["npm", "run", "dev"],
+        working_directory="/path/to/project",
+        port=3000
+    )
+    deployment = process_manager.start(config)
+
+    # Check health
+    health = health_manager.check_health(deployment.deployment_id)
+
+    # Start background monitoring
+    health_manager.start_monitoring()
+
+Note: ProcessStatus has been consolidated into ServiceState (core.enums) as of Phase 3A Batch 24.
+"""
+
+# Re-export data models and interfaces for convenience
+from claude_mpm.core.enums import HealthStatus
+from claude_mpm.services.core.interfaces.health import IHealthCheck, IHealthCheckManager
+from claude_mpm.services.core.interfaces.process import (
+    IDeploymentStateManager,
+    ILocalProcessManager,
+)
+from claude_mpm.services.core.interfaces.restart import (
+    ICrashDetector,
+    IRestartManager,
+    IRestartPolicy,
+)
+from claude_mpm.services.core.interfaces.stability import (
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IResourceMonitor,
+)
+from claude_mpm.services.core.models.health import DeploymentHealth, HealthCheckResult
+from claude_mpm.services.core.models.process import (
+    PROTECTED_PORT_RANGES,
+    DeploymentState,
+    ProcessInfo,
+    ProcessStatus,
+    StartConfig,
+    is_port_protected,
+)
+from claude_mpm.services.core.models.restart import (
+    CircuitBreakerState,
+    RestartAttempt,
+    RestartConfig,
+    RestartHistory,
+)
+from claude_mpm.services.core.models.stability import (
+    LogPatternMatch,
+    MemoryTrend,
+    ResourceUsage,
+)
+
+# Import service implementations
+from .health_manager import HealthCheckManager
+from .log_monitor import LogMonitor
+from .memory_leak_detector import MemoryLeakDetector
+from .process_manager import LocalProcessManager, PortConflictError, ProcessSpawnError
+from .resource_monitor import ResourceMonitor
+from .state_manager import DeploymentStateManager, StateCorruptionError
+from .unified_manager import UnifiedLocalOpsManager
+
+__all__ = [
+    "PROTECTED_PORT_RANGES",
+    # Data models - Restart
+    "CircuitBreakerState",
+    "CrashDetector",
+    "DeploymentHealth",
+    "DeploymentState",
+    # Service implementations
+    "DeploymentStateManager",
+    "HealthCheckManager",
+    "HealthCheckResult",
+    # Data models - Health
+    "HealthStatus",
+    "ICrashDetector",
+    # Interfaces
+    "IDeploymentStateManager",
+    "IHealthCheck",
+    "IHealthCheckManager",
+    "ILocalProcessManager",
+    "ILogMonitor",
+    "IMemoryLeakDetector",
+    "IResourceMonitor",
+    "IRestartManager",
+    "IRestartPolicy",
+    "LocalProcessManager",
+    "LogMonitor",
+    "LogPatternMatch",
+    "MemoryLeakDetector",
+    # Data models - Stability
+    "MemoryTrend",
+    "PortConflictError",
+    "ProcessInfo",
+    "ProcessSpawnError",
+    "ProcessStatus",
+    # Data models - Process
+    "ResourceMonitor",
+    "ResourceUsage",
+    "RestartAttempt",
+    "RestartConfig",
+    "RestartHistory",
+    "RestartManager",
+    "RestartPolicy",
+    "StartConfig",
+    # Exceptions
+    "StateCorruptionError",
+    "UnifiedLocalOpsManager",
+    "is_port_protected",
+]