claude-mpm 4.21.0__py3-none-any.whl → 5.0.2__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

@@ -60,10 +60,7 @@ Note: ProcessStatus has been consolidated into ServiceState (core.enums) as of P
 
 # 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.health import IHealthCheck, IHealthCheckManager
 from claude_mpm.services.core.interfaces.process import (
     IDeploymentStateManager,
     ILocalProcessManager,
@@ -78,10 +75,7 @@ from claude_mpm.services.core.interfaces.stability import (
     IMemoryLeakDetector,
     IResourceMonitor,
 )
-from claude_mpm.services.core.models.health import (
-    DeploymentHealth,
-    HealthCheckResult,
-)
+from claude_mpm.services.core.models.health import DeploymentHealth, HealthCheckResult
 from claude_mpm.services.core.models.process import (
     PROTECTED_PORT_RANGES,
     DeploymentState,
@@ -106,11 +100,7 @@ from claude_mpm.services.core.models.stability import (
 from .health_manager import HealthCheckManager
 from .log_monitor import LogMonitor
 from .memory_leak_detector import MemoryLeakDetector
-from .process_manager import (
-    LocalProcessManager,
-    PortConflictError,
-    ProcessSpawnError,
-)
+from .process_manager import LocalProcessManager, PortConflictError, ProcessSpawnError
 from .resource_monitor import ResourceMonitor
 from .state_manager import DeploymentStateManager, StateCorruptionError
 from .unified_manager import UnifiedLocalOpsManager

claude_mpm/services/local_ops/health_checks/__init__.py

@@ -14,9 +14,7 @@ ARCHITECTURE:
 """
 
 from claude_mpm.services.local_ops.health_checks.http_check import HttpHealthCheck
-from claude_mpm.services.local_ops.health_checks.process_check import (
-    ProcessHealthCheck,
-)
+from claude_mpm.services.local_ops.health_checks.process_check import ProcessHealthCheck
 from claude_mpm.services.local_ops.health_checks.resource_check import (
     ResourceHealthCheck,
 )

claude_mpm/services/local_ops/health_manager.py

@@ -43,10 +43,7 @@ from claude_mpm.core.enums import HealthStatus
 from claude_mpm.services.core.base import SyncBaseService
 from claude_mpm.services.core.interfaces.health import IHealthCheckManager
 from claude_mpm.services.core.interfaces.process import ILocalProcessManager
-from claude_mpm.services.core.models.health import (
-    DeploymentHealth,
-    HealthCheckResult,
-)
+from claude_mpm.services.core.models.health import DeploymentHealth, HealthCheckResult
 from claude_mpm.services.local_ops.health_checks import (
     HttpHealthCheck,
     ProcessHealthCheck,

claude_mpm/services/local_ops/process_manager.py

@@ -187,7 +187,7 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
             # Check if process is still running
             if process.poll() is not None:
                 # Process died immediately
-                stdout, stderr = process.communicate()
+                _stdout, stderr = process.communicate()
                 error_msg = stderr.decode("utf-8", errors="replace") if stderr else ""
                 raise ProcessSpawnError(
                     f"Process died immediately. Exit code: {process.returncode}. "

claude_mpm/services/local_ops/resource_monitor.py

@@ -102,7 +102,7 @@ class ResourceMonitor(SyncBaseService, IResourceMonitor):
         self._initialized = True
         self.log_info(
             f"Resource monitor initialized "
-            f"(fd_threshold={self.fd_threshold_percent*100:.0f}%, "
+            f"(fd_threshold={self.fd_threshold_percent * 100:.0f}%, "
             f"thread_threshold={self.thread_threshold}, "
             f"connection_threshold={self.connection_threshold}, "
             f"disk_threshold={self.disk_threshold_mb}MB)"
@@ -304,7 +304,7 @@ class ResourceMonitor(SyncBaseService, IResourceMonitor):
             return 0
 
         try:
-            soft_limit, hard_limit = resource_module.getrlimit(
+            soft_limit, _hard_limit = resource_module.getrlimit(
                 resource_module.RLIMIT_NOFILE
             )
             return soft_limit

claude_mpm/services/mcp_gateway/config/configuration.py

@@ -215,7 +215,7 @@ class MCPConfiguration(BaseMCPService, IMCPConfiguration):
                     current[part] = {}
                 elif not isinstance(current[part], dict):
                     self.log_warning(
-                        f"Cannot override non-dict config at {'.'.join(config_path[:i+1])}"
+                        f"Cannot override non-dict config at {'.'.join(config_path[: i + 1])}"
                     )
                     break
                 current = current[part]

claude_mpm/services/mcp_gateway/server/mcp_gateway.py

@@ -21,12 +21,7 @@ from typing import Any, Callable, Dict, List, Optional, Union
 
 # Import from the official MCP package
 from mcp.server import Server
-from mcp.types import (
-    EmbeddedResource,
-    ImageContent,
-    TextContent,
-    Tool,
-)
+from mcp.types import EmbeddedResource, ImageContent, TextContent, Tool
 
 from claude_mpm.services.mcp_gateway.core.base import BaseMCPService
 from claude_mpm.services.mcp_gateway.core.interfaces import (

claude_mpm/services/mcp_gateway/server/stdio_server.py

@@ -65,7 +65,6 @@ def apply_backward_compatibility_patches():
                         and hasattr(request, "params")
                         and request.params is not None
                     ):
-
                         # Convert params to dict to check for clientInfo
                         params_dict = request.params
                         if hasattr(params_dict, "model_dump"):
@@ -542,7 +541,6 @@ class SimpleMCPServer:
 
                         result = f"Python: {sys.version}"
                     elif info_type == "cwd":
-
                         result = f"Working Directory: {Path.cwd()}"
                     elif info_type == "all":
                         import datetime

claude_mpm/services/mcp_gateway/tools/document_summarizer.py

@@ -73,7 +73,7 @@ class LRUCache:
             if not self.cache:
                 break
             # Remove least recently used item
-            removed_key, removed_value = self.cache.popitem(last=False)
+            _removed_key, removed_value = self.cache.popitem(last=False)
             self.current_memory -= removed_value.get("size_bytes", 0)
 
         # Add new item

claude_mpm/services/mcp_gateway/tools/kuzu_memory_service.py

@@ -199,7 +199,9 @@ class KuzuMemoryService(BaseToolAdapter):
         try:
             if action == "store":
                 result = await self.store_memory(
-                    params.get("content"), params.get("tags"), {}  # metadata
+                    params.get("content"),
+                    params.get("tags"),
+                    {},  # metadata
                 )
             elif action == "recall":
                 result = await self.recall_memories(
@@ -213,7 +215,9 @@ class KuzuMemoryService(BaseToolAdapter):
                 )
             elif action == "context":
                 result = await self.get_context(
-                    params.get("query", ""), 2, True  # depth  # include_related
+                    params.get("query", ""),
+                    2,
+                    True,  # depth  # include_related
                 )
             else:
                 return MCPToolResult(success=False, error=f"Unknown action: {action}")

claude_mpm/services/memory/failure_tracker.py

@@ -29,6 +29,7 @@ Example flow:
 
 import logging
 import re
+import threading
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Dict, List, Optional, Tuple
@@ -536,6 +537,7 @@ class FailureTracker:
 
 # Singleton instance for session-level tracking
 _tracker_instance: Optional[FailureTracker] = None
+_tracker_lock = threading.Lock()
 
 
 def get_failure_tracker() -> FailureTracker:
@@ -544,13 +546,23 @@ def get_failure_tracker() -> FailureTracker:
     WHY: Session-level tracking requires a singleton to maintain state
     across multiple hook invocations during the same session.
 
+    Thread-safe implementation using double-checked locking pattern to
+    prevent race conditions during concurrent initialization.
+
     Returns:
         The FailureTracker singleton instance
     """
     global _tracker_instance
-    if _tracker_instance is None:
-        _tracker_instance = FailureTracker()
-    return _tracker_instance
+
+    # Fast path - check without lock
+    if _tracker_instance is not None:
+        return _tracker_instance
+
+    # Slow path - acquire lock and double-check
+    with _tracker_lock:
+        if _tracker_instance is None:
+            _tracker_instance = FailureTracker()
+        return _tracker_instance
 
 
 def reset_failure_tracker() -> None:
@@ -558,6 +570,9 @@ def reset_failure_tracker() -> None:
 
     WHY: Tests need to reset state between runs. Also useful for
     explicitly starting a new tracking session.
+
+    Thread-safe implementation ensures proper cleanup.
     """
     global _tracker_instance
-    _tracker_instance = None
+    with _tracker_lock:
+        _tracker_instance = None

claude_mpm/services/memory/optimizer.py

@@ -618,7 +618,7 @@ class MemoryOptimizer(LoggerMixin):
                     )
 
                 # Check for similar items
-                consolidated, consolidated_count = self._consolidate_similar_items(
+                _consolidated, consolidated_count = self._consolidate_similar_items(
                     unique_points
                 )
                 if consolidated_count > 0:

claude_mpm/services/model/model_router.py

@@ -266,7 +266,7 @@ class ModelRouter(BaseService, IModelRouter):
 
         # Route based on strategy
         if self.strategy == RoutingStrategy.CLAUDE_ONLY:
-            return await self._route_to_claude(content, task, model, **kwargs)
+            return await self._route_to_claude(content, task, model=model, **kwargs)
 
         if self.strategy in (
             RoutingStrategy.OLLAMA_ONLY,
@@ -275,13 +275,13 @@ class ModelRouter(BaseService, IModelRouter):
             return await self._route_to_ollama(
                 content,
                 task,
-                model,
+                model=model,
                 require_success=True,
                 **kwargs,
             )
 
         # AUTO strategy
-        return await self._route_auto(content, task, model, **kwargs)
+        return await self._route_auto(content, task, model=model, **kwargs)
 
     async def _route_auto(
         self,
@@ -308,7 +308,7 @@ class ModelRouter(BaseService, IModelRouter):
             response = await self._route_to_ollama(
                 content,
                 task,
-                model,
+                model=model,
                 require_success=False,
                 **kwargs,
             )
@@ -325,7 +325,7 @@ class ModelRouter(BaseService, IModelRouter):
         # Ollama unavailable or failed - fallback to Claude
         if self.fallback_enabled:
             self.log_info("Falling back to Claude")
-            return await self._route_to_claude(content, task, model, **kwargs)
+            return await self._route_to_claude(content, task, model=model, **kwargs)
         return self._create_error_response(
             task,
             model,
@@ -356,8 +356,7 @@ class ModelRouter(BaseService, IModelRouter):
         if require_success and not await self.ollama_provider.is_available():
             if self.strategy == RoutingStrategy.PRIVACY_FIRST:
                 error_msg = (
-                    "Ollama not available. Privacy mode enabled - "
-                    "not sending to cloud."
+                    "Ollama not available. Privacy mode enabled - not sending to cloud."
                 )
             else:
                 error_msg = "Ollama not available and required by configuration"
@@ -368,7 +367,7 @@ class ModelRouter(BaseService, IModelRouter):
         self._route_count["ollama"] += 1
 
         return await self.ollama_provider.analyze_content(
-            content, task, model, **kwargs
+            content, task, model=model, **kwargs
         )
 
     async def _route_to_claude(
@@ -394,7 +393,7 @@ class ModelRouter(BaseService, IModelRouter):
         self._route_count["claude"] += 1
 
         return await self.claude_provider.analyze_content(
-            content, task, model, **kwargs
+            content, task, model=model, **kwargs
         )
 
     def _create_error_response(